X-Account-Id. Consulta la guía de DICT para el registro de claves.
Elegir un tipo de código QR
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.
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.
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 · List · Retrieve
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:
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 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), 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:
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 · List · Retrieve · Update
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.