Saltar al contenido principal
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 representados como QR Codes dinámicos:
  • 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:
EstadoSignificado
ACTIVECreado y disponible para pago
CONCLUDEDPago recibido — el cobro está liquidado
REMOVED_BY_RECEIVERCancelado por el comercio (DELETE)
REMOVED_BY_PSPCancelado por el PSP (sistema o política)
Un cobro avanza por: creado → ACTIVE → CONCLUDED (pagado) o expirado / removido. Al crearlo, el plugin programa un trabajo de expiración:
  • Inmediato (COB): expira después de expirationInSeconds.
  • Con vencimiento (COBV): expira en dueDate + validAfterDue días (por defecto 30).
Una vez expirado o CONCLUDED, un cobro ya no puede pagarse, y un cobro CONCLUDED no puede eliminarse (PIX-0104) ni actualizarse (PIX-0022).

​
Campos clave

CampoRequerido enNotas
txIdCOB + COBVIdentificador único entre todos los cobros; se usa para vincular el pago entrante
amountCOB + COBVDecimal con 2 posiciones, mayor que 0
receiverKeyCOB + COBVClave Pix que recibe el pago; debe pertenecer a la cuenta
expirationInSecondsSolo COBVentana de validez para cobros inmediatos
dueDate / validAfterDueSolo COBVFecha de vencimiento y período de gracia posterior al vencimiento
debtorCOBV (opcional en COB)Nombre + CPF/CNPJ; restringe quién puede pagar
amount.fine / interest / discount / abatementSolo COBV (opcional)Reglas de cobro exclusivas de COBV
Para COBV, el valor final liquidado depende del momento del pago — el pago anticipado aplica descuentos, el pago a tiempo usa el monto original, y el pago tardío agrega multa e interés (menos cualquier abatimiento).

​
Crear, consultar, actualizar, eliminar

AcciónInmediato (COB)Con vencimiento (COBV)
CrearPOST /v1/collections/immediatePOST /v1/collections/duedate
ListarGET /v1/collections/immediateGET /v1/collections/duedate
ConsultarGET /v1/collections/immediate/{id}GET /v1/collections/duedate/{id}
ActualizarPATCH /v1/collections/immediate/{id}PATCH /v1/collections/duedate/{id}
EliminarDELETE /v1/collections/immediate/{id}—
Todas las solicitudes requieren el encabezado X-Account-Id. Las actualizaciones y eliminaciones solo se permiten mientras el cobro está ACTIVE.

​
Flujo de pago

Un cobro se paga mediante 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 CONCLUDED y el cash-in se registra en Midaz como una transacción del libro mayor.
  5. El plugin emite un webhook de cobro pagado para que tu sistema sea notificado en tiempo real.
Cuando se establece un debtor en el cobro, solo un pago desde ese CPF/CNPJ lo liquida. Esta es la principal defensa contra que el pagador equivocado concluya un cobro.

​
Evento de webhook al pagar

Cuando un cobro se liquida, el plugin encola un webhook saliente que describe el pago y el nuevo estado CONCLUDED, entregado de forma asíncrona por el worker de webhooks salientes. 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

CasoComportamiento
ExpiradoEl cobro ya no puede pagarse; un pago entrante tardío no se vincula y sigue el flujo estándar de cash-in no coincidente
Monto no coincidenteUn pago cuyo valor no coincide con el cobro se rechaza/maneja según las reglas de BACEN y no concluye el cobro
Deudor no coincidenteUn pago desde un CPF/CNPJ distinto del debtor configurado no liquida el cobro (PIX-0073 cubre los errores de formato del documento del deudor)
txId duplicadoLa creación falla — txId debe ser único entre todos los cobros
Actualizar/eliminar después de la conclusiónRechazado (PIX-0022 / PIX-0104) — un cobro CONCLUDED es inmutable

​
Referencia

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

​
Próximos pasos