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. Distintos 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 frente a 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 agregar un txId opcional (alfanumérico, hasta 25 caracteres) para la conciliación. Si omites los datos del comercio, el plugin los completa con los datos del titular en el CRM.
include_base64=true para recibir también un PNG del código QR codificado en Base64. El plugin valida que la cuenta sea titular de la clave receptora antes de crear el código.
Referencia: Crear un código QR estático · Listar · Consultar
Cobros inmediatos (COB)
Los cobros inmediatos (
/v1/collections/immediate), o cobrança imediata, son códigos QR dinámicos 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 puede liquidar un cobro solo 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 una tarea de vencimiento. Después de que transcurre
expirationSeconds, el cobro pasa a EXPIRED y ningún pagador puede liquidarlo. Puedes actualizar (PUT) o eliminar (DELETE) un cobro solo mientras esté en ACTIVE.
Confirmación del 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: Crear un cobro inmediato · Listar · Consultar · Actualizar · Eliminar
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 datos completos del deudor y del receptor.
Campos principales: dueDate, validAfterDue, un debtor obligatorio y un objeto amount. El campo obligatorio validAfterDue define los días que el cobro sigue siendo pagable después del vencimiento. El debtor necesita un nombre y un CPF o CNPJ. También acepta email, address, city, state y zipCode opcionales. El objeto amount contiene el valor original y componentes de cargo opcionales:
El momento del pago determina el valor final. Antes del vencimiento, el pagador recibe el descuento que corresponda. En la fecha de vencimiento, se aplica el monto
original. Después del vencimiento, el plugin suma la multa y los intereses, y luego resta la reducción que corresponda. Un descuento con fecha (discountDateFixed) necesita una date anterior a dueDate.
El plugin requiere un documento válido del deudor (CPF o CNPJ). Mantiene el cobro pagable hasta la fecha de vencimiento más validAfterDue días.
Referencia: Crear un cobro con vencimiento · Listar · Consultar · Actualizar
Decodificar códigos QR
El decodificador (
POST /v1/qrcodes/decode) analiza cualquier código QR Pix escaneado. Devuelve los datos de pago incorporados. Ú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 cobro antes de confirmar el pago.
El plugin detecta automáticamente el tipo de código QR y devuelve una respuesta tipada:
- STATIC: clave receptora, monto/descripción opcionales, información del comercio,
txId. - IMMEDIATE (COB): todos los campos estáticos más monto obligatorio, vencimiento, 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/intereses/descuento.