Checklist antes de contratar uma integração de pagamento (Pix, cartão, boleto)
O que quebra em produção quando a integração de pagamento é tratada como projeto de uma semana: webhooks sem verificação, falta de idempotência e reconciliação ignorada.
Integrar pagamento parece simples na documentação do gateway: um POST, um retorno, um webhook. A complexidade não está na chamada que funciona. Está nos cenários que quebram às três da manhã.
Esta é a lista do que eu verifico antes de colocar qualquer integração em produção, depois de construir sistemas de pagamento que processam Pix, cartão e boleto para negócios reais.
1. Webhook com HMAC, não com URL secreta
Webhook sem verificação criptográfica aceita POST de qualquer origem. Se o payload chega e o sistema processa sem validar assinatura, um atacante pode forjar notificação de pagamento aprovado.
O mínimo é HMAC-SHA256: o gateway assina o payload com uma chave secreta que só você e ele conhecem, e o seu endpoint valida a assinatura antes de processar. URL secreta não é segurança — é obscuridade que dura até o primeiro scan automatizado.
No e-commerce de consultas veiculares que construí, toda notificação de pagamento passava por validação HMAC antes de atualizar o status do pedido. Sem isso, o sistema confia no que chega — e confiança não é mecanismo de segurança.
2. Idempotência no recebimento
O gateway pode enviar o mesmo webhook mais de uma vez. Rede oscilou, timeout, retry. Se o seu endpoint processa duas vezes, você entrega o produto duas vezes ou cobra duas vezes.
A regra é simples: cada notificação carrega um identificador único (id da transação ou idempotency key). Se o identificador já foi processado, o endpoint responde 200 e não mexe em nada. Isso protege contra duplicidade sem depender do gateway ser perfeito.
3. Reconciliação diária
Webhook é assíncrono. E assíncrono falha. O webhook pode não chegar. Pode chegar atrasado. O gateway pode ter caído na hora exata.
Reconciliação é a rotina diária que compara o que o gateway diz que recebeu com o que o seu sistema diz que processou. Sem ela, você descobre pagamento não contabilizado quando o cliente reclama — e cliente que reclama de dinheiro some, não reclama de novo.
4. Sandbox não é produção
O ambiente de sandbox do gateway tem latência diferente, comportamento de timeout diferente, e muitas vezes retorna status que nunca acontecem em produção (ou vice-versa). Testar só no sandbox é testar um sistema diferente.
O que faço: homologo no sandbox, mas testo os cenários de falha em produção com valor mínimo (R$ 0,01 ou equivalente), em horário controlado, com monitoramento ativo. Se o gateway tem endpoint de health check, monitoro antes e durante.
5. LGPD nos dados de cartão
Você não armazena número de cartão. Ponto. Se o gateway oferece tokenização, você armazena o token, nunca o PAN. Se o gateway não oferece tokenização, você troca de gateway.
Dados de pagamento trazem responsabilidade proporcional ao dano. Um vazamento de e-mail é grave. Um vazamento de dados de cartão é existencial para uma pequena empresa. A multa da LGPD é proporcional ao faturamento, mas o dano reputacional não tem teto.
6. Quem responde às três da manhã
Pagamento não tem horário comercial. Se o Pix parou de processar sábado às 22h, o prejuízo acumula até segunda de manhã — se alguém perceber.
Antes de contratar a integração, defina: quem é acionado, por qual canal, com qual procedimento. Se a resposta for "o desenvolvedor que construiu", esse desenvolvedor precisa estar de plantão ou o sistema precisa ter degradação controlada (exibir mensagem, enfileirar, notificar o time na manhã seguinte).
Onde isso quebra
O erro mais comum é tratar pagamento como feature, não como serviço crítico. Feature você testa no sandbox, sobe e esquece. Serviço crítico você monitora, reconcilia e tem plano de contingência. A diferença de postura é a diferença entre um sistema que funciona há seis meses e um que quebrou no primeiro feriado.
Se você está planejando integrar pagamento no seu sistema, me conte o contexto.