Automação de cobrança: o que decidir antes de deixar o sistema cobrar sozinho

Automação de cobrança não é "mandar boleto sozinho". É garantir que o valor certo seja cobrado da pessoa certa, uma única vez, e que o seu sistema saiba com certeza quando isso realmente aconteceu, sem depender de alguém checando o extrato manualmente.

Depois de integrar gateway de pagamento e montar régua de cobrança automática em produção, essas são as decisões que separam uma automação confiável de uma que assusta o cliente com cobrança errada.

O webhook de pagamento precisa de assinatura validada

Todo gateway sério (PIX, boleto, cartão) manda um webhook quando o status de um pagamento muda: pago, cancelado, estornado. O erro mais comum é tratar esse POST como verdade absoluta só porque chegou na URL certa.

Qualquer pessoa pode descobrir a URL do seu webhook e mandar um POST forjado dizendo "isso foi pago". A defesa é validar a assinatura que o gateway envia junto (normalmente um header com hash HMAC do corpo da requisição, calculado com uma chave secreta que só você e o gateway conhecem). Se a assinatura não bate, o evento é descartado, não processado.

Isso não é paranoia: é o mesmo princípio usado pra validar licença por HMAC quando o dado de verificação passa por um canal que não é totalmente controlado. Se alguém pode forjar o payload, alguém vai tentar.

Idempotência por ID da transação, nunca por valor

Webhook de pagamento é reenviado com frequência, por instabilidade de rede, por retry automático do próprio gateway, por timeout na sua resposta. Se a automação processa "cobrança recebida" cada vez que o webhook chega, uma cobrança de R$ 200 pode virar duas baixas de R$ 200 no seu financeiro.

A chave de idempotência aqui é o ID da transação que o gateway gera, nunca o valor ou a data. Dois pagamentos diferentes podem ter o mesmo valor no mesmo dia (dois clientes pagando a mesma mensalidade), então "valor + data" não identifica uma cobrança de forma única. Antes de dar baixa, checar se aquele ID de transação já foi processado. Se já foi, responder OK pro gateway sem repetir a ação.

O que fazer quando o webhook não chega

Servidor fora do ar no segundo exato em que o webhook chegou, fila travada, deploy no meio da hora errada: existe sempre uma chance real do evento se perder. Se a única fonte de verdade for o webhook, uma cobrança pode ficar marcada como pendente pra sempre mesmo tendo sido paga de verdade.

O fallback recomendado é reconciliação periódica: um job que roda algumas vezes por dia e consulta a API do gateway perguntando o status real de toda cobrança ainda marcada como pendente há mais de X horas. O webhook resolve a velocidade, a reconciliação resolve a confiabilidade.

Nunca guarde dado de cartão, use o token do provedor

Isso não é sobre boa prática abstrata, é sobre responsabilidade legal. Guardar número de cartão, CVV ou qualquer dado sensível de pagamento no próprio banco coloca o sistema dentro do escopo de PCI-DSS, que é caro e complexo de cumprir corretamente.

Todo gateway sério oferece tokenização: você recebe um token que representa aquele cartão, sem nunca tocar no dado real. Guarde o token, não o cartão. Se um dia o banco de dados vazar, o token sozinho não serve pra nada fora daquele gateway.

Régua de cobrança automática sem virar spam

Automatizar a cobrança de inadimplência é onde mais se vê automação boa virar automação que afasta cliente. Enviar lembrete todo dia, em todos os canais ao mesmo tempo, sem limite, transforma uma régua de cobrança em assédio.

O que funciona: espaçamento crescente entre tentativas (não o mesmo intervalo toda vez), limite máximo de tentativas antes de escalar pra um humano decidir o próximo passo, e canal condizente com o valor e o tempo de atraso (mensagem simples pros primeiros dias, contato mais direto quando o atraso é longo). A régua automática deve saber quando parar de insistir sozinha.

Ferramentas que eu recomendo de verdade

Asaas: gateway brasileiro com PIX, boleto e cartão, webhook nativo pra cada mudança de status, e ambiente de sandbox real pra testar antes de ir pra produção. Prefiro ele quando o cliente já opera com CPF/CNPJ brasileiro e precisa de PIX como opção principal.

n8n: pra orquestrar a régua de cobrança em si (quando mandar o próximo lembrete, por qual canal, quando escalar pra humano) sem deixar essa lógica espalhada em código dentro do backend principal.

Supabase: como registro histórico de cada tentativa de cobrança e cada webhook recebido, mesmo os que não geraram ação. Esse histórico é o que permite reconstruir "o que aconteceu" quando um cliente questiona uma cobrança.

Cuidados que custam caro se ignorados

• Nunca processe webhook sem validar assinatura. Um POST forjado marcando uma cobrança como paga sem ter sido pode liberar produto ou serviço de graça.
• Nunca logue dado de pagamento em texto puro, nem token, nem os últimos dígitos completos do cartão, em nenhum log de debug.
• Idempotência por ID de transação, nunca por valor e data. É o erro mais fácil de cometer e mais caro de descobrir tarde.
• Reconciliação periódica não é opcional se o webhook é a única fonte de verdade da automação.

Automação de cobrança bem feita é invisível: o cliente paga, o sistema sabe, ninguém precisa conferir extrato na mão. Ela aparece exatamente quando um desses cuidados foi ignorado, e nesse caso aparece do jeito mais caro possível.