X-Account-Id header. See the DICT guide for key registration.
Choosing a QR Code type
Static QR Codes
Static BR Codes (
/v1/brcode/static) are reusable. Different payers can pay the same code many times. Each code links to a Pix key and, optionally, to merchant data.
Fixed vs. variable amount:
- With amount — the payer scans and confirms a predefined value. Useful for fixed-price items.
- Without amount — the payer scans and enters the value manually. Useful for donations or open checkout.
merchant.name, merchant.city, merchant.categoryCode (MCC), and merchant.postalCode. You can also add an optional txId (alphanumeric, up to 25 characters) for reconciliation. If you omit merchant data, the plugin fills it from CRM holder data.
include_base64=true to also receive a Base64-encoded PNG of the QR Code. The plugin validates that the account owns the receiver key before it creates the code.
Reference: Create a static QR code · List · Retrieve
Immediate charges (COB)
Immediate collections (
/v1/collections/immediate), or cobrança imediata, are dynamic, single-use QR Codes. Each charge sets a specific amount and a short validity window. A required txId identifies each charge. A payer can settle a charge only once.
Required fields: amount, expirationSeconds, receiverKey, and txId. The optional debtorName and debtorDocument fields identify the intended payer.
Lifecycle:
When you create a charge, the plugin schedules an expiration job. After
expirationSeconds elapses, the charge moves to EXPIRED and no payer can settle it. You can update (PUT) or delete (DELETE) a charge only while it is ACTIVE.
Payment confirmation: when an incoming Pix settles the charge, the plugin moves it to COMPLETED. The plugin then emits a webhook to notify your system in real time. See the Webhooks guide and the Collections guide for the full payment flow.
Reference: Create an immediate charge · List · Retrieve · Update · Delete
Due-date charges (COBV)
Due-date collections (
/v1/collections/duedate), or cobrança com vencimento, are dynamic QR Codes for billing with a due date, like a boleto. They support complex amount rules. They require full debtor and receiver data.
Key fields: dueDate, validAfterDue, a required debtor, and an amount object. The required validAfterDue field sets the days the charge stays payable after the due date. The debtor needs a name and a CPF or CNPJ. It also takes optional email, address, city, state, and zipCode. The amount object holds the original value and optional charge components:
Payment timing determines the final value. Before the due date, the payer gets any discount. On the due date, the
original amount applies. After the due date, the plugin adds the fine and interest, then subtracts any abatement. A dated discount (discountDateFixed) needs a date before the dueDate.
The plugin requires a valid debtor document (CPF or CNPJ). It keeps the charge payable until the due date plus validAfterDue days.
Reference: Create a due-date charge · List · Retrieve · Update
Decoding QR Codes
The decoder (
POST /v1/qrcodes/decode) parses any scanned Pix QR Code. It returns the embedded payment data. Use it in payment-initiation flows. A customer scans a QR Code, and you read the receiver, amount, and charge details before you confirm the payment.
The plugin auto-detects the QR Code type and returns a typed response:
- STATIC — receiver key, optional amount/description, merchant info,
txId. - IMMEDIATE (COB) — all static fields plus required amount, expiration, status, and review number.
- DUE_DATE (COBV) — all immediate fields plus due date,
validAfterDue, debtor, receiver, and the full fine/interest/discount structure.
Next steps
- Collections — Collection lifecycle, payment linking, and webhook events
- DICT — Registering the Pix keys your QR Codes receive on
- Webhooks — Payment and status notifications