CONFIABILIDADE DE API
Idempotência em pagamentos: como evitar cobranças duplicadas
Idempotência é a propriedade que permite repetir uma solicitação sem criar o mesmo efeito financeiro mais de uma vez. Em pagamentos, ela protege contra duplo clique, timeout, repetição automática e concorrência. A chave precisa representar a intenção do negócio, não apenas uma requisição de rede.
Por que duplicidade acontece
O cliente clica novamente, a conexão cai depois do envio, um worker repete a mensagem ou dois processos tratam o mesmo pedido. Sem uma chave consistente, cada repetição pode criar uma cobrança nova.
Como desenhar a chave
Use um identificador estável por operação, como pedido e tipo de ação. Reutilize a chave somente quando o conteúdo representa a mesma intenção. Guarde resposta e parâmetros para detectar conflito.
Idempotência não substitui estado
Mesmo com chave, o sistema precisa saber se a cobrança está pendente, aprovada, cancelada ou estornada. Operações diferentes exigem chaves e regras próprias. Uma nova tentativa legítima deve ser distinguida da repetição técnica.
Cenários de teste
- Duas solicitações simultâneas.
- Timeout após criação.
- Mesmo ID com valor diferente.
- Reprocessamento de fila.
- Evento duplicado.
Se você quer avaliar esse desenho na sua operação, fale com um especialista da Marcha. A recomendação final depende do modelo de negócio, do fluxo financeiro e da análise cadastral e comercial.
Escolha a chave pela intenção
A chave deve representar a operação que não pode repetir, como criar uma cobrança para um pedido. Não reutilize a mesma chave para ações diferentes nem gere outra a cada retry automático. Associe chave, escopo, payload e resultado.
Defina tempo de retenção coerente com a janela de repetição. Se o payload mudar, rejeite ou trate explicitamente em vez de executar silenciosamente.
Concorrência no servidor
Duas requisições podem chegar ao mesmo tempo. Use restrição única ou transação para garantir que apenas uma execute. Marcar em memória depois do processamento deixa uma janela de duplicidade.
Armazene estado em processamento, concluído ou falho recuperável e decida como responder a chamadas concorrentes. Teste queda entre efeito externo e persistência local.
Idempotência depois do pagamento
Também proteja liberação de acesso, emissão, estoque, e-mail e repasse. O webhook pode repetir mesmo que a criação da cobrança tenha sido idempotente. Cada consumidor precisa de sua própria chave de efeito.
Monitore colisões, repetições e operações presas. Ferramentas de reprocessamento devem reutilizar a intenção original e mostrar o que já foi aplicado.
Perguntas frequentes
Chave idempotente pode ser aleatória?
Pode, se for persistida e reutilizada para a mesma intenção. Gerar outra a cada repetição elimina a proteção.
Quanto tempo guardar a chave?
Siga o contrato da API e o ciclo operacional relevante.
Idempotência evita todo pagamento duplicado?
Reduz duplicidade técnica, mas regras de pedido e atendimento também são necessárias.
Webhook também precisa de idempotência?
Sim. Eventos podem ser reenviados e processados mais de uma vez.
Idempotência elimina toda duplicidade?
Ela reduz duplicidade dentro do escopo implementado, mas não corrige chaves mal escolhidas, efeitos fora da transação ou operações manuais paralelas. Modele cada efeito crítico, use restrições persistentes e reconcilie com o provedor. Testes de concorrência e falha são necessários.
A mesma chave pode ser usada para criar cobrança e fazer estorno?
Não. São intenções diferentes e precisam de chaves e escopos distintos. Uma chave deve identificar uma operação específica com payload coerente. Reutilizá-la para ações diferentes pode devolver resultado incorreto ou bloquear uma operação legítima. Documente como cada chave é gerada, por quanto tempo é retida e o que acontece quando o conteúdo da requisição muda.