BlooBank API Documentation

Outbound flows differ from inbound in one important way: they are two-step. POST creates the order in AWAITING_APPROVAL; a subsequent PUT .../approve submits it to the PIX network. The pause between the two is where you implement dual-control, balance checks, or anti-fraud rules. For other instrument types, see Instrument types. For the underlying state machine, see Payment lifecycle.

The flow

Generate an idempotencyKey for the operation

Tie it to the business intent — typically the payout id, prefixed unambiguously.

idempotencyKey = "payout-2026-0309"

Persist locally before the API call.

Pre-flight balance check

Outbound orders are denied if available < amount. Check first to fail fast.

GET /wallets/production-main/balance HTTP/1.1

Compare available.value to your intended amount. If insufficient, do not even attempt the create — surface the shortage to the operator.

Create the order (AWAITING_APPROVAL)

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"
  },
  "metadata": {
    "payoutId": "2026-0309"
  }
}

Response: 201 Created with status: "AWAITING_APPROVAL". No money has moved yet — the wallet’s available is unchanged.

{
  "id":              "ord_4LqGwCxZzOrNyB8fHcSeK",
  "status":          "AWAITING_APPROVAL",
  "direction":       "OUT",
  "network":         "br.gov.bcb.pix",
  "amount":          15000,
  "currency":        "BRL",
  "idempotencyKey":  "payout-2026-0309",
  "instrument": {
    "type":     "PIX_CASH_OUT_KEY",
    "keyType":  "CPF",
    "keyValue": "12345678901"
  },
  "createdAt":  "2026-01-15T11:00:00.000Z"
}

Approve to submit (or cancel to drop)

To approve and submit:

PUT /wallets/production-main/paymentOrders/ord_4Lq.../approve HTTP/1.1

Response: 200 OK with status: "PENDING". The PIX network is now processing. The wallet’s locked increases by the order amount.To cancel before submission:

PUT /wallets/production-main/paymentOrders/ord_4Lq.../cancel HTTP/1.1

Response: 200 OK with status: "CANCELED". The order never reaches the PIX network. available and locked are unchanged.Both transitions require the order to be in AWAITING_APPROVAL — any other state returns PAYMENT_ORDER_NOT_AWAITING_APPROVAL (for approve) or PAYMENT_ORDER_INVALID_STATE (for cancel).

Wait for settlement via webhook

On settlement:

{
  "event":      "payment_order.success",
  "messageId":  "msg_9I3lQrS0aU5yWn",
  "occurredAt": "2026-01-15T11:00:03.214Z",
  "data": {
    "id":              "ord_4LqGwCxZzOrNyB8fHcSeK",
    "status":          "SUCCESS",
    "direction":       "OUT",
    "amount":          15000,
    "currency":        "BRL",
    "idempotencyKey":  "payout-2026-0309",
    "instrument": {
      "type":       "PIX_CASH_OUT_KEY",
      "keyType":    "CPF",
      "keyValue":   "12345678901",
      "endToEndId": "E60746948202601151100001B2C3D4E",
      "creditorAccount": {
        "ispb":                 "60746948",
        "bankCode":             "237",
        "bankName":             "Banco Bradesco S.A.",
        "agencyNumber":         "1234",
        "accountType":          "CHECKING_ACCOUNT",
        "accountNumber":        "987654-3",
        "accountOwnerName":     "Recipient Name",
        "accountOwnerDocument": "12345678901"
      }
    },
    "processedAt": "2026-01-15T11:00:03.214Z"
  }
}

locked decreases; amount decreases by the order amount.On failure (payment_order.failed event), locked decreases and amount is unchanged — funds are released:

{
  "event": "payment_order.failed",
  "data": {
    "id": "ord_4Lq...",
    "status": "FAILED",
    "errorCode":    "INSUFFICIENT_FUNDS",
    "errorMessage": "Insufficient available balance to complete this transfer."
  }
}

Dual control — common patterns

AWAITING_APPROVAL is the design hook for human or automated approval gates. Two common patterns:

Pattern A — operator review

Operators see all AWAITING_APPROVAL orders in a dashboard, click “approve” or “cancel” individually. Use this when each payment carries enough variance that human judgment is valuable.

GET /wallets/production-main/paymentOrders?filter=status%3DAWAITING_APPROVAL&order_by=createdAt&page_size=50 HTTP/1.1

Pattern B — automated rule engine

A separate service consumes new orders (via webhook on payment_order.created), applies business rules (limits, anti-fraud, beneficiary checks), and calls approve or cancel automatically. Use this for high-volume, low-variance flows like payroll. The benefit of separating create from approve: the approver service can use a different credential with stricter RBAC than the creator service. The first service can create payouts at scale; only the second can submit them.

Recipient resolution

For PIX_CASH_OUT_KEY, the recipient account is resolved by the provider after submission. You do not need to know the bank or account number — just the PIX key. The resolved creditorAccount appears in the order response after settlement. If the key cannot be resolved (recipient does not exist, key is malformed), the order finalizes as FAILED with errorCode: "RECIPIENT_INVALID". The funds are never debited from your wallet.

Cancel after approve

Once you call approve, the order moves to PENDING and you can no longer cancel it. The order will reach a final state (SUCCESS or FAILED) on the PIX network’s timeline — typically seconds. If you must reverse an outbound payment after it settled, you need a separate refund flow (request via the PIX network), not a cancel.

Reconciliation

Per outbound order, your local record should accumulate:

Field	Source
Order id	API response on create
Idempotency key	Generated by you, stored locally
Status timeline	`AWAITING_APPROVAL` → `PENDING` → `PROCESSING` → final
End-to-end id	Webhook `SUCCESS` payload
Resolved creditor account	Webhook `SUCCESS` payload
Error code	Webhook `FAILED` payload

Match payout-2026-0309 (your local id) to ord_4Lq... (BlooBank id) to E60746948... (PIX network id) — three layers of identity that collectively define the reconciliation chain.

Common errors

Reason	Cause	Fix
`INSUFFICIENT_FUNDS` (in order `errorCode`)	`available` was less than `amount` at submit time.	Check balance first; do not bypass the gate.
`RECIPIENT_INVALID` (in order `errorCode`)	PIX key could not be resolved or account is closed.	Verify the key value with the recipient.
`PAYMENT_ORDER_NOT_AWAITING_APPROVAL` (HTTP 422)	`approve` called on an order not in `AWAITING_APPROVAL`.	Verify state via `GET` first.
`PAYMENT_ORDER_INVALID_STATE` (HTTP 422)	`cancel` called on an order not in `AWAITING_APPROVAL`.	Once approved, the order cannot be canceled — wait for terminal state.
`IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS` (HTTP 422)	The key was already used with a different body.	Pick a new key.

See Error catalog for the full list.

Pix cash-in

The inbound counterpart.

Instrument types

KEY, EMV, ACCOUNT — when to use each.

Webhooks overview

Receiving lifecycle events.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Pix cash-out

The flow

Dual control — common patterns

Pattern A — operator review

Pattern B — automated rule engine

Recipient resolution

Cancel after approve

Reconciliation

Common errors

Next

Pix cash-in

Instrument types

Webhooks overview

​The flow

​Dual control — common patterns

​Pattern A — operator review

​Pattern B — automated rule engine

​Recipient resolution

​Cancel after approve

​Reconciliation

​Common errors

​Next

Pix cash-in

Instrument types

Webhooks overview

The flow

Dual control — common patterns

Pattern A — operator review

Pattern B — automated rule engine

Recipient resolution

Cancel after approve

Reconciliation

Common errors

Next