Eventos do Pix Indirect via BTG

O Pix Indirect via BTG publica 63 fatos de negócio JSON como CloudEvents 1.0 em modo binário de conteúdo via Kafka. Estes eventos estão disponíveis em deploys BYOC. O streaming é opcional e fica desligado por padrão. Para ligá-lo, defina STREAMING_ENABLED=true e as outras variáveis de eventos de negócio no componente da API. A visão geral de streaming de eventos descreve o envelope comum.

Contrato de transporte

Campo	Valor
`ce-source`	O valor de `STREAMING_CLOUDEVENTS_SOURCE`. O padrão é `plugin-br-pix-indirect-btg`.
Tópico	`lerian.streaming.<ce-source>`
`ce-type`	`studio.lerian.<ce-source>.<event-key>`
`ce-tenantid`	O valor de `STREAMING_TENANT_ID`. O padrão é `default`.
Versão do schema	`1.0.0` para todo evento
Tipo de conteúdo	`application/json`
Entrega	Definida por evento. Veja Entrega.
Tópico de comandos	Nenhum
Manifesto em runtime	`GET /v1/streaming/manifest`

Se você mudar STREAMING_CLOUDEVENTS_SOURCE, o tópico e cada ce-type mudam junto. Quando o streaming está ligado, a API serve o catálogo de eventos em GET /v1/streaming/manifest. A rota exige o recurso streaming do Access Manager com a ação get.

Entrega

Cada evento tem um destes três modos de entrega:

Outbox: a API escreve o evento no seu outbox do PostgreSQL, e um relay o publica no Kafka.
Direta, com fallback para o outbox: a API publica o evento no Kafka. Se os brokers estiverem indisponíveis ou lentos, a API escreve o evento no outbox.
Melhor esforço: a API publica o evento no Kafka, sem outbox.

A publicação de um evento nunca faz falhar a operação de negócio que o produziu. Um evento pode chegar mais de uma vez: deduplique por (ce-source, ce-id) e mantenha os consumidores idempotentes. Não dependa da ordem de chegada.

Catálogo de eventos

Cobranças

Chave do evento	Dispara quando	Entrega
`collection.created`	O BTG registra uma cobrança Pix, e a API a guarda como `ACTIVE`. Dispara para cobranças imediatas e com vencimento. O campo `type` as diferencia.	Direta, com fallback para o outbox
`collection.updated`	O BTG aceita uma alteração em uma cobrança `ACTIVE`, e a API guarda a cobrança com uma nova revisão.	Direta, com fallback para o outbox
`collection.deleted`	O BTG aceita a exclusão de uma cobrança imediata `ACTIVE`, e a API a guarda como `DELETED`.	Direta, com fallback para o outbox
`collection.completed`	Uma cobrança passa de `ACTIVE` para `COMPLETED`: o pagamento dela é liquidado, ou o endpoint de operador a conclui.	Outbox

Chaves DICT e reivindicações

Chave do evento	Dispara quando	Entrega
`dict_entry.created`	Uma chave Pix é guardada como `ACTIVE` para uma das suas contas: pela API, pela conciliação, ou quando uma reivindicação é concluída a seu favor.	Direta, com fallback para o outbox
`dict_entry.updated`	O DICT aceita uma alteração nos dados da conta ou do dono de uma chave, e a API a guarda.	Direta, com fallback para o outbox
`dict_entry.deleted`	Uma chave sai da sua conta: você a exclui, a conciliação a remove, ou o doador confirma uma reivindicação sobre ela.	Direta, com fallback para o outbox
`claim.created`	Existe uma reivindicação de portabilidade ou de posse para uma chave: você a abre como reivindicador, ou o BTG informa uma reivindicação que outro participante abriu sobre a sua chave.	Outbox
`claim.acknowledged`	O doador reconhece a reivindicação, e a reivindicação passa para `WAITING_RESOLUTION`.	Direta, com fallback para o outbox
`claim.confirmed`	O doador confirma a reivindicação.	Outbox
`claim.completed`	A reivindicação chega a `COMPLETED`, e a chave pertence ao reivindicador no DICT.	Outbox
`claim.cancelled`	A reivindicação chega a `CANCELLED`, e a chave fica com o doador.	Outbox

Recuperação de fundos do MED 2.0

Chave do evento	Dispara quando	Entrega
`funds_recovery.created`	Existe uma recuperação de fundos: você a cria, ou o BTG informa uma que a API não tinha.	Outbox
`funds_recovery.tracked`	A recuperação de fundos passa para `TRACKED`, e o grafo de rastreamento dela fica disponível.	Direta, com fallback para o outbox
`funds_recovery.awaiting_analysis`	A recuperação de fundos passa para `AWAITING_ANALYSIS`.	Outbox
`funds_recovery.analysed`	A recuperação de fundos passa para `ANALYSED`.	Outbox
`funds_recovery.refund_requested`	A recuperação de fundos passa para `REFUNDING`.	Outbox
`funds_recovery.completed`	O BTG informa a recuperação de fundos como `COMPLETED`.	Outbox
`funds_recovery.cancelled`	A recuperação de fundos passa para `CANCELLED`.	Outbox

Relatos de infração e solicitações de devolução do MED

Chave do evento	Dispara quando	Entrega
`infraction.created`	Existe um relato de infração: você o abre, ou o BTG entrega um que uma contraparte abriu contra o seu cliente.	Outbox
`infraction.acknowledged`	Um relato de infração passa de `OPEN` para `ACKNOWLEDGED`.	Direta, com fallback para o outbox
`infraction.closed`	Um relato de infração chega a `CLOSED` com o resultado da análise.	Outbox
`infraction.cancelled`	Um relato de infração chega a `CANCELLED`.	Outbox
`refund_request.created`	Existe uma solicitação de devolução do MED: você a cria, ou o BTG entrega uma que uma contraparte criou.	Outbox
`refund_request.closed`	Uma solicitação de devolução chega a `CLOSED` com o resultado e o valor devolvido.	Outbox
`refund_request.cancelled`	Uma solicitação de devolução chega a `CANCELLED`.	Outbox

Cash-in e devoluções

Chave do evento	Dispara quando	Entrega
`cashin.received`	A API aceita um Pix recebido e o guarda como `CREATED`. Nenhum crédito acontece nesta etapa.	Direta, com fallback para o outbox
`cashin.completed`	Um Pix recebido é liquidado, e a API o credita na conta no Midaz.	Outbox
`cashin.failed`	O BTG informa um erro para um Pix recebido aceito, e a API o guarda como `REJECTED`. Nada é creditado.	Outbox
`refund.created`	Existe uma devolução para uma das suas contas. O campo `type` (`CASHOUT` ou `CASHIN`) dá a direção dela.	Direta, com fallback para o outbox
`refund.processing`	Uma devolução que você envia (`CASHOUT`) passa para `PROCESSING`.	Direta, com fallback para o outbox
`refund.completed`	Uma devolução é liquidada e passa para `COMPLETED`.	Outbox
`refund.rejected`	O BTG ou a liquidação intra-PSP rejeita uma devolução em andamento, e a API a guarda como `REJECTED`.	Outbox
`refund.failed`	Uma devolução que você envia (`CASHOUT`) não pode ser executada, e a API a guarda como `FAILED`.	Outbox

Cash-out, iniciação de pagamento e agendamentos

Chave do evento	Dispara quando	Entrega
`payment_initiation.created`	Uma iniciação de pagamento (`MANUAL`, `KEY` ou `QR_CODE`) passa na validação, e a API a guarda como `PENDING`.	Direta, com fallback para o outbox
`cashout.created`	A API guarda um cash-out como `CREATED`.	Direta, com fallback para o outbox
`cashout.processing`	O provedor aceita o cash-out, e a API o guarda como `PROCESSING`.	Direta, com fallback para o outbox
`cashout.completed`	O cash-out é liquidado, e a API o guarda como `COMPLETED`.	Outbox
`cashout.rejected`	O BTG ou a liquidação intra-PSP rejeita um cash-out que chegou ao provedor, e a API o guarda como `REJECTED`.	Outbox
`cashout.failed`	O cash-out falha antes de o provedor aceitá-lo, e a API o guarda como `FAILED`.	Outbox
`schedule.created`	A API guarda um Pix agendado como `SCHEDULED`.	Direta, com fallback para o outbox
`schedule.cancelled`	Um agendamento `SCHEDULED` é cancelado.	Direta, com fallback para o outbox
`schedule.attempt_failed`	Uma tentativa falha por saldo insuficiente, e o agendamento espera uma nova tentativa no mesmo dia.	Melhor esforço
`schedule.executed`	Um Pix agendado é executado e liquidado.	Outbox
`schedule.failed`	Um Pix agendado chega a `FAILED` depois da última tentativa.	Outbox

Autorizações do Pix Automático

Chave do evento	Dispara quando	Entrega
`authorization_request.created`	A API guarda uma solicitação de autorização para uma conta pagadora: o BTG a entrega, ou você confirma um QR Code do Pix Automático para o pagador.	Direta, com fallback para o outbox
`authorization_request.approved`	O BTG reconhece a aprovação do pagador, e a solicitação passa para `APPROVING`. O mandato não existe nesta etapa.	Direta, com fallback para o outbox
`authorization_request.confirmed`	O BTG confirma a aprovação, e a solicitação chega a `CONFIRMED`.	Outbox
`authorization_request.rejected`	A solicitação chega a `REJECTED`: o pagador a rejeita, ou o BTG informa uma rejeição.	Outbox
`authorization_request.cancelled`	O BTG informa o cancelamento de uma solicitação antes da confirmação dela.	Outbox
`authorization_request.expired`	A solicitação chega a `EXPIRED` sem uma decisão.	Outbox
`authorization_request.reply_failed`	A API não consegue entregar a decisão do pagador ao BTG, e a solicitação chega a `REPLY_FAILED`.	Direta, com fallback para o outbox
`authorization_request.payment_failed`	O Pix imediato de uma solicitação de pay-and-confirm não é liquidado, e a solicitação chega a `PAYMENT_FAILED`. Nenhum mandato é criado.	Outbox
`recurring_authorization.authorized`	Um mandato do Pix Automático passa a valer para uma conta pagadora.	Outbox
`recurring_authorization.cancelled`	Um mandato é cancelado pela API, e as cobranças agendadas futuras dele são canceladas junto.	Outbox
`recurrence.completed`	A última cobrança permitida de uma recorrência é executada, e a recorrência termina.	Outbox
`recurrence.expired`	Uma recorrência chega à data final, e ela termina.	Outbox

Cobranças do Pix Automático

Chave do evento	Dispara quando	Entrega
`recurring_charge.received`	Uma cobrança do Pix Automático chega do BTG, e a API a guarda como `RECEIVED`.	Direta, com fallback para o outbox
`recurring_charge.scheduled`	A API agenda uma tentativa de débito para uma cobrança: a cobrança passa nas verificações de aceite, ou uma tentativa com falha tem novas tentativas restantes.	Direta, com fallback para o outbox
`recurring_charge.rejected`	As verificações de aceite recusam uma cobrança recebida. O pagador não é debitado.	Outbox
`recurring_charge.executed`	O pagador é debitado por uma cobrança.	Outbox
`recurring_charge.failed`	A última tentativa de débito permitida falha. O pagador não é debitado.	Outbox
`recurring_charge.cancelled`	Uma cobrança agendada é cancelada: o mandato dela é cancelado, ou o agendamento dela é cancelado.	Direta, com fallback para o outbox

API de DICT

API de Reivindicações

MED · Infrações

MED · Marcadores de fraude

MED · Solicitações de devolução

MED · Estatísticas

API de Transações

API de QR Codes

API de Cobranças

API de Recuperação de Fundos

API de Conciliação

API de Pix Automático

API de Agendamentos

API de Relatórios de Transação

Tempos de transações

API de Webhooks

Tratamento de erros

Eventos

Eventos do Pix Indirect via BTG

Contrato de transporte

Entrega

Catálogo de eventos

Cobranças

Chaves DICT e reivindicações

Recuperação de fundos do MED 2.0

Relatos de infração e solicitações de devolução do MED

Cash-in e devoluções

Cash-out, iniciação de pagamento e agendamentos

Autorizações do Pix Automático

Cobranças do Pix Automático

​Contrato de transporte

​Entrega

​Catálogo de eventos

​Cobranças

​Chaves DICT e reivindicações

​Recuperação de fundos do MED 2.0

​Relatos de infração e solicitações de devolução do MED

​Cash-in e devoluções

​Cash-out, iniciação de pagamento e agendamentos

​Autorizações do Pix Automático

​Cobranças do Pix Automático

Contrato de transporte

Entrega

Catálogo de eventos

Cobranças

Chaves DICT e reivindicações

Recuperação de fundos do MED 2.0

Relatos de infração e solicitações de devolução do MED

Cash-in e devoluções

Cash-out, iniciação de pagamento e agendamentos

Autorizações do Pix Automático

Cobranças do Pix Automático