Cobros

Cómo funcionan los cobros Pix en el Plugin Pix Indirecto (BTG): cobros inmediatos (COB) y con vencimiento (COBV), su ciclo de vida y eventos de webhook.

Un cobro (cobrança) es un cobro Pix dinámico 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:

• Inmediato (COB) — cobrança imediata: un cobro de corta duración por un monto fijo. Úsalo para checkout y pagos únicos.
• Con vencimiento (COBV) — cobrança com vencimento: un cobro tipo boleto con una fecha de vencimiento y multa, interés, descuento y abatimiento opcionales. Úsalo para facturas, cuotas y facturación B2B.

Esta guía cubre el ciclo de vida del cobro y el flujo de pago. Para los detalles de generación de QR Codes y la validación campo por campo, consulta la guía de QR Codes.

​

Ciclo de vida

---

Ambos tipos de cobro comparten el mismo modelo de estados:

Estado	Significado
ACTIVE	Creado y disponible para pago
COMPLETED	Pago recibido — el cobro está liquidado
REMOVED_BY_RECEIVER	Eliminado por el comercio (DELETE)
REMOVED_BY_PSP	Expirado tras su ventana de validez

Un cobro pasa de ACTIVE a COMPLETED cuando el pagador lo paga. Pasa a REMOVED_BY_PSP cuando expira, o a REMOVED_BY_RECEIVER cuando el comercio lo elimina. Cada tipo tiene su propia ventana de validez:

• Inmediato (COB): el cobro expira después de expirationSeconds.
• Con vencimiento (COBV): el cobro expira en dueDate más validAfterDue días.

Después de que un cobro expira o alcanza COMPLETED, el pagador ya no puede pagarlo. El plugin también rechaza cualquier intento de eliminar o actualizar un cobro COMPLETED (PIX-0704).

​

Campos clave

---

Campo	Requerido en	Notas
txId	COB + COBV	Identificador único entre todos los cobros; se usa para vincular el pago entrante
amount	COB + COBV	Decimal con 2 posiciones, mayor que 0
receiverKey	COB + COBV	Clave Pix que recibe el pago; debe pertenecer a la cuenta
expirationSeconds	Solo COB	Ventana de validez para cobros inmediatos
dueDate / validAfterDue	Solo COBV	Fecha de vencimiento y período de gracia posterior al vencimiento
debtor	COBV (opcional en COB)	Nombre + CPF/CNPJ del pagador esperado
amount.fine / interest / discount / abatement	Solo COBV (opcional)	Reglas de cobro exclusivas de COBV

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 tardío agrega multa e interés, menos cualquier abatimiento.

​

Crear, consultar, actualizar, eliminar

---

Acción	Inmediato (COB)	Con vencimiento (COBV)
Crear	POST /v1/collections/immediate	POST /v1/collections/duedate
Listar	GET /v1/collections/immediate	GET /v1/collections/duedate
Consultar	GET /v1/collections/immediate/{id}	GET /v1/collections/duedate/{id}
Actualizar	PATCH /v1/collections/immediate/{id}	PATCH /v1/collections/duedate/{id}
Eliminar	DELETE /v1/collections/immediate/{id}	—

Todas las solicitudes requieren el encabezado X-Account-Id. Puedes actualizar o eliminar un cobro solo mientras está ACTIVE.

​

Flujo de pago

---

El pagador liquida un cobro con un Pix entrante (cash-in) que lleva el txId del cobro:

1. El comercio crea un cobro y 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 al cobro comparando el txId del pago con el txId del cobro y el documento del receptor. (FindByTxID(txID, receiverDocument).)
4. En caso de coincidencia, el cobro pasa a COMPLETED y el plugin registra el cash-in en Midaz como una transacción del libro mayor.
5. El plugin emite un webhook de cobro pagado para notificar a tu sistema en tiempo real.

Cuando estableces un debtor en el cobro, 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 pagar

---

Después de que un pago liquida un cobro, 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 mediante las URLs de webhook de cash-in (WEBHOOK_TRANSFER_CASHIN_URL, con WEBHOOK_DEFAULT_URL como respaldo). Para los tipos de evento, payloads, reintentos y resolución de URL, consulta la guía de Webhooks.

​

Casos de error

---

Caso	Comportamiento
Expirado	El pagador ya no puede pagar el cobro. Un pago entrante tardío queda sin vincular y sigue el flujo estándar de cash-in no coincidente
Monto no coincidente	Para un cobro inmediato, un pago cuyo monto difiere del cobro no completa el cobro (PIX-0729)		txId duplicado	La creación falla — un txId debe ser único entre todos los cobros (PIX-0701)
Actualizar/eliminar después de completarse	El plugin rechaza la solicitud (PIX-0704) — un cobro COMPLETED es inmutable

​

Referencia

---

Inmediato (COB): Crear · Listar · Consultar · Actualizar · Eliminar

Con vencimiento (COBV): Crear · Listar · Consultar · Actualizar

​

Próximos pasos

---

• QR Codes — Tipos de QR Code y el decodificador
• Transferencias intra-PSP — Liquidación interna cuando el pagador y el beneficiario comparten tu ISPB
• Webhooks — Notificaciones de pago y estado