Saltar al contenido principal
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

Cada tipo de cobranza informa su estado con sus propios valores: Una cobranza pasa de ACTIVE a COMPLETED cuando el pagador la paga. Una cobranza inmediata pasa a DELETED cuando el comercio la elimina. Cada tipo tiene su propia ventana de validez:
  • Inmediata (COB): el cobro es válido durante expirationSeconds después de su creación.
  • Con vencimiento (COBV): el cobro sigue pagable hasta dueDate más los días de validAfterDue.
Después de que una cobranza llega a COMPLETED, el plugin niega cualquier pago adicional a ella. 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. Una eliminación también requiere X-Reason (DELETED_BY_USER o DELETED_BY_PSP). 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. La cobranza debe estar ACTIVE. Para un cobro inmediato, el monto también debe coincidir. De lo contrario, el plugin niega el pago.
  4. El plugin registra el cash-in en Midaz como una transacción del ledger y luego pasa la cobranza a COMPLETED.
  5. El plugin emite el webhook de cash-in para notificar a tu sistema.
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 evento TRANSFER / CASHIN del pago. 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, luego WEBHOOK_TRANSFER_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