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. La solicitud requiere un clientRequestId. 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.
Pix Saque y Pix Troco: para crear un cobro de Pix Saque, agrega el campo opcional withdrawalAmount. Para crear un cobro de Pix Troco, envía withdrawalAmount junto con transactionAmount. El transactionAmount debe ser igual a amount. Los dos valores deben ser mayores que cero.
Ciclo de vida:
El cobro es válido durante
expirationSeconds después de su creación. 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, se aplican la multa y los intereses, menos 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). El cobro sigue 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): clave receptora, monto, vencimiento,
txId, estado, número de revisión y el deudor opcional. - DUE_DATE (COBV): clave receptora,
txId, fecha de vencimiento,validAfterDue, deudor, receptor, estado, número de revisión y la estructura de multa/intereses/descuento/reducción con el monto final. - RECURRENCE: los datos de recurrencia de un código QR de Pix Automático.