Checklist antes de contratar uma integração de pagamento
O que pode falhar quando pagamentos são tratados como um projeto de uma semana.
A documentação de um gateway (serviço que processa pagamentos) faz a integração parecer simples. Basta um pedido POST enviado pelo seu sistema, uma resposta e um webhook (aviso automático do serviço).
O pedido que funciona raramente é o problema. O risco está nas falhas que podem aparecer às três da manhã.
Esta é a lista que confiro antes de colocar uma integração em produção (em uso real). Ela vem de sistemas de pagamento que construí para negócios reais, com Pix, cartão e boleto.
1. Verifique o webhook com HMAC, não com uma URL secreta
Um webhook sem verificação criptográfica aceita pedidos POST de qualquer origem. Se o sistema recebe a mensagem sem conferir a assinatura, alguém pode falsificar um aviso de pagamento aprovado.
O mínimo é HMAC-SHA256 (uma assinatura digital calculada com os dados e uma chave secreta). Só você e o gateway conhecem essa chave. Seu sistema confere essa assinatura antes de processar a mensagem. Uma URL secreta não protege o sistema. Só esconde o endereço até a primeira varredura automática.
No e-commerce de consultas veiculares que construí, cada notificação de pagamento passava pela validação HMAC. Só depois o sistema atualizava o status do pedido. Sem isso, o sistema confia em qualquer mensagem que recebe. Confiança não é proteção.
2. Evite processar o mesmo aviso duas vezes
O gateway pode enviar o mesmo webhook mais de uma vez. A rede falha, o tempo de espera termina ou o serviço tenta de novo. Se seu sistema processar a mensagem duas vezes, pode entregar o produto ou cobrar duas vezes.
Cada aviso precisa de um identificador único, como o ID da transação. Uma chave de idempotência também serve. Ela impede repetir a operação. Se o identificador já foi processado, o sistema responde 200 e não faz nada. Isso evita duplicidade sem depender de um gateway perfeito.
3. Compare os registros todos os dias
Um webhook é um aviso que chega depois do pagamento, e esse tipo de mensagem pode falhar. Pode não chegar, chegar atrasado ou o gateway pode parar justamente naquele momento.
A reconciliação compara todos os dias os pagamentos que o gateway diz ter recebido com os que seu sistema processou. Sem essa comparação, você só descobre um pagamento esquecido quando o cliente reclama. Quem reclama de dinheiro costuma ir embora em vez de reclamar outra vez.
4. O ambiente de teste não é o ambiente real
O sandbox é o ambiente de teste do gateway. O tempo de resposta e o comportamento podem mudar quando há demora. Ele também pode mostrar situações que nunca aparecem em produção, ou o contrário. Testar só no sandbox é testar um sistema diferente.
Eu testo no sandbox e também verifico falhas em produção com um valor mínimo, R$ 0,01 ou equivalente. Faço isso em horário controlado e acompanho o sistema. Se o gateway tiver um endereço para consultar se está funcionando, acompanho esse endereço antes e durante o teste.
5. Proteja os dados do cartão
Você não armazena o número do cartão. Ponto. Tokenização troca o número do cartão por um código. Se o gateway oferece isso, guarde o código. Nunca guarde o PAN (o número completo do cartão). Se o gateway não oferece tokenização, troque de gateway.
Dados de pagamento trazem responsabilidade proporcional ao dano. Vazar um e-mail é grave. Vazar dados de cartão pode acabar com uma empresa pequena. A multa da LGPD (Lei Geral de Proteção de Dados) é proporcional ao faturamento. O dano à reputação não tem teto.
6. Quem atende às três da manhã?
Pagamento não tem horário comercial. Se o Pix parar de processar sábado às 22h, o prejuízo pode crescer até segunda de manhã, se é que alguém vai perceber.
Antes de contratar a integração, defina quem será avisado, por qual canal e o que essa pessoa deve fazer. Se a resposta for "o desenvolvedor que construiu", ele precisa estar disponível para atender. Outra opção é reduzir o serviço com controle. O sistema pode mostrar uma mensagem, guardar o pedido para depois e avisar a equipe na manhã seguinte.
Onde isso falha
O erro mais comum é tratar pagamento como uma função do sistema, em vez de um serviço crítico. Uma função você testa no sandbox, coloca no ar e esquece. Um serviço crítico precisa de acompanhamento, comparação diária e um plano para falhas.
Essa diferença separa um sistema que funciona há seis meses de outro que quebra no primeiro feriado.
Se você está planejando integrar pagamentos ao seu sistema, me conte o contexto.