> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Instrument types
> The five PIX instrument variants — static QR, dynamic QR, key, EMV, and account — and when to use each.
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
```json theme={"dark"}
{
"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
```json theme={"dark"}
{
"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:
```json theme={"dark"}
{
"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
```json theme={"dark"}
{
"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
```json theme={"dark"}
{
"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
```json theme={"dark"}
{
"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
```json theme={"dark"}
{
"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
```json theme={"dark"}
{
"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.
## Choosing a variant — quick decision tree
```mermaid theme={"dark"}
flowchart TD
A{Direction?} -->|IN| B{Same QR
used many times?}
B -->|Yes| C[PIX_CASH_IN_EMV_STATIC]
B -->|No, one-shot| D[PIX_CASH_IN_EMV_DYNAMIC]
A -->|OUT| E{What does
the recipient
provide?}
E -->|PIX key| F[PIX_CASH_OUT_KEY]
E -->|EMV payload
they sent me| G[PIX_CASH_OUT_EMV]
E -->|Account
coordinates| H[PIX_CASH_OUT_ACCOUNT]
```
## Next
Build a complete inbound flow with dynamic EMV.
Build a complete outbound flow with approval.