> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# QR Codes

> How the Pix Indirect Plugin (BTG) generates and decodes Pix QR Codes — static BR Codes, immediate charges (COB), due-date charges (COBV), and the universal decoder.

The Pix Indirect Plugin (BTG) generates and manages Pix QR Codes (BR Codes) so your customers can receive payments. It supports four QR Code domains: **static** BR Codes, **immediate** charges (cobrança imediata / COB), **due-date** charges (cobrança com vencimento / COBV), and a universal **decoder** for payment initiation.

All QR Codes follow the EMV QCO specification and embed the receiver's Pix key. Before a QR Code can be created, the **receiver key must already exist in DICT and be owned by the requesting account** (identified by the `X-Account-Id` header). See the [DICT guide](/en/midaz/plugins/pix/indirect/indirect-pix-dict) 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.

You can enrich the code with merchant data (`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.

```json theme={null}
POST /v1/brcode/static
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "receiverKey": "+5511999999999",
  "amount": "100.00",
  "description": "Payment for order #12345",
  "txId": "TX123ABC",
  "merchant": { "name": "Loja ABC", "city": "São Paulo", "categoryCode": "5411" }
}
→ 201 Created  { "id": "...", "emv": "00020126580014br.gov.bcb.pix...", "status": "ACTIVE" }
```

Pass `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](/en/reference/midaz/plugins/indirect-pix/create-a-static-qr-code) · [List](/en/reference/midaz/plugins/indirect-pix/list-static-qr-codes) · [Retrieve](/en/reference/midaz/plugins/indirect-pix/retrieve-a-static-qr-code)

# 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) |

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](/en/midaz/plugins/pix/indirect/indirect-pix-webhooks) and the [Collections guide](/en/midaz/plugins/pix/indirect/indirect-pix-collections) for the full payment flow.

**Reference:** [Create an immediate charge](/en/reference/midaz/plugins/indirect-pix/create-an-immediate-charge) · [List](/en/reference/midaz/plugins/indirect-pix/list-immediate-charges) · [Retrieve](/en/reference/midaz/plugins/indirect-pix/retrieve-immediate-charge-details) · [Update](/en/reference/midaz/plugins/indirect-pix/update-an-immediate-charge) · [Delete](/en/reference/midaz/plugins/indirect-pix/delete-an-immediate-charge)

# 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 |

**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](/en/reference/midaz/plugins/indirect-pix/create-a-dynamic-charge-with-due-date) · [List](/en/reference/midaz/plugins/indirect-pix/list-dynamic-charges-with-due-date) · [Retrieve](/en/reference/midaz/plugins/indirect-pix/retrieve-dynamic-charge-with-due-date-details) · [Update](/en/reference/midaz/plugins/indirect-pix/update-a-dynamic-charge-with-due-date)

# 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.

For dynamic codes, the plugin resolves the dynamic payload from BTG before returning, so the response reflects the charge's current state.

```json theme={null}
POST /v1/qrcodes/decode
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "emv": "00020126580014br.gov.bcb.pix..." }
→ 200 OK  { "type": "IMMEDIATE", "amount": "100.00", "receiverKey": "...", "status": "ACTIVE" }
```

**Reference:** [Decode a Pix QR code](/en/reference/midaz/plugins/indirect-pix/decode-a-pix-qr-code)

# Next steps

***

* [Collections](/en/midaz/plugins/pix/indirect/indirect-pix-collections) — Collection lifecycle, payment linking, and webhook events
* [DICT](/en/midaz/plugins/pix/indirect/indirect-pix-dict) — Registering the Pix keys your QR Codes receive on
* [Webhooks](/en/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Payment and status notifications