Bloobank API Documentation

This tutorial walks through receiving a PIX payment end to end. The shortest happy path uses a dynamic EMV QR: you create an order, render the QR to the customer, the customer pays, and a webhook tells you it settled. For the underlying state machine, see Payment lifecycle. For other instrument types, see Instrument types.

The flow

Generate an idempotencyKey for the invoice

Tie it to the business intent — typically the invoice or order id, prefixed so it is unambiguous.

idempotencyKey = "invoice-2026-0184"

Persist it locally before calling the API. On any network failure during the next step, you will retry with the same key.

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,
    "debtorName":      "John Doe",
    "debtorDocument":  "12345678901"
  },
  "metadata": {
    "orderId": "2026-0184"
  }
}

Response: 201 Created with status: "PENDING" and the provider-rendered QR.

{
  "id":              "ord_3KpFvBwYzNqMxA7eHbRdJ",
  "status":          "PENDING",
  "direction":       "IN",
  "network":         "br.gov.bcb.pix",
  "amount":          25000,
  "currency":        "BRL",
  "idempotencyKey":  "invoice-2026-0184",
  "instrument": {
    "type":      "PIX_CASH_IN_EMV_DYNAMIC",
    "expiresIn": 86400,
    "qrcode":    "00020101021126830014br.gov.bcb.pix...",
    "copypaste": "00020101021126830014br.gov.bcb.pix...",
    "expiresAt": "2026-01-16T10:30:00.000Z",
    "endToEndId": null
  },
  "createdAt":  "2026-01-15T10:30:00.000Z",
  "updatedAt":  "2026-01-15T10:30:00.000Z"
}

The qrcode and copypaste are the same EMV payload. Store the id for reconciliation; persist the QR/copypaste alongside the invoice.

Render the QR to the customer

Two surfaces:

qrcode — generate a QR image on your client side and display it.
copypaste — show as a copy-able string for users on the same device as their banking app (“PIX copia e cola”).

Both encode the same EMV payload; provide both for the best UX.Show the customer the expiresAt so they know how long the QR is valid.

Wait for settlement — via webhook

When the customer pays, your registered cash-in endpoint (set up during onboarding) receives a webhook delivery with status: "SUCCESS". The body is the full PaymentOrder document — no event envelope:

{
  "id":             "ord_3KpFvBwYzNqMxA7eHbRdJ",
  "kind":           "Payment.Order",
  "wallet":         "production-main",
  "ordVersion":     2,
  "direction":      "IN",
  "status":         "SUCCESS",
  "network":        "br.gov.bcb.pix",
  "idempotencyKey": "invoice-2026-0184",
  "amount":         25000,
  "currency":       "BRL",
  "instrument": {
    "type":       "PIX_CASH_IN_EMV_DYNAMIC",
    "endToEndId": "E60746948202601151030001A1B2C3D",
    "qrcode":     "00020101021126830014br.gov.bcb.pix...",
    "copypaste":  "00020101021126830014br.gov.bcb.pix...",
    "expiresAt":  "2026-01-16T10:30:00.000Z"
  },
  "metadata":     { "orderId": "2026-0184" },
  "errorCode":    null,
  "errorMessage": null,
  "createdAt":    "2026-01-15T10:30:00.000Z",
  "updatedAt":    "2026-01-15T10:31:24.512Z",
  "processedAt":  "2026-01-15T10:31:24.512Z",
  "selfName":     "wallets/production-main/paymentOrders/ord_3KpFvBwYzNqMxA7eHbRdJ",
  "etag":         "c8b1f0a9d2e37c46"
}

Verify the X-Webhook-Signature header before trusting the payload (see Verifying signatures), persist, acknowledge with a 2xx and the literal response body success, then mark the invoice as paid and ship. Deliveries are at-least-once: deduplicate by (id, etag) and discard any delivery whose ordVersion is lower than the highest you have already processed for that order.

(Fallback) Poll if you cannot expose a webhook

If a webhook endpoint is not feasible, poll the order until it reaches a final state.

GET /wallets/production-main/paymentOrders/ord_3KpFvBwYzNqMxA7eHbRdJ HTTP/1.1

Poll every 5–10 seconds until status is one of SUCCESS, FAILED, EXPIRED, REFUNDED. Then stop.Polling consumes rate-limit quota — prefer webhooks.

Listing inbound orders

To page through historical inbound orders, use the list endpoint with a direction filter:

GET /wallets/production-main/paymentOrders?filter=direction%3DIN%20AND%20status%3DSUCCESS&order_by=createdAt%20desc&page_size=50 HTTP/1.1

See Pagination for the iteration pattern and Filtering for the available fields.

Static QR (long-lived)

For a reusable QR — e.g., a store-counter sign that any customer can pay — use PIX_CASH_IN_EMV_STATIC. As with every payment order, amount is required and must be a positive integer in minor units; every payer settles that fixed amount:

{
  "direction":      "IN",
  "network":        "br.gov.bcb.pix",
  "idempotencyKey": "store-counter-checkout-1",
  "amount":         25000,
  "currency":       "BRL",
  "instrument":     { "type": "PIX_CASH_IN_EMV_STATIC" }
}

Note: with the static variant, every settlement to the same QR creates a new SUCCESS webhook delivery for a new logical order. The platform manages this — your webhook consumer processes each delivery independently, deduplicating by (id, etag) (each settlement carries its own order id).

Reconciliation

For every inbound payment, your local invoice record should end up with:

Field	Source
Order id	API response on create
Idempotency key	Generated by you, stored locally
End-to-end id	Webhook payload (`SUCCESS` delivery)
Settled-at timestamp	Webhook payload (`processedAt`)
Currency, amount	API response / webhook payload

At end of day, list orders by createdAt window and reconcile against your local set. Any local invoice without a matching SUCCESS order is unpaid; any order without a local invoice is a billing leak.

Errors

Reason	Cause	Fix
`INVALID_FIELD` (in `details[]`)	A field on the create request failed validation.	Fix the named field.
`WALLET_NOT_FOUND`	The wallet path segment does not resolve.	Verify wallet name.
`IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS`	The key is already bound to a different body.	Pick a new key — or reconcile against the existing order.
`RBAC_DENY`	The credential lacks permission to create payment orders on this wallet.	Capture `decisionId`; contact account team.

See Error catalog for the full list.

Pix cash-out

The outbound counterpart, with approval.

Webhooks overview

Receiving and verifying settled-order deliveries.

Payment lifecycle

The state machine reference.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Webhooks

Pix cash-in

The flow

Listing inbound orders

Static QR (long-lived)

Reconciliation

Errors

Next

Pix cash-out

Webhooks overview

Payment lifecycle

​The flow

​Listing inbound orders

​Static QR (long-lived)

​Reconciliation

​Errors

​Next

Pix cash-out

Webhooks overview

Payment lifecycle

The flow

Listing inbound orders

Static QR (long-lived)

Reconciliation

Errors

Next