Eventos de Pix Indirect via BTG

Pix Indirect via BTG publica 63 hechos de negocio JSON como CloudEvents 1.0 en modo de contenido binario sobre Kafka. Estos eventos están disponibles en despliegues BYOC. El streaming es opcional y está desactivado por defecto. Para activarlo, define STREAMING_ENABLED=true y las demás variables de eventos de negocio en el componente de la API. La visión general del streaming de eventos describe el envelope común.

Contrato de transporte

Campo	Valor
`ce-source`	El valor de `STREAMING_CLOUDEVENTS_SOURCE`. El valor predeterminado es `plugin-br-pix-indirect-btg`.
Tema	`lerian.streaming.<ce-source>`
`ce-type`	`studio.lerian.<ce-source>.<event-key>`
`ce-tenantid`	El valor de `STREAMING_TENANT_ID`. El valor predeterminado es `default`.
Versión del esquema	`1.0.0` para cada evento
Tipo de contenido	`application/json`
Entrega	Definida por evento. Consulta Entrega.
Tema de comandos	Ninguno
Manifest en tiempo de ejecución	`GET /v1/streaming/manifest`

Si cambias STREAMING_CLOUDEVENTS_SOURCE, el tema y cada ce-type cambian con él. Cuando el streaming está activado, la API sirve el catálogo de eventos en GET /v1/streaming/manifest. La ruta requiere el recurso streaming del Access Manager con la acción get.

Entrega

Cada evento tiene uno de estos tres modos de entrega:

Outbox: la API escribe el evento en su outbox de PostgreSQL, y un relay lo publica en Kafka.
Directa, con fallback al outbox: la API publica el evento en Kafka. Si los brokers no están disponibles o responden lento, la API escribe el evento en el outbox.
Mejor esfuerzo: la API publica el evento en Kafka, sin outbox.

Publicar un evento nunca hace fallar la operación de negocio que lo produjo. Un evento puede llegar más de una vez: deduplica según (ce-source, ce-id) y mantén los consumidores idempotentes. No dependas del orden de llegada.

Catálogo de eventos

Cobranzas

Clave del evento	Se dispara cuando	Entrega
`collection.created`	BTG registra una cobranza Pix, y la API la guarda como `ACTIVE`. Se dispara para cobranzas inmediatas y con vencimiento. El campo `type` las distingue.	Directa, con fallback al outbox
`collection.updated`	BTG acepta un cambio en una cobranza `ACTIVE`, y la API guarda la cobranza con una nueva revisión.	Directa, con fallback al outbox
`collection.deleted`	BTG acepta la eliminación de una cobranza inmediata `ACTIVE`, y la API la guarda como `DELETED`.	Directa, con fallback al outbox
`collection.completed`	Una cobranza pasa de `ACTIVE` a `COMPLETED`: su pago se liquida, o el endpoint de operador la completa.	Outbox

Claves DICT y reclamaciones

Clave del evento	Se dispara cuando	Entrega
`dict_entry.created`	Una clave Pix se guarda como `ACTIVE` para una de tus cuentas: por la API, por la conciliación, o cuando una reclamación se completa a tu favor.	Directa, con fallback al outbox
`dict_entry.updated`	El DICT acepta un cambio en los datos de la cuenta o del dueño de una clave, y la API lo guarda.	Directa, con fallback al outbox
`dict_entry.deleted`	Una clave sale de tu cuenta: la eliminas, la conciliación la quita, o el donante confirma una reclamación sobre ella.	Directa, con fallback al outbox
`claim.created`	Existe una reclamación de portabilidad o de titularidad para una clave: la abres como reclamante, o BTG informa una reclamación que otro participante abrió sobre tu clave.	Outbox
`claim.acknowledged`	El donante da acuse de la reclamación, y la reclamación pasa a `WAITING_RESOLUTION`.	Directa, con fallback al outbox
`claim.confirmed`	El donante confirma la reclamación.	Outbox
`claim.completed`	La reclamación llega a `COMPLETED`, y la clave pertenece al reclamante en el DICT.	Outbox
`claim.cancelled`	La reclamación llega a `CANCELLED`, y la clave queda con el donante.	Outbox

Recuperación de fondos de MED 2.0

Clave del evento	Se dispara cuando	Entrega
`funds_recovery.created`	Existe una recuperación de fondos: la creas, o BTG informa una que la API no tenía.	Outbox
`funds_recovery.tracked`	La recuperación de fondos pasa a `TRACKED`, y su grafo de rastreo está disponible.	Directa, con fallback al outbox
`funds_recovery.awaiting_analysis`	La recuperación de fondos pasa a `AWAITING_ANALYSIS`.	Outbox
`funds_recovery.analysed`	La recuperación de fondos pasa a `ANALYSED`.	Outbox
`funds_recovery.refund_requested`	La recuperación de fondos pasa a `REFUNDING`.	Outbox
`funds_recovery.completed`	BTG informa la recuperación de fondos como `COMPLETED`.	Outbox
`funds_recovery.cancelled`	La recuperación de fondos pasa a `CANCELLED`.	Outbox

Informes de infracción y solicitudes de devolución de MED

Clave del evento	Se dispara cuando	Entrega
`infraction.created`	Existe un informe de infracción: lo abres, o BTG entrega uno que una contraparte abrió contra tu cliente.	Outbox
`infraction.acknowledged`	Un informe de infracción pasa de `OPEN` a `ACKNOWLEDGED`.	Directa, con fallback al outbox
`infraction.closed`	Un informe de infracción llega a `CLOSED` con su resultado de análisis.	Outbox
`infraction.cancelled`	Un informe de infracción llega a `CANCELLED`.	Outbox
`refund_request.created`	Existe una solicitud de devolución de MED: la creas, o BTG entrega una que creó una contraparte.	Outbox
`refund_request.closed`	Una solicitud de devolución llega a `CLOSED` con su resultado y el monto devuelto.	Outbox
`refund_request.cancelled`	Una solicitud de devolución llega a `CANCELLED`.	Outbox

Cash-in y devoluciones

Clave del evento	Se dispara cuando	Entrega
`cashin.received`	La API acepta un Pix entrante y lo guarda como `CREATED`. Ningún crédito ocurre en este paso.	Directa, con fallback al outbox
`cashin.completed`	Un Pix entrante se liquida, y la API lo acredita en la cuenta en Midaz.	Outbox
`cashin.failed`	BTG informa un error para un Pix entrante aceptado, y la API lo guarda como `REJECTED`. No se acredita nada.	Outbox
`refund.created`	Existe una devolución para una de tus cuentas. El campo `type` (`CASHOUT` o `CASHIN`) da su dirección.	Directa, con fallback al outbox
`refund.processing`	Una devolución que envías (`CASHOUT`) pasa a `PROCESSING`.	Directa, con fallback al outbox
`refund.completed`	Una devolución se liquida y pasa a `COMPLETED`.	Outbox
`refund.rejected`	BTG o la liquidación intra-PSP rechaza una devolución en curso, y la API la guarda como `REJECTED`.	Outbox
`refund.failed`	Una devolución que envías (`CASHOUT`) no se puede ejecutar, y la API la guarda como `FAILED`.	Outbox

Cash-out, iniciación de pago y programaciones

Clave del evento	Se dispara cuando	Entrega
`payment_initiation.created`	Una iniciación de pago (`MANUAL`, `KEY` o `QR_CODE`) pasa la validación, y la API la guarda como `PENDING`.	Directa, con fallback al outbox
`cashout.created`	La API guarda un cash-out como `CREATED`.	Directa, con fallback al outbox
`cashout.processing`	El proveedor acepta el cash-out, y la API lo guarda como `PROCESSING`.	Directa, con fallback al outbox
`cashout.completed`	El cash-out se liquida, y la API lo guarda como `COMPLETED`.	Outbox
`cashout.rejected`	BTG o la liquidación intra-PSP rechaza un cash-out que llegó al proveedor, y la API lo guarda como `REJECTED`.	Outbox
`cashout.failed`	El cash-out falla antes de que el proveedor lo acepte, y la API lo guarda como `FAILED`.	Outbox
`schedule.created`	La API guarda un Pix programado como `SCHEDULED`.	Directa, con fallback al outbox
`schedule.cancelled`	Se cancela una programación `SCHEDULED`.	Directa, con fallback al outbox
`schedule.attempt_failed`	Un intento falla por saldo insuficiente, y la programación espera un nuevo intento el mismo día.	Mejor esfuerzo
`schedule.executed`	Un Pix programado se ejecuta y se liquida.	Outbox
`schedule.failed`	Un Pix programado llega a `FAILED` después de su último intento.	Outbox

Autorizaciones de Pix Automático

Clave del evento	Se dispara cuando	Entrega
`authorization_request.created`	La API guarda una solicitud de autorización para una cuenta pagadora: BTG la entrega, o confirmas un código QR de Pix Automático para el pagador.	Directa, con fallback al outbox
`authorization_request.approved`	BTG da acuse de la aprobación del pagador, y la solicitud pasa a `APPROVING`. El mandato no existe en este paso.	Directa, con fallback al outbox
`authorization_request.confirmed`	BTG confirma la aprobación, y la solicitud llega a `CONFIRMED`.	Outbox
`authorization_request.rejected`	La solicitud llega a `REJECTED`: el pagador la rechaza, o BTG informa un rechazo.	Outbox
`authorization_request.cancelled`	BTG informa la cancelación de una solicitud antes de su confirmación.	Outbox
`authorization_request.expired`	La solicitud llega a `EXPIRED` sin una decisión.	Outbox
`authorization_request.reply_failed`	La API no puede entregar la decisión del pagador a BTG, y la solicitud llega a `REPLY_FAILED`.	Directa, con fallback al outbox
`authorization_request.payment_failed`	El Pix inmediato de una solicitud de pay-and-confirm no se liquida, y la solicitud llega a `PAYMENT_FAILED`. No se crea ningún mandato.	Outbox
`recurring_authorization.authorized`	Un mandato de Pix Automático entra en vigor para una cuenta pagadora.	Outbox
`recurring_authorization.cancelled`	Se cancela un mandato por la API, y sus cobros programados futuros se cancelan con él.	Outbox
`recurrence.completed`	Se ejecuta el último cobro permitido de una recurrencia, y la recurrencia termina.	Outbox
`recurrence.expired`	Una recurrencia llega a su fecha final, y termina.	Outbox

Cobros de Pix Automático

Clave del evento	Se dispara cuando	Entrega
`recurring_charge.received`	Un cobro de Pix Automático llega desde BTG, y la API lo guarda como `RECEIVED`.	Directa, con fallback al outbox
`recurring_charge.scheduled`	La API programa un intento de débito para un cobro: el cobro pasa las verificaciones de aceptación, o un intento fallido tiene reintentos restantes.	Directa, con fallback al outbox
`recurring_charge.rejected`	Las verificaciones de aceptación rechazan un cobro recibido. No se debita al pagador.	Outbox
`recurring_charge.executed`	Se debita al pagador por un cobro.	Outbox
`recurring_charge.failed`	El último intento de débito permitido falla. No se debita al pagador.	Outbox
`recurring_charge.cancelled`	Se cancela un cobro programado: se cancela su mandato, o se cancela su programación.	Directa, con fallback al outbox

API de DICT

API de Reclamaciones

MED · Infracciones

MED · Marcadores de fraude

MED · Solicitudes de devolución

MED · Estadísticas

API de Transacciones

API de Códigos QR

API de Cobros

API de Recuperación de Fondos

API de Conciliación

API de Pix Automático

API de Programaciones

API de Informes de Transacción

Tiempos de transacciones

API de Webhooks

Manejo de errores

Eventos

Eventos de Pix Indirect via BTG

Contrato de transporte

Entrega

Catálogo de eventos

Cobranzas

Claves DICT y reclamaciones

Recuperación de fondos de MED 2.0

Informes de infracción y solicitudes de devolución de MED

Cash-in y devoluciones

Cash-out, iniciación de pago y programaciones

Autorizaciones de Pix Automático

Cobros de Pix Automático

​Contrato de transporte

​Entrega

​Catálogo de eventos

​Cobranzas

​Claves DICT y reclamaciones

​Recuperación de fondos de MED 2.0

​Informes de infracción y solicitudes de devolución de MED

​Cash-in y devoluciones

​Cash-out, iniciación de pago y programaciones

​Autorizaciones de Pix Automático

​Cobros de Pix Automático

Contrato de transporte

Entrega

Catálogo de eventos

Cobranzas

Claves DICT y reclamaciones

Recuperación de fondos de MED 2.0

Informes de infracción y solicitudes de devolución de MED

Cash-in y devoluciones

Cash-out, iniciación de pago y programaciones

Autorizaciones de Pix Automático

Cobros de Pix Automático