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

> Generate and decode Pix QR Codes via BTG — static BR Codes, immediate COB and due-date COBV charges, EMV payloads, and the universal QR Code decoder.

The Pix Indirect Plugin (BTG) generates and manages Pix QR Codes (BR Codes) so your customers can receive payments. The plugin supports four QR Code types: static BR Codes, immediate charges (COB), due-date charges (COBV), and a decoder for payment initiation.

All QR Codes follow the EMV QCO specification and embed the receiver's Pix key. Before you create a QR Code, the receiver key must already exist in DICT. The requesting account must own the key. You identify the account with the `X-Account-Id` header. See the [DICT guide](/en/rails/pix/btg/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. 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.

You can add merchant data to the code: `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.

```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..." }
```

Pass `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](/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`), 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:**

| Status      | Meaning                           |
| ----------- | --------------------------------- |
| `ACTIVE`    | Created and available for payment |
| `COMPLETED` | Payment received successfully     |
| `EXPIRED`   | Validity window elapsed           |
| `DELETED`   | Cancelled by the merchant         |

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](/en/rails/pix/btg/indirect-pix-webhooks) and the [Collections guide](/en/rails/pix/btg/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`), 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:

| Component   | Modality                                                | Applies                    |
| ----------- | ------------------------------------------------------- | -------------------------- |
| `fine`      | `FIXED_VALUE` or `PERCENT`                              | Penalty for late payment   |
| `interest`  | e.g. `PERCENTAGE_PER_MONTH_CALENDAR_DAYS`               | Accrues after the due date |
| `discount`  | a modality with a value, or a `discountDateFixed` array | Reward for early payment   |
| `abatement` | `FIXED_VALUE` or `PERCENT`                              | Reduction on the amount    |

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](/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. 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.

For dynamic codes, the plugin resolves the payload from BTG before it returns. 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/rails/pix/btg/indirect-pix-collections) — Collection lifecycle, payment linking, and webhook events
* [DICT](/en/rails/pix/btg/indirect-pix-dict) — Registering the Pix keys your QR Codes receive on
* [Webhooks](/en/rails/pix/btg/indirect-pix-webhooks) — Payment and status notifications