Skip to main content
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:

​
Direction defines the workflow

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.
2

Create the payment order

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

Response: 201 Created with status: "AWAITING_APPROVAL". No money has moved yet.
3

Approve

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)

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: 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

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.