Skip to main content
Una cobranza (cobrança) es un cobro Pix dinámico y de un solo uso que solicita un pago específico. El Plugin Pix Indirecto (BTG) admite dos tipos. Ambos tipos usan un QR Code dinámico:
  • Inmediata (COB) (cobrança imediata): un cobro de corta duración por un monto fijo. Úsala para checkout y pagos únicos.
  • Con vencimiento (COBV) (cobrança com vencimento): un cobro parecido a un boleto, con fecha de vencimiento y multa, intereses, descuento y bonificación opcionales. Úsala para facturas, cuotas y facturación B2B.
Esta guía cubre el ciclo de vida de la cobranza y el flujo de pago. Para los detalles de generación de QR Code y la validación campo por campo, consulta la guía de QR Codes.

​
Ciclo de vida

Ambos tipos de cobranza comparten el mismo modelo de estados: Una cobranza pasa de ACTIVE a COMPLETED cuando el pagador la paga. Pasa a REMOVED_BY_PSP cuando vence, o a REMOVED_BY_RECEIVER cuando el comercio la elimina. Cada tipo tiene su propia ventana de validez:
  • Inmediata (COB): el cobro vence después de expirationSeconds.
  • Con vencimiento (COBV): el cobro vence en dueDate más los días de validAfterDue.
Después de que una cobranza vence o llega a COMPLETED, el pagador ya no puede pagarla. El plugin también rechaza cualquier intento de eliminar o actualizar una cobranza COMPLETED (PIX-0704).

​
Campos clave

Para COBV, el valor final depende del momento del pago. El pago anticipado aplica descuentos. El pago a tiempo usa el monto original. El pago atrasado suma multa e intereses, menos cualquier bonificación.

​
Creación, consulta, actualización y eliminación

Todas las solicitudes requieren el header X-Account-Id. Puedes actualizar o eliminar una cobranza solo mientras está ACTIVE.

​
Flujo de pago

El pagador liquida una cobranza con un Pix entrante (cash-in) que lleva el txId de la cobranza:
  1. El comercio crea una cobranza y le presenta su QR Code (o txId) al pagador.
  2. El pagador liquida el cobro. BTG notifica al plugin del cash-in entrante.
  3. El plugin vincula el cash-in con la cobranza al comparar el txId del pago con el txId de la cobranza y el documento del receptor. (FindByTxID(txID, receiverDocument).)
  4. Si coinciden, la cobranza pasa a COMPLETED y el plugin registra el cash-in en Midaz como una transacción del ledger.
  5. El plugin emite un webhook de cobranza pagada para notificar a tu sistema en tiempo real.
Cuando defines un debtor en la cobranza, el cobro registra el CPF/CNPJ del pagador esperado. El plugin no bloquea a un pagador distinto en la liquidación.

​
Evento de webhook al pagarse

Después de que un pago liquida una cobranza, el plugin encola un webhook saliente. El webhook describe el pago y el nuevo estado COMPLETED. El worker de webhooks salientes lo entrega de forma asíncrona. Configura el destino con las URL de webhook de cash-in (WEBHOOK_TRANSFER_CASHIN_URL, con WEBHOOK_DEFAULT_URL como alternativa). Para tipos de evento, payloads, reintentos y resolución de URL, consulta la guía de Webhooks.

​
Casos de error

​
Referencia

Inmediata (COB): Crear · Listar · Consultar · Actualizar · Eliminar Con vencimiento (COBV): Crear · Listar · Consultar · Actualizar

​
Próximos pasos