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 — the same code can be paid many times by different payers. They are tied to a Pix key and, optionally, 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, 4 digits), merchant.postalCode) and an optional txId (alphanumeric, ≤ 25 characters) for reconciliation. If merchant data is omitted, the plugin can enrich it from CRM holder data.
include_base64=true to also receive a Base64-encoded PNG of the QR Code. The plugin validates key ownership (returns PIX-0092 if the key is not owned, PIX-0093 if inactive).
Reference: Create a static QR code · List · Retrieve
Immediate charges (COB)
Immediate collections (
/v1/collections/immediate) are dynamic, single-use QR Codes for a specific amount with a short validity window. Each is uniquely identified by a required txId and can only be paid once.
Required fields: amount, expirationInSeconds (recommended ≤ 3600), receiverKey, and txId. An optional debtor (name + document) restricts who may pay — when set, only the specified CPF/CNPJ can settle the charge.
Lifecycle:
When created, the plugin schedules an expiration job; after
expirationInSeconds elapses the charge can no longer be paid. While ACTIVE, the charge can be updated (PATCH) or deleted (DELETE) — a charge in CONCLUDED status cannot be deleted (PIX-0104).
Payment confirmation: when an incoming Pix settles the charge, the plugin transitions it to CONCLUDED and emits a webhook so your system is notified 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) are dynamic QR Codes for billing with a due date, analogous to a boleto. They support complex amount rules and require full debtor and receiver data.
Key fields: dueDate, validAfterDue (days the charge stays payable after the due date — default 30), a required debtor (name + CPF/CNPJ, plus optional email/address/city/state/zipCode), and an amount object with optional charge components:
Payment timing determines the final value: before the due date the payer gets any applicable discount; on the due date the original amount applies; after the due date fines and interest are added (minus any abatement).
UP_TO_DATE discount types require a date that must fall before the dueDate.
The plugin validates the debtor document format (PIX-0073) and schedules expiration at dueDate + validAfterDue.
Reference: Create a due-date charge · List · Retrieve · Update
Decoding QR Codes
The decoder (
POST /v1/qrcodes/decode) parses any scanned Pix QR Code and returns its embedded payment data. Use it in payment-initiation flows — when a customer scans a QR Code and you need the receiver, amount, and charge details before confirming 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