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

Insufficient funds do not reject the create call. The shortfall is detected asynchronously at submit time — after you approve — and the order finalizes as FAILED with errorCode: "INSUFFICIENT_FUNDS". Check the balance up front so you never submit an order that is doomed to fail.

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, your registered cash-out endpoint (set up during onboarding) receives a webhook delivery with status: "SUCCESS". The body is the full PaymentOrder document — no event envelope:

{
  "id":              "ord_4LqGwCxZzOrNyB8fHcSeK",
  "kind":            "Payment.Order",
  "wallet":          "production-main",
  "ordVersion":      4,
  "direction":       "OUT",
  "status":          "SUCCESS",
  "network":         "br.gov.bcb.pix",
  "idempotencyKey":  "payout-2026-0309",
  "amount":          15000,
  "currency":        "BRL",
  "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"
    }
  },
  "metadata":     { "payoutId": "2026-0309" },
  "errorCode":    null,
  "errorMessage": null,
  "createdAt":    "2026-01-15T11:00:00.000Z",
  "updatedAt":    "2026-01-15T11:00:03.214Z",
  "processedAt":  "2026-01-15T11:00:03.214Z",
  "selfName":     "wallets/production-main/paymentOrders/ord_4LqGwCxZzOrNyB8fHcSeK",
  "etag":         "f4a2c91b7d5e0836"
}

locked decreases; amount decreases by the order amount.Verify the X-Webhook-Signature header before trusting the payload (see Verifying signatures), persist, then acknowledge with a 2xx and the literal response body success. Deduplicate deliveries by (id, etag) and guard ordering with ordVersion.On failure, the order finalizes FAILED and a webhook delivery with status: "FAILED" arrives; locked decreases and amount is unchanged — funds are released:

{
  "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 discovers new orders — by polling the AWAITING_APPROVAL list above, or via an internal message from the creating service (order creation is an intermediate state and never generates a webhook) — 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	`SUCCESS` webhook delivery
Resolved creditor account	`SUCCESS` webhook delivery
Error code	`FAILED` webhook delivery

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` when the platform submitted the order after approval. Create and approve succeed; the order finalizes `FAILED` and a webhook delivery with `status: FAILED` arrives asynchronously.	Run the pre-flight balance check; create a new order once funds are available.
`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 409)	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 settled-order deliveries.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Webhooks

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