BlooBank API Documentation

The instrument field on a payment order is a discriminated union by type. The variant determines the request shape, the response fields, and the user-facing flow. There are five PIX variants today.

Cheat sheet

`type`	Direction	Use for	Provider returns
`PIX_CASH_IN_EMV_STATIC`	IN	Reusable receipts (e.g., a single QR for a store)	`endToEndId` after settlement
`PIX_CASH_IN_EMV_DYNAMIC`	IN	One-shot invoice (e.g., e-commerce checkout)	`qrcode`, `copypaste`, `expiresAt`, `endToEndId` after settlement
`PIX_CASH_OUT_KEY`	OUT	Pay to a PIX key (CPF, CNPJ, phone, email, EVP)	`creditorAccount` after settlement (resolved by provider)
`PIX_CASH_OUT_EMV`	OUT	Pay an EMV (BR-Code) payload	`endToEndId`, `creditorAccount`, `emvTxid`
`PIX_CASH_OUT_ACCOUNT`	OUT	Pay to explicit bank account coordinates (ISPB + agency + account)	`endToEndId`

`PIX_CASH_IN_EMV_STATIC`

A reusable PIX payment instrument. The QR/EMV does not expire; many payers can pay the same QR.

Request

{
  "direction": "IN",
  "network":   "br.gov.bcb.pix",
  "amount":    25000,
  "currency":  "BRL",
  "instrument": {
    "type": "PIX_CASH_IN_EMV_STATIC"
  }
}

Use when

Physical signage at a point of sale.
Recurring donations or tipping.
Any scenario where the same QR will be paid multiple times.

Caveats

The same QR receives many payments. Each settlement creates a new transaction record in the PIX network; the BlooBank order’s endToEndId reflects the first matching settlement. For ongoing reconciliation, listen for webhook events on the order rather than polling.

`PIX_CASH_IN_EMV_DYNAMIC`

A one-shot, expiring QR/EMV for a specific invoice. The QR is valid until expiresAt; one payer settles.

Request

{
  "direction": "IN",
  "network":   "br.gov.bcb.pix",
  "amount":    25000,
  "currency":  "BRL",
  "instrument": {
    "type":      "PIX_CASH_IN_EMV_DYNAMIC",
    "expiresIn": 86400,
    "debtorName":     "John Doe",
    "debtorDocument": "12345678901"
  }
}

Field	Required	Notes
`expiresIn`	Optional	Seconds until expiration. Default `86400` (24 h).
`debtorName`	Optional	Hint for the provider; appears on the customer’s bank app.
`debtorDocument`	Optional	Brazilian CPF (11 digits) or CNPJ (14 digits) of the expected payer.
`debtorAccount`	Optional	A `BankAccount` if you want to constrain which account can pay.

Response — populated fields

After creation, the response populates the provider-rendered payload:

{
  "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
  }
}

qrcode and copypaste are the same EMV payload; qrcode is intended for QR rendering, copypaste for the “PIX copia e cola” UX. After settlement, endToEndId is populated.

Use when

E-commerce checkout where the customer pays once.
Invoices with a known due date.
Any flow where you want auto-expiration if the payer does not settle.

`PIX_CASH_OUT_KEY`

Send PIX to a known PIX key. The provider resolves the key to a recipient account.

Request

{
  "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"
  }
}

Field	Required	Notes
`keyType`	✅	`CPF` \| `CNPJ` \| `PHONE` \| `EMAIL` \| `EVP`
`keyValue`	✅	The key value, normalized per `keyType` (e.g., phone in `+5511999998888` format).

Key formats

`keyType`	Format
`CPF`	11 digits, no punctuation. `12345678901`
`CNPJ`	14 digits, no punctuation. `12345678000190`
`PHONE`	E.164 with country code. `+5511999998888`
`EMAIL`	Standard email. `customer@example.com`
`EVP`	UUID v4. `123e4567-e89b-12d3-a456-426614174000`

Response — populated after settlement

{
  "instrument": {
    "type":     "PIX_CASH_OUT_KEY",
    "keyType":  "CPF",
    "keyValue": "12345678901",
    "endToEndId": "E60746948202601151030001A1B2C3D",
    "creditorAccount": {
      "ispb":           "60746948",
      "bankCode":       "237",
      "bankName":       "Banco Bradesco S.A.",
      "agencyNumber":   "1234",
      "accountType":    "CHECKING_ACCOUNT",
      "accountNumber":  "987654-3",
      "accountOwnerName":     "Recipient Name",
      "accountOwnerDocument": "12345678901"
    }
  }
}

creditorAccount is populated by the provider after key resolution.

Use when

The most common outbound flow.
The recipient supplies a PIX key.
You do not need to validate account ownership client-side (the provider does).

`PIX_CASH_OUT_EMV`

Pay an EMV (BR-Code) payload. Used when scanning or copying a PIX QR code as a sender.

Request

{
  "direction":      "OUT",
  "network":        "br.gov.bcb.pix",
  "amount":         25000,
  "currency":       "BRL",
  "idempotencyKey": "scanned-2026-0309",
  "instrument": {
    "type":     "PIX_CASH_OUT_EMV",
    "emvValue": "00020126360014br.gov.bcb.pix0114+5511999998888..."
  }
}

Field	Required	Notes
`emvValue`	✅	The full EMV payload as scanned/copied.

The amount in the request body must match the amount encoded in the EMV (when present) — for static EMVs without amount, the request amount is used.

Response — populated after parse

{
  "instrument": {
    "type":     "PIX_CASH_OUT_EMV",
    "emvValue": "00020126360014br.gov.bcb.pix...",
    "keyType":  "CPF",
    "keyValue": "12345678901",
    "emvTxid":  "ABCDE12345",
    "emvAmount": 25000,
    "emvObs":   "Pagamento referente à fatura 0184",
    "creditorAccount": { /* ... */ },
    "endToEndId": "E60746948202601151030001A1B2C3D"
  }
}

Use when

The user scans a QR or pastes the “PIX copia e cola” payload.
You receive an EMV from an external source (e.g., a partner’s invoice).

`PIX_CASH_OUT_ACCOUNT`

Pay to explicit bank account coordinates. Used when the recipient does not have a PIX key registered.

Request

{
  "direction":      "OUT",
  "network":        "br.gov.bcb.pix",
  "amount":         50000,
  "currency":       "BRL",
  "idempotencyKey": "payroll-2026-0309-emp-1729",
  "instrument": {
    "type": "PIX_CASH_OUT_ACCOUNT",
    "creditorAccount": {
      "ispb":           "60746948",
      "agencyNumber":   "1234",
      "accountType":    "CHECKING_ACCOUNT",
      "accountNumber":  "987654-3",
      "accountOwnerName":     "Recipient Name",
      "accountOwnerDocument": "12345678901"
    }
  }
}

The creditorAccount object is required and must include enough fields to route the payment (ispb, agencyNumber, accountType, accountNumber, accountOwnerDocument at minimum).

Use when

The recipient does not have a PIX key.
Bulk payroll or supplier payments where you already have account coordinates on file.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Instrument types

Cheat sheet

`PIX_CASH_IN_EMV_STATIC`

Request

Use when

Caveats

`PIX_CASH_IN_EMV_DYNAMIC`

Request

Response — populated fields

Use when

`PIX_CASH_OUT_KEY`

Request

Key formats

Response — populated after settlement

Use when

`PIX_CASH_OUT_EMV`

Request

Response — populated after parse

Use when

`PIX_CASH_OUT_ACCOUNT`

Request

Use when

Choosing a variant — quick decision tree

Next

Pix cash-in tutorial

Pix cash-out tutorial

​Cheat sheet

​PIX_CASH_IN_EMV_STATIC

​Request

​Use when

​Caveats

​PIX_CASH_IN_EMV_DYNAMIC

​Request

​Response — populated fields

​Use when

​PIX_CASH_OUT_KEY

​Request

​Key formats

​Response — populated after settlement

​Use when

​PIX_CASH_OUT_EMV

​Request

​Response — populated after parse

​Use when

​PIX_CASH_OUT_ACCOUNT

​Request

​Use when

​Choosing a variant — quick decision tree

​Next

Pix cash-in tutorial

Pix cash-out tutorial

Cheat sheet

`PIX_CASH_IN_EMV_STATIC`

Request

Use when

Caveats

`PIX_CASH_IN_EMV_DYNAMIC`

Request

Response — populated fields

Use when

`PIX_CASH_OUT_KEY`

Request

Key formats

Response — populated after settlement

Use when

`PIX_CASH_OUT_EMV`

Request

Response — populated after parse

Use when

`PIX_CASH_OUT_ACCOUNT`

Request

Use when

Choosing a variant — quick decision tree

Next