Guia para desenvolvedores

Idempotência em APIs de pagamento: como nunca cobrar nem pagar duas vezes

Redes falham e requisições são repetidas. Em pagamento, repetir sem cuidado vira cobrança em dobro ou dinheiro enviado duas vezes. Idempotência é o contrato que garante um só efeito.

Abrir conta Falar com o time

A ideia em uma frase

Uma operação idempotente produz o mesmo resultado se for repetida. Você manda a mesma chamada com a mesma chave, e o sistema devolve o resultado da primeira, sem executar de novo.

Onde aplicar

Criar cobrança
O identificador (txid) do pedido garante uma única cobrança.
Pix de saída
A chave de idempotência garante um único pagamento.
Webhook
O seu servidor guarda o id do evento e ignora repetição.

Boas práticas

Gere a chave antes de chamar a API e guarde-a com o pedido, para repetir exatamente a mesma em caso de erro. Nunca gere uma chave nova ao tentar de novo. Veja Pix de saída e Pix de entrada.

Perguntas frequentes

O que é uma chave de idempotência?

Um identificador único que você manda com a requisição para que repeti-la não gere efeito duplicado.

Por quanto tempo a chave vale?

Consulte a documentação da API para o prazo e o comportamento.

Isso vale para consulta?

Consultas já são seguras para repetir. A chave importa nas operações que movimentam dinheiro.