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

# Códigos QR

> Cómo el Plugin Pix Indirecto (BTG) genera y decodifica códigos QR Pix — BR Codes estáticos, cobros inmediatos (COB), cobros con vencimiento (COBV) y el decodificador universal.

El Plugin Pix Indirecto (BTG) genera y gestiona códigos QR Pix (BR Codes) para que tus clientes puedan recibir pagos. Admite cuatro dominios de códigos QR: BR Codes **estáticos**, cobros **inmediatos** (cobrança imediata / COB), cobros **con vencimiento** (cobrança com vencimento / COBV) y un **decodificador** universal para la iniciación de pagos.

Todos los códigos QR siguen la especificación EMV QCO e incorporan la clave Pix del receptor. Antes de poder crear un código QR, la **clave del receptor debe existir previamente en DICT y pertenecer a la cuenta solicitante** (identificada por el header `X-Account-Id`). Consulta la [guía de DICT](/es/midaz/plugins/pix/indirect/indirect-pix-dict) para el registro de claves.

# Elegir un tipo de código QR

***

| Tipo                       | Características                                                                                    | Ideal para                                                                      |
| -------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Estático**               | Reutilizable (múltiples pagos) · monto opcional (fijo o ingresado por el pagador) · sin expiración | Pantallas de POS, material impreso, donaciones, e-commerce con montos variables |
| **Inmediato (COB)**        | Pago único · monto obligatorio · expiración en segundos                                            | Checkout, facturación, compras únicas                                           |
| **Con vencimiento (COBV)** | Pago único · monto + cargos · fecha de vencimiento + periodo de gracia                             | Facturas, cuotas, suscripciones, facturación B2B (similar a boleto)             |
| **Decode**                 | Lee cualquier código QR escaneado                                                                  | Iniciar un pago a partir de un código escaneado                                 |

# Códigos QR estáticos

***

Los BR Codes estáticos (`/v1/brcode/static`) son **reutilizables**: el mismo código puede pagarse muchas veces por diferentes pagadores. Están vinculados a una clave Pix y, opcionalmente, a datos del comercio.

**Monto fijo vs. variable:**

* **Con monto** — el pagador escanea y confirma un valor predefinido. Útil para artículos de precio fijo.
* **Sin monto** — el pagador escanea e ingresa el valor manualmente. Útil para donaciones o checkout abierto.

Puedes enriquecer el código con datos del comercio (`merchant.name`, `merchant.city`, `merchant.categoryCode` (MCC, 4 dígitos), `merchant.postalCode`) y un `txId` opcional (alfanumérico, ≤ 25 caracteres) para la reconciliación. Si se omiten los datos del comercio, el plugin puede enriquecerlos a partir de los datos del titular en CRM.

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

Envía `include_base64=true` para recibir también un PNG codificado en Base64 del código QR. El plugin valida la titularidad de la clave (devuelve `PIX-0092` si la clave no pertenece a la cuenta, `PIX-0093` si está inactiva).

**Referencia:** [Create a static QR code](/es/reference/midaz/plugins/indirect-pix/create-a-static-qr-code) · [List](/es/reference/midaz/plugins/indirect-pix/list-static-qr-codes) · [Retrieve](/es/reference/midaz/plugins/indirect-pix/retrieve-a-static-qr-code)

# Cobros inmediatos (COB)

***

Los cobros inmediatos (`/v1/collections/immediate`) son códigos QR **dinámicos y de un solo uso** para un monto específico con una ventana de validez corta. Cada uno se identifica de forma única por un `txId` obligatorio y solo puede pagarse una vez.

**Campos obligatorios:** `amount`, `expirationInSeconds` (recomendado ≤ 3600), `receiverKey` y `txId`. Un `debtor` opcional (nombre + documento) restringe quién puede pagar: cuando se establece, solo el CPF/CNPJ especificado puede liquidar el cobro.

**Ciclo de vida:**

| Estado                | Significado                               |
| --------------------- | ----------------------------------------- |
| `ACTIVE`              | Creado y disponible para el pago          |
| `CONCLUDED`           | Pago recibido correctamente               |
| `REMOVED_BY_RECEIVER` | Cancelado por el comercio                 |
| `REMOVED_BY_PSP`      | Cancelado por el PSP (sistema o política) |

Al crearse, el plugin programa un **trabajo de expiración**; una vez transcurrido `expirationInSeconds`, el cobro ya no puede pagarse. Mientras está en `ACTIVE`, el cobro puede actualizarse (`PATCH`) o eliminarse (`DELETE`); un cobro en estado `CONCLUDED` no puede eliminarse (`PIX-0104`).

**Confirmación de pago:** cuando un Pix entrante liquida el cobro, el plugin lo transiciona a `CONCLUDED` y emite un **webhook** para que tu sistema sea notificado en tiempo real. Consulta la [guía de Webhooks](/es/midaz/plugins/pix/indirect/indirect-pix-webhooks) y la [guía de Cobros](/es/midaz/plugins/pix/indirect/indirect-pix-collections) para el flujo de pago completo.

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

# Cobros con vencimiento (COBV)

***

Los cobros con vencimiento (`/v1/collections/duedate`) son códigos QR dinámicos para **facturación con fecha de vencimiento**, análogos a un boleto. Admiten reglas de monto complejas y requieren los datos completos del deudor y del receptor.

**Campos clave:** `dueDate`, `validAfterDue` (días que el cobro permanece pagable después de la fecha de vencimiento, por defecto 30), un `debtor` obligatorio (nombre + CPF/CNPJ, además de email/dirección/ciudad/estado/código postal opcionales) y un objeto `amount` con componentes de cargo opcionales:

| Componente  | Tipos                                                              | Aplica                                        |
| ----------- | ------------------------------------------------------------------ | --------------------------------------------- |
| `fine`      | `FIXED`, `PERCENTAGE`                                              | Multa por pago atrasado                       |
| `interest`  | `DAILY_AMOUNT`, `DAILY_PERCENTAGE`, `MONTHLY_PERCENTAGE`           | Se acumula después de la fecha de vencimiento |
| `discount`  | `FIXED`, `PERCENTAGE`, `FIXED_UP_TO_DATE`, `PERCENTAGE_UP_TO_DATE` | Recompensa por pago anticipado                |
| `abatement` | `FIXED`                                                            | Crédito/reducción sobre el monto              |

El **momento del pago** determina el valor final: antes de la fecha de vencimiento el pagador obtiene cualquier descuento aplicable; en la fecha de vencimiento se aplica el monto original; después de la fecha de vencimiento se añaden multas e intereses (menos cualquier abatement). Los tipos de descuento `UP_TO_DATE` requieren una `date` que debe ser anterior a la `dueDate`.

El plugin valida el formato del documento del deudor (`PIX-0073`) y programa la expiración en `dueDate + validAfterDue`.

**Referencia:** [Create a due-date charge](/es/reference/midaz/plugins/indirect-pix/create-a-dynamic-charge-with-due-date) · [List](/es/reference/midaz/plugins/indirect-pix/list-dynamic-charges-with-due-date) · [Retrieve](/es/reference/midaz/plugins/indirect-pix/retrieve-dynamic-charge-with-due-date-details) · [Update](/es/reference/midaz/plugins/indirect-pix/update-a-dynamic-charge-with-due-date)

# Decodificación de códigos QR

***

El decodificador (`POST /v1/qrcodes/decode`) analiza cualquier código QR Pix escaneado y devuelve los datos de pago que incorpora. Úsalo en **flujos de iniciación de pago**: cuando un cliente escanea un código QR y necesitas el receptor, el monto y los detalles del cargo antes de confirmar el pago.

El plugin detecta automáticamente el tipo de código QR y devuelve una respuesta tipada:

* **STATIC** — clave del receptor, monto/descripción opcionales, información del comercio, `txId`.
* **IMMEDIATE (COB)** — todos los campos estáticos más el monto obligatorio, expiración, estado y número de revisión.
* **DUE\_DATE (COBV)** — todos los campos inmediatos más fecha de vencimiento, `validAfterDue`, deudor, receptor y la estructura completa de multa/interés/descuento.

Para los códigos dinámicos, el plugin resuelve el payload dinámico desde BTG antes de responder, por lo que la respuesta refleja el estado actual del cobro.

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

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

# Próximos pasos

***

* [Cobros](/es/midaz/plugins/pix/indirect/indirect-pix-collections) — Ciclo de vida del cobro, vinculación de pagos y eventos webhook
* [DICT](/es/midaz/plugins/pix/indirect/indirect-pix-dict) — Registro de las claves Pix en las que reciben tus códigos QR
* [Webhooks](/es/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Notificaciones de pago y estado