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 que uso pra validar licença por HMAC quando o dado de verificação passa por um canal que eu não controlo totalmente. 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 que uso é 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 seu próprio banco te coloca 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 seu banco de dados vazar, o token sozinho não serve pra nada fora do seu gateway.
Régua de cobrança automática sem virar spam
Automatizar a cobrança de inadimplência é onde mais vejo 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. Já expliquei o porquê acima, mas vale repetir: é 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.
Nayara Martins, desenvolvedora de sistemas sob medida em Assis, SP. Mais em prospectia.space.
Top comments (0)