Problemas Com Sistema Monetário

Como identificar e resolver problemas com sistemas monetários na prática

Se você está lidando com problemas com sistema monetário no seu negócio ou na sua operação financeira, provavelmente já passou por alguma dessas situações: uma transação que não aparece no extrato, um saldo que não bate com a conciliação automática, ou um cliente dizendo que pagou e o sistema dizendo que não recebeu. Isso é mais comum do que parece, e na maioria das vezes não é um bug — é configuração, integração mal ajustada ou regra de negócio que ninguém documentou. Antes de falar de soluções, preciso deixar claro onde a coisa costuma quebrar. Sistemas monetários modernos não são monolíticos. Eles são compostos por gateway de pagamento, processador, acquirer, split de pagamento, antifraude, conciliação automática e, em muitos casos, módulos de faturamento recorrente. Cada um desses componentes fala com o outro por API, e cada conexão é um ponto potencial de falha. O erro raramente está no motor principal. Está nas fronteiras entre os módulos.

diagnóstico de problemas com sistema monetário

A primeira coisa que eu faço quando alguém me procura com um problema de moeda é pedir o ID da transação e o timestamp exato. Sem isso, você está navegando no escuro. A maioria dos suportes técnicos pede essas informações, mas raramente explica por quê. O ID da transação permite rastrear o ciclo completo: autorização, capture, settlement e reconciliação. O timestamp é crucial porque muitos problemas aparecem apenas em janelas específicas — virada de dia, renovação de chave de criptografia, mudanças de taxa de câmbio em lotes noturnos. No meu caso, tive uma situação recorrente com um cliente de e-commerce que usava Stripe e Mercado Pago em paralelo. O problema era intermitente: transações em BRL pareciam ser autorizadas, mas a conciliação diária fechava com saldo negativo. Levei três dias para isolar. O problema não estava no gateway, nem no processador, nem na conta do cliente. Estava na configuração de rateio (split) onde o campo country_code da subconta estava definido como US em vez de BR. Isso causava conversão cambial duplamente aplicada — uma pela tarifa do gateway e outra pelo spread do acquirer. A correção foi ajustar o mapeamento de subcontas e rodar um job de retrabalho nas 47 transações daquele mês. Custou cerca de 6 horas de desenvolvimento e 15 minutos de configuração.

Se você quer diagnosticar problemas de forma sistemática, comece pelo fluxo reverso. Não observe apenas o que o sistema diz que aconteceu. Observe o que o banco disse que realmente aconteceu. Extraia os arquivos de retorno do seu acquirer, compare linha a linha com os logs da sua API, e identifique onde as divergências começam. Uma planilha simples com colunas para transaction_id, status_api, status_bank, amount_original, amount_converted e fee_applied resolve 80% dos casos em menos de uma hora. Outro ponto que poucos consideram é a diferença entre status de autorização e status de liquidação. Uma transação pode vir como approved na API e ainda assim não aparecer no saldo disponível do vendedor. Isso acontece porque o money movement tem etapas: authorization hold, capture, batch settlement, funding. Cada uma tem seu próprio tempo e suas próprias regras de falha. O cliente vê approved e acha que o dinheiro caiu. O sistema mostra pendente porque está na etapa de settlement. Essa lacuna de compreensão é responsável por uma quantidade absurda de tickets de suporte que na verdade são expectativas mal gerenciadas, não bugs reais.

Quando se trata de correções, a hierarquia de prioridade que eu uso é sempre a mesma: primeiro resolvo a reconciliação, depois a experiência do cliente, e só então investigo a causa raiz. Isso pode parecer contraintuitivo, mas reconciiliar o saldo corretamente evita que você tome decisões baseadas em números errados. Já vi pessoas cancelarem reembolsos porque o sistema mostrava saldo zerado, quando na verdade o dinheiro estava retido em settlement com um atraso de 2 dias úteis. Cancelar o reembolso naquela situação gerava estorno duplo e uma dor de cabeça legal que podia levar semanas para resolver. Um detalhe técnico importante que muitos ignoram: a precisão decimal. Sistemas monetários usam either floating point (errado) ou decimal/bigDecimal (correto). Se o seu sistema armazena valores monetários como float, você vai ter problemas de arredondamento que parecem aleatórios mas na verdade seguem padrões matemáticos previsíveis. O problema aparece principalmente em conversões de moeda e cálculos de taxa percentual. Um valor de 19,99 multiplicado por 0,15 pode resultar em 2,9984999999999997 em vez de 2,9985. Over time, esses erros se acumulam e geram discrepâncias que parecem fraude até você entender o que está acontecendo. A correção é simples — usar tipos decimais em todas as operações financeiras — mas em sistemas legados isso pode significar uma reescrita significativa.

Se você está começando do zero e precisa de uma base para montar seu sistema, existem opções open source que valem a pena considerar. O moqit é um projeto brasileiro que oferece uma camada de abstração para operação com múltiplos gateways. O código está no GitHub e a documentação cobre os casos mais comuns de split, recorrência e conciliação. Para quem trabalha com volumes maiores, o padrão industry é implementar uma camada de orquestração própria com filas assíncronas para cada evento monetário — authorization, capture, refund, chargeback. Cada um desses eventos deve ter seu próprio log, sua própria tabela de retry com backoff exponencial, e sua própria capacidade de rollback. O problema é que a maioria das empresas pula essa camada. Elas conectam o gateway direto no banco de dados e confiam na resiliência da API do provedor. APIs caem. Connection timeouts acontecem. Webhooks chegam fora de ordem. Sem uma camada de orquestração, você perde transações ou processa as mesmas transações duas vezes. Eu vi um case recente onde um marketplace processou o mesmo pagamento três vezes porque o webhook de confirmação foi recebido antes do webhook de autorização e o sistema não tinha controle de idempotência. O prejuízo foi de R$ 47.000 em 48 horas.

O que eu recomendo para quem está enfrentando problemas no momento é o seguinte: isole o problema primeiro. Anote exatamente o que está errado, quando começou, quantas transações estão afetadas e se há um padrão (mesmo valor, mesma moeda, mesmo horário, mesmo gateway). Depois disso, pare de mexer na código até ter esse diagnóstico. Mudanças às cegas em sistemas monetários são a forma mais rápida de transformar um problema recuperável em uma situação catastrófica. Se o problema for de reconciliação, rode um script de comparação entre sua base e o arquivo de retorno do acquirer. Se for de API, verifique os headers de request e response, especialmente campos como x-request-id e idempotency-key. Se for de configuração de moeda, confirme o currency_code em cada ponto do fluxo — gateway, processador, subconta, reporte. Uma última coisa que vale a pena mencionar: a questão tributária. Problemas com sistema monetário muitas vezes se confundem com problemas de reporte fiscal. Um gateway pode reportar o valor bruto, outro o valor líquido, outro com classificação diferente de receita. Se você não padroniza isso desde o início, no final do trimestre vai ter uma divergência entre o que o sistema financeiro mostra e o que o contador precisa declarar. Não é um bug técnico. É um problema de modelagem de dados que só se revela quando você precisa gerar um relatório fiscal. Configure desde o começo campos separados para valor_bruto, taxa_aplicada, fee_gateway, valor_liquido_e_recebedor, e mantenha esses valores imutáveis após a confirmação da transação.

Aprender a lidar com esses sistemas exige paciência e rigidez. Não existe solução mágica. Existe entendimento do fluxo,_logging_bom_suficiente, e_a_correção_certa_no_momento_certo.