Payment Status Reconciliation - Documentação DEVMOB

Payment Status Reconciliation é a rotina periódica que corrige drift entre o estado local de Payment e o estado do provider.

Objetivo

A rotina complementa webhooks e filas assíncronas, garantindo que pagamentos pendentes ou em processamento não fiquem presos em estado antigo.

Ao rodar, a rotina:

Busca pagamentos com externalProvider e externalProviderId.
Filtra pagamentos em estados não terminais, como PENDING, PROCESSING e estados de antifraude.
Consulta o provider de billing.
Atualiza status, paidAt, overdueAt, canceledAt e demais campos aplicáveis conforme resposta do provider.

Regra	Comportamento
Fonte externa	O provider é a fonte de verdade para status de cobrança externa.
Estados terminais	Pagamentos `PAID`, `CANCELED`, `PAYMENT_FAILED`, `REFUNDED` ou `CHARGEDBACK` não devem ser reabertos pela rotina.
Vencimento	`dueDate` e `overdueAt` representam vencimento local quando aplicável.
Idempotência	Reprocessar o mesmo status não deve gerar efeitos duplicados.
Escopo	A rotina atua apenas em pagamentos conhecidos pelo DEVMOB.