24/05/2026 · Equipe GálagoTEF
Idempotência em pagamentos: por que ela evita venda duplicada
Se existe um conceito que separa uma integração de pagamento profissional de uma amadora, é a idempotência. Ela é o que garante que, mesmo quando a rede falha e seu sistema reenvia a mesma cobrança, o cliente seja cobrado uma única vez. Este artigo explica o que é idempotência, por que ela é indispensável em pagamentos e como implementá-la.
O problema: a rede não é confiável
Imagine este cenário: seu PDV envia uma cobrança de R$ 200, a maquininha processa e aprova, mas a resposta se perde na volta por um timeout de rede. Seu sistema não sabe se deu certo. O que ele faz? Se reenviar a cobrança, o cliente pode ser cobrado duas vezes. Se não reenviar, você pode perder uma venda que foi aprovada. Esse é o problema clássico que a idempotência resolve.
O que é idempotência
Uma operação é idempotente quando executá-la várias vezes produz o mesmo resultado que executá-la uma vez. Em pagamentos, isso significa: enviar a mesma cobrança dez vezes deve resultar em uma transação, não dez. A técnica padrão é a chave de idempotência (idempotency key): um identificador único que seu sistema gera para cada cobrança e envia junto com a requisição.
O funcionamento é direto:
- Na primeira vez que a plataforma vê aquela chave, ela processa a transação e guarda o resultado.
- Nas próximas vezes que a mesma chave chegar, ela não processa de novo; apenas devolve o resultado já registrado.
Assim, reenvios por timeout retornam a mesma resposta em vez de criar uma nova venda.
Como gerar uma boa chave de idempotência
A chave precisa ser única para cada cobrança lógica, mas estável para os reenvios da mesma cobrança. Boas práticas:
- Gere a chave antes de enviar a requisição, e reutilize-a em todos os retries daquela cobrança.
- Use um identificador que já represente a venda no seu sistema (por exemplo, o ID do pedido combinado com a tentativa), ou um UUID guardado junto ao pedido.
- Não gere uma chave nova a cada tentativa: isso derrota todo o propósito.
- Associe a chave à empresa (tenant) para evitar colisão entre clientes diferentes.
Idempotência não é só na cobrança
O mesmo raciocínio vale para outras operações sensíveis:
- Estorno e cancelamento: reenviar um estorno não pode devolver o dinheiro duas vezes.
- Consumo de webhook: a mesma notificação pode chegar mais de uma vez; seu handler precisa ignorar duplicatas usando o ID do evento. Falamos disso em webhooks de pagamento: como usar para confirmar vendas.
Ou seja, idempotência é uma disciplina que atravessa toda a integração, do envio da cobrança ao processamento das notificações.
Onde isso costuma dar errado
Os erros mais comuns em integrações reais são:
- Gerar chave nova a cada retry, transformando reenvio em venda duplicada.
- Tratar timeout como falha e refazer a cobrança sem chave.
- Confiar que “a rede não vai falhar” (ela vai).
- Não persistir o resultado da chave, então o segundo request reprocessa.
Esses problemas aparecem justamente nos momentos de pico, quando a rede está mais instável e o volume é maior, ou seja, no pior momento possível.
Por que isso importa mais em TEF
Em pagamento, uma cobrança duplicada não é um bug qualquer: é dinheiro do cliente saindo indevidamente, reclamação, estorno e desgaste de reputação. Por isso, em um hub de TEF, a idempotência deve ser requisito de dia um, não algo para o backlog. Ela anda de mãos dadas com o isolamento por empresa: cada tenant tem seu espaço de chaves, sem risco de uma empresa colidir com a chave de outra. Antes de escolher uma plataforma, verifique esse ponto no nosso guia de o que avaliar em uma API de pagamento.
Resumo
| Situação | Sem idempotência | Com idempotência |
|---|---|---|
| Timeout e reenvio | Risco de dupla cobrança | Mesma resposta, uma venda |
| Webhook repetido | Pedido liberado 2x | Duplicata ignorada |
| Estorno reenviado | Devolução dobrada | Estorno único |
Integre com tranquilidade
Idempotência é o cinto de segurança da sua integração de pagamento: você espera nunca precisar, mas é ela que evita o acidente no dia em que a rede falha. Implementá-la desde o começo custa pouco; corrigir uma dupla cobrança em produção custa muito.
O GálagoTEF trata cada transação com chave de idempotência por empresa, garantindo que reenvios não gerem venda duplicada. Veja como enviar a chave na documentação da API e comece sua integração com segurança em app.galagotef.com.br.