The BlooBank Transactions Engine API is the canonical entry point for moving money on the BlooBank platform. This page sketches the surrounding architecture so you can reason about where your integration sits in the bigger picture.Documentation Index
Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt
Use this file to discover all available pages before exploring further.
The integration surface
You will work with two control planes:Transactions Engine API
REST API. Provision wallets, create and approve payment orders, query state. The subject of this documentation.
Webhooks
Server-pushed events. Receive lifecycle notifications for payment orders so your reconciliation does not depend on polling.
secp256k1 signatures over canonical request strings. The same credential identifies your service on the API and authenticates webhook deliveries (in the reverse direction).
Request path
| Step | What happens |
|---|---|
| 1 | Your service signs the request with your ECDSA private key and sends it over HTTPS. |
| 2–3 | The platform verifies the signature, replay window, and RBAC grants. |
| 4–5 | The Transactions Engine validates the request and submits to the underlying provider. |
| 6 | The provider returns a settlement result (synchronous or asynchronous). |
| 7–8 | The Engine emits a webhook event; your service verifies the delivery signature and reconciles. |
Boundaries you must reason about
These boundaries shape your integration design — choose where each lives in your stack.| Boundary | Owned by | Notes |
|---|---|---|
| Private key | You | Never leaves your environment. Stored in a secret manager. See Generate your keys. |
| Public key | BlooBank | Registered during onboarding. Used by the platform to verify your signatures. |
| Request signing | You | Build the canonical string and sign per the Access Protocol. |
| Webhook signature verification | You | Verify every delivery before acting on it. See Verifying signatures. |
| Idempotency | You | Supply an idempotencyKey on every retryable create. See Idempotency. |
| Authorization (RBAC) | BlooBank | Enforced server-side per credential. Errors surface as RBAC_DENY (HTTP 403). |
| Settlement | Provider network | PIX or future networks. BlooBank abstracts the protocol but settlement timing depends on the network. |
Reliability model
- API requests — strongly consistent. A
201 Createdresponse means the resource is persisted. - Payment-order settlement — asynchronous. A
201 CreatedonPOST .../paymentOrdersmeans the order is accepted, not settled. The order moves through lifecycle states and finalizes when the provider confirms. - Webhook delivery — at-least-once. Events can be redelivered. Idempotent consumers are required — see Best practices.
Next
Resources & naming
How resources are identified and versioned.
Authentication
The Access Protocol — your entry point.