X-Account-Id header). See the DICT guide for key registration.
Choosing a QR Code type
| Type | Characteristics | Best for |
|---|---|---|
| Static | Reusable (multiple payments) · optional amount (fixed or payer-entered) · no expiration | POS displays, printed material, donations, e-commerce with variable amounts |
| Immediate (COB) | Single payment · amount required · seconds-based expiration | Checkout, invoicing, one-time purchases |
| Due-date (COBV) | Single payment · amount + charges · due date + grace period | Bills, installments, subscriptions, B2B invoicing (boleto-like) |
| Decode | Reads any scanned QR Code | Initiating a payment from a scanned code |
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:
| Status | Meaning |
|---|---|
ACTIVE | Created and available for payment |
CONCLUDED | Payment received successfully |
REMOVED_BY_RECEIVER | Cancelled by the merchant |
REMOVED_BY_PSP | Cancelled by the PSP (system or policy) |
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:
| Component | Types | Applies |
|---|---|---|
fine | FIXED, PERCENTAGE | Penalty for late payment |
interest | DAILY_AMOUNT, DAILY_PERCENTAGE, MONTHLY_PERCENTAGE | Accrues after due date |
discount | FIXED, PERCENTAGE, FIXED_UP_TO_DATE, PERCENTAGE_UP_TO_DATE | Reward for early payment |
abatement | FIXED | Credit/reduction on the amount |
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