Uma resposta de API pode dizer que a solicitação foi aceita. Um webhook pode notificar novo status. Nenhum dos dois, sozinho, prova que o recebedor obteve o valor esperado, o pedido avançou corretamente, o ledger interno fechou e a contabilidade recebeu o lançamento certo. Sistemas financeiros confiáveis preservam evidência em todas as camadas.
Pix opera continuamente, mas a aplicação observa momentos diferentes: criação da cobrança, consentimento, autorização, ordem, liquidação, crédito na conta recebedora, notificação, lançamento no ledger, liberação do pedido, devolução e fechamento contábil. A iniciação via Open Finance adiciona recursos de consentimento e pagamento com máquinas de estados próprias.
Não reduza tudo a um booleano pago. Cada transição precisa de fonte, identificador, event time, receive time, valor, status, motivo e confiança. O negócio define qual evidência autoriza liberar estoque, ativar serviço, permitir saque, devolver e reconhecer receita.
Criar cobrança dinâmica ou recurso de pagamento registra uma possibilidade de pagamento, não a movimentação. A autorização confirma intenção no escopo do consentimento. Liquidação é a transferência concluída pela infraestrutura. Crédito e disponibilidade podem ser observados por API, extrato ou arquivos do PSP.
Webhook reduz latência, mas continua sendo um canal de evidência. Autentique, grave de forma imutável e confirme outcomes críticos em endpoint autoritativo ou movimentação da conta. Webhook perdido não pode esconder pagamento liquidado; webhook falso ou repetido não pode liberar valor.
Timeout pode ocorrer depois que o PSP aceitou o request. Repetir com outro identificador pode criar cobrança ou pagamento adicional. Gere a chave antes da primeira tentativa e vincule merchant, tipo, valor, destino e hash do payload; retenha resposta e estado originais.
Eventos recebidos também exigem dedupe. Use ID do provedor quando existir e imponha unicidade sobre PSP, txid, end-to-end ID, evento e versão. Notificação repetida deve devolver o mesmo journal e a mesma transição.
A tabela de payment serve como projeção atual. Para integridade financeira, use ledger append-only de partidas dobradas em que cada journal fecha e referencia o evento-fonte. Separe recebível, clearing, caixa disponível, saldo do cliente, payable, taxa, liability de devolução, perda e suspense conforme o produto.
Não edite lançamento histórico para “corrigir”. Registre reversão ou ajuste com motivo e autorização. Teste invariantes: débitos igualam créditos, moeda consistente, regras das contas respeitadas e toda liberação aponta para journal committed.
Conciliação operacional compara inbox de webhook com API do PSP. Conciliação de caixa compara transações do provedor/banco com ledger de cash e clearing. Conciliação de negócio compara recebíveis pagos com pedidos, faturas e assinaturas. Conciliação contábil compara saldos e exports com o razão geral.
Cada execução tem frequência e tolerância próprias. Near real-time encontra pedido pago travado. Intraday encontra posting ausente ou duplicado. Fechamento diário captura taxas, devoluções, virada de data e arquivos que falharam após sucesso operacional.
Primeiro use end-to-end ID, txid, payment ID, transação do PSP, conta, valor e moeda. Depois aplique chaves secundárias restritas: janela de liquidação, pagador/recebedor, referência e transformações conhecidas. Match fuzzy não deve movimentar dinheiro ou baixar fatura automaticamente sem policy de confiança.
Valor sem correspondência vai para suspense com owner e aging. Liquidações parciais ou agregadas exigem regras explícitas. Registre por que houve match, campos iguais, divergências e aprovação humana.
| Divergência | Causa provável | Check automático | Ação segura | Evidência |
|---|---|---|---|---|
| PSP liquidou; pedido pendente | Webhook perdido, worker, lock ou versão de schema. | Consultar payment e localizar journal/transição pelos IDs. | Lançar/aplicar idempotentemente se invariantes passarem. | Evento, API, journal, trace e versão do pedido. |
| Pedido pago sem caixa | Evento falso, mapeamento precoce, ambiente errado ou override. | Checar PSP, extrato, conta, valor, credencial e ambiente. | Congelar liberação/payout e investigar com prioridade. | Ator, regra, payload, extrato e trilha de auth. |
| Pagamento duplicado | Retry com nova chave, duas cobranças ou replay. | Agrupar pedido, valor, pagador, tempo e IDs. | Não mesclar; aplicar policy de devolução/crédito. | Comprovantes, intenção e elegibilidade. |
| Valor divergente | Cobrança stale, desconto, taxa, parcial ou fatura errada. | Comparar bruto, líquido, taxa, esperado e quote. | Suspense ou alocação parcial. | Cobrança, fatura, tarifa, extrato e policy. |
| Devolução divergente | Pendente, parcial, transação errada ou duplicidade. | Vincular original, return ID, valor, status, journal e caso. | Lançar apenas estado verificado; manter liability pendente. | Original, devolução, motivo, aprovação e ledger. |
| Consentimento autorizado; sem pagamento | Jornada interrompida, rejeição, expiração ou falha do participante. | Ler consent e payment separadamente com reason codes. | Mostrar estado correto e iniciar nova jornada sem reusar autoridade inválida. | IDs, horários, client, participante e histórico. |
Reembolso comercial decorre da relação com o cliente. A devolução Pix usa mecanismos e identificadores do arranjo. O MED atende cenários específicos de fraude e não substitui estorno comum nem prevenção.
Modele solicitado, aprovado, enviado, processando, concluído, rejeitado, cancelado, parcial e falhou. Reserve liability quando a empresa assume o compromisso, mas marque caixa devolvido apenas com evidência do rail. O total não pode exceder o valor elegível.
Iniciação envolve consentimento, autorização, client, participante, resource status e jornadas redirecionadas ou desacopladas. Preserve o histórico. O pagamento não pode exceder escopo, valor, credor, agenda ou validade autorizada.
Use controles FAPI: autenticação forte de client, acesso sender-constrained quando especificado, validação exata, autoridade curta, rotação de chaves, assinaturas quando exigidas, defesa contra replay e testes de conformidade. Registre versão da API e participante em cada trace.
Avalie idade da conta, mudança de device/sessão, histórico do beneficiário, valor, velocidade, horário, local, canal, comportamento, indícios de golpe e limites. Durante autorização, preserve o que foi exibido e aprovado. Depois, monitore contas relacionadas, devoluções, disputas, mule indicators e recuperação.
Modelos precisam de reason codes e calibração. Meça perda evitada junto de falso positivo, abandono, acessibilidade, tempo de análise, reclamação e recuperação.
Correlacione pedido, consentimento, cobrança, recurso, webhook, consulta, end-to-end ID, extrato, journal, transição, devolução e caso. Meça lag, dedupe, tempo de transição, valor sem match, idade de suspense, tentativas de quebrar o ledger, fechamento e backlog de exceções.
Alertas devem considerar valor e idade. Dez divergências pequenas não equivalem a um pedido alto liberado sem caixa.
Simule timeout após aceite, requests duplicados, webhook perdido/fora de ordem, PSP indisponível, liquidação tardia, API versus extrato, virada do dia, devolução parcial, estorno duplicado, ID malformado, precisão monetária, rotação de chave, consentimento expirado e retomada após deploy.
Execute fechamento diário simulado: delimite janela, trate late entries, concilie saldos, gere relatório, exporte journals e prove que rerun não duplica.
Eu construiria um payment control plane com adapters de PSP, outbox de requests, inbox imutável, state machines de consentimento e pagamento, gateway de risco, verificador, ledger de partidas dobradas, serviço de transição, motor de conciliação, suspense, console de exceções e export contábil.
Cada adapter preservaria o código externo e mapearia para vocabulário interno versionado. Correções automáticas seriam idempotentes, explicáveis e reversíveis por novo journal.
Liquidação rápida não elimina complexidade contábil; apenas reduz o tempo para tratá-la. Sistemas Pix e Open Finance confiáveis separam estados, preservam IDs, lançam partidas imutáveis, verificam evidências independentes e dão owner a cada divergência.
Artigo sobre pipelines de Pix e Open Finance no Brasil, incluindo máquinas de estados, consentimento, idempotência, liquidação, ledger de partidas dobradas, matching, devoluções, MED, antifraude, exceções, testes e observabilidade.