Skip to main content

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.

BlooBank organizes all financial movement around the Payment Order — a single resource type that represents any operation that moves money, in either direction, through any supported network. There are no separate “Pix-In” or “Pix-Out” resources; both are payment orders with a different direction field.

​
The model

Every payment order has:
FieldNotes
directionIN (cash-in) or OUT (cash-out).
networkThe payment network (currently br.gov.bcb.pix).
amountInteger minor units (e.g., cents for BRL).
currencyISO 4217 code.
instrumentDiscriminated union — five PIX variants today. See Instrument types.
idempotencyKeyCaller-supplied; makes the create safe to retry. See Idempotency.
statusLifecycle state. See Payment lifecycle.
metadataFree-form caller-supplied tags.

​
Direction defines the workflow

DirectionWorkflow
INOne-step. POST creates the order, the platform immediately submits it to the provider, and the order starts in PENDING. The payer settles when they pay the QR/key.
OUTTwo-step. POST creates the order in AWAITING_APPROVAL. A subsequent PUT .../approve submits it to the provider; PENDING follows. This gates outbound flows behind an explicit human (or automated) approval.
The two-step OUT flow is deliberate: outbound payments leave your balance, so a separate approval step lets you implement dual-control, fraud checks, or business-rule validation before money leaves the wallet.

​
Identifiers

Every payment order carries three identifiers:

id

Server-assigned at creation: ord_3KpFvBwYzNqMxA7eHbRdJ. Immutable. Use as your database key.

idempotencyKey

Caller-supplied at creation. Bound to the (wallet, idempotencyKey) tuple. Makes the create safe to retry.

endToEndId

PIX-network-assigned end-to-end identifier. Populated after the provider returns it (typically on settlement).
For reconciliation against external systems, endToEndId is what the PIX network uses. For your internal records, id is the BlooBank-side identifier and idempotencyKey is your client-side identifier.

​
A complete example — inbound (cash-in)

1

Generate an idempotencyKey for the invoice

Persist it locally before calling the API.
idempotencyKey = "invoice-2026-0184"
2

Create the payment order

POST /wallets/production-main/paymentOrders HTTP/1.1
Content-Type: application/json

{
  "direction":      "IN",
  "network":        "br.gov.bcb.pix",
  "idempotencyKey": "invoice-2026-0184",
  "amount":         25000,
  "currency":       "BRL",
  "instrument":     { "type": "PIX_CASH_IN_EMV_DYNAMIC", "expiresIn": 86400 }
}
Response: 201 Created with status: "PENDING" and the instrument populated (qrcode, copypaste, expiresAt).
3

Render the QR code to your customer

The instrument.qrcode and instrument.copypaste fields contain provider-rendered PIX payloads. Display them; the customer pays via their bank app.
4

Wait for the webhook (or poll)

When the customer pays, the order transitions to SUCCESS and a webhook fires. See Webhooks overview.
5

Reconcile

The wallet balance reflects the inbound funds. The endToEndId is now populated on the order.

​
A complete example — outbound (cash-out)

1

Pre-flight balance check

GET /wallets/production-main/balance — verify available.value >= amount.
2

Create the payment order

POST /wallets/production-main/paymentOrders HTTP/1.1
Content-Type: application/json

{
  "direction":      "OUT",
  "network":        "br.gov.bcb.pix",
  "idempotencyKey": "payout-2026-0309",
  "amount":         15000,
  "currency":       "BRL",
  "instrument":     {
    "type":     "PIX_CASH_OUT_KEY",
    "keyType":  "CPF",
    "keyValue": "12345678901"
  }
}
Response: 201 Created with status: "AWAITING_APPROVAL". No money has moved yet.
3

Approve

PUT /wallets/production-main/paymentOrders/ord_3Kp.../approve HTTP/1.1
Response: 200 OK with status: "PENDING". The order is now submitted to the PIX network. locked increases by the amount.
4

Or cancel (alternative to approval)

PUT /wallets/production-main/paymentOrders/ord_3Kp.../cancel HTTP/1.1
Response: 200 OK with status: "CANCELED". The order never reaches the provider.
5

Wait for completion via webhook

On settlement: status: "SUCCESS", locked decreases, amount decreases (the funds left your wallet).

​
Amounts

All amounts are integers in minor units:
DisplayAPI amount
R$ 1.00100
R$ 250.0025000
R$ 1,234.56123456
See Amounts & currency.

​
Idempotency

For payment orders, always supply an idempotencyKey. Retrying without one creates a duplicate payment. The pattern:
  1. Persist the key in your local database before calling the API.
  2. Include it in the create body.
  3. On any network failure, retry with the same key.
  4. Use the API response to reconcile your local state.
See Idempotency for the full pattern.

​
Networks today

NetworkCodeDirectionNotes
Pix (Brazil)br.gov.bcb.pixIN / OUTThe current network for both directions.
Future networks may be added (Tron, Solana, Bitcoin, Ethereum are reserved in the ProviderNetwork enum). The direction + network + instrument.type triple determines which provider handles the order.

​
Next

Lifecycle

The state machine: AWAITING_APPROVAL → PENDING → PROCESSING → final.

Instrument types

The five PIX variants and when to use each.

Pix cash-in tutorial

End-to-end inbound flow.

Pix cash-out tutorial

End-to-end outbound flow with approval.