X-Account-Id). Consulta la guía de 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.
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.
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 · List · Retrieve
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) |
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 y la guía de Cobros para el flujo de pago completo.
Referencia: Create an immediate charge · List · Retrieve · Update · Delete
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 |
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 · List · Retrieve · Update
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.