> ## 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), con vencimiento (COBV) y universal.

El Plugin Pix Indirecto (BTG) genera y gestiona códigos QR Pix (BR Codes) para que tus clientes puedan recibir pagos. El plugin admite cuatro tipos de códigos QR: BR Codes estáticos, cobros inmediatos (COB), cobros con vencimiento (COBV) y un decodificador 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 crear un código QR, la clave del receptor debe existir previamente en DICT. La cuenta solicitante debe ser propietaria de la clave. Identificas la cuenta con el header `X-Account-Id`. Consulta la [guía de DICT](/es/rails/pix/btg/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. Diferentes pagadores pueden pagar el mismo código muchas veces. Cada código se vincula 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 añadir datos del comercio al código: `merchant.name`, `merchant.city`, `merchant.categoryCode` (MCC) y `merchant.postalCode`. También puedes añadir un `txId` opcional (alfanumérico, hasta 25 caracteres) para la reconciliación. Si omites los datos del comercio, el plugin los completa 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..." }
```

Envía `include_base64=true` para recibir también un PNG codificado en Base64 del código QR. El plugin valida que la cuenta sea propietaria de la clave del receptor antes de crear el código.

**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`), o cobrança imediata, son códigos QR dinámicos y de un solo uso. Cada cobro define un monto específico y una ventana de validez corta. Un `txId` obligatorio identifica cada cobro. Un pagador solo puede liquidar un cobro una vez.

**Campos obligatorios:** `amount`, `expirationSeconds`, `receiverKey` y `txId`. Los campos opcionales `debtorName` y `debtorDocument` identifican al pagador previsto.

**Ciclo de vida:**

| Estado      | Significado                      |
| ----------- | -------------------------------- |
| `ACTIVE`    | Creado y disponible para el pago |
| `COMPLETED` | Pago recibido correctamente      |
| `EXPIRED`   | Ventana de validez transcurrida  |
| `DELETED`   | Cancelado por el comercio        |

Cuando creas un cobro, el plugin programa un trabajo de expiración. Una vez transcurrido `expirationSeconds`, el cobro pasa a `EXPIRED` y ningún pagador puede liquidarlo. Solo puedes actualizar (`PUT`) o eliminar (`DELETE`) un cobro mientras está en `ACTIVE`.

**Confirmación de pago:** cuando un Pix entrante liquida el cobro, el plugin lo pasa a `COMPLETED`. Luego el plugin emite un webhook para notificar a tu sistema en tiempo real. Consulta la [guía de Webhooks](/es/rails/pix/btg/indirect-pix-webhooks) y la [guía de Cobros](/es/rails/pix/btg/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`), o cobrança com vencimento, son códigos QR dinámicos para facturación con fecha de vencimiento, como un boleto. Admiten reglas de monto complejas. Requieren los datos completos del deudor y del receptor.

**Campos clave:** `dueDate`, `validAfterDue`, un `debtor` obligatorio y un objeto `amount`. El campo obligatorio `validAfterDue` define los días que el cobro permanece pagable después de la fecha de vencimiento. El `debtor` necesita un nombre y un CPF o CNPJ. También admite email, dirección, ciudad, estado y código postal opcionales. El objeto `amount` contiene el valor `original` y componentes de cargo opcionales:

| Componente  | Modalidad                                                    | Aplica                                        |
| ----------- | ------------------------------------------------------------ | --------------------------------------------- |
| `fine`      | `FIXED_VALUE` o `PERCENT`                                    | Multa por pago atrasado                       |
| `interest`  | p. ej. `PERCENTAGE_PER_MONTH_CALENDAR_DAYS`                  | Se acumula después de la fecha de vencimiento |
| `discount`  | una modalidad con un valor, o un arreglo `discountDateFixed` | Recompensa por pago anticipado                |
| `abatement` | `FIXED_VALUE` o `PERCENT`                                    | Reducción sobre el monto                      |

El momento del pago determina el valor final. Antes de la fecha de vencimiento, el pagador obtiene cualquier descuento. En la fecha de vencimiento, se aplica el monto `original`. Después de la fecha de vencimiento, el plugin añade la multa y el interés, y luego resta cualquier abatement. Un descuento con fecha (`discountDateFixed`) necesita una `date` anterior a la `dueDate`.

El plugin requiere un documento de deudor válido (CPF o CNPJ). Mantiene el cobro pagable hasta la fecha de vencimiento más `validAfterDue` días.

**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. Devuelve los datos de pago que incorpora. Úsalo en flujos de iniciación de pago. Un cliente escanea un código QR y tú lees 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 desde BTG antes de responder. 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/rails/pix/btg/indirect-pix-collections) — Ciclo de vida del cobro, vinculación de pagos y eventos webhook
* [DICT](/es/rails/pix/btg/indirect-pix-dict) — Registro de las claves Pix en las que reciben tus códigos QR
* [Webhooks](/es/rails/pix/btg/indirect-pix-webhooks) — Notificaciones de pago y estado