Idempotência
Idempotência é a garantia de que reenviar a mesma requisição não gera um segundo pagamento. Em sistemas distribuídos a resposta pode se perder mesmo depois de a operação ter sido efetivada — um timeout de rede, um deploy no meio do caminho — e sem idempotência o retry viraria débito duplicado.
Duas chaves controlam esse comportamento:
Ambas são opcionais: quando você não envia, geramos um valor aleatório. Isso é importante e costuma passar batido — uma requisição sem essas chaves é sempre tratada como uma operação nova, e não tem proteção nenhuma contra duplicidade. Se o seu retry precisa ser seguro, envie as duas e repita exatamente os mesmos valores.
Recomendamos UUID v4 na Idempotency-Key e, no identifier, a chave que você já usa internamente para a operação (número do lote, id da ordem de pagamento).
O que cada fluxo usa para deduplicar
A chave que vale muda por fluxo. Reenviar com os mesmos valores é sempre seguro; o que difere é qual campo você precisa manter fixo.
Cenários
Os exemplos usam PIX out e valem igual para a transferência interna. O boleto difere na recusa, como mostra a tabela acima, e a TED tem uma seção própria.
A operação deu certo e você reenvia
Devolvemos 200 com o resultado original — mesmo paymentId, mesmo endToEndId. Nenhum novo débito acontece, e o payload da segunda requisição é ignorado.
A operação falhou de forma definitiva e você reenvia
Este é o caso da conta sem saldo, da chave PIX inválida, da recusa por antifraude e do bloqueio por uma policy sua. A resposta é 422 com o motivo:
Uma falha definitiva significa que o dinheiro não saiu e não vai sair. O desfecho fica registrado na Idempotency-Key: reenviar com a mesma chave devolve a mesma recusa, com o mesmo paymentId, o mesmo errorCode e o completedAt da primeira tentativa, e não executa o pagamento de novo, nem depois de você aportar saldo. A chave não expira, então isso vale para sempre.
Para tentar de novo, resolva a causa e abra uma nova tentativa, com Idempotency-Key nova e identifier novo. A chave nova é segura aqui porque a primeira tentativa já tem desfecho e ele não muda. Na transferência interna o identifier novo é obrigatório: o liquidante não aceita repetir o de uma ordem já registrada e responde 409 identifier_conflict. Se o identifier é o número do pedido no seu sistema, acrescente o número da tentativa (pedido-4471-2).
A operação ainda está em andamento
Enquanto o pagamento não tem desfecho, reenviar com a mesma Idempotency-Key anexa à execução em curso em vez de abrir uma segunda. A resposta é 202 com status: "PENDING". Nunca existem dois pagamentos concorrentes para a mesma chave.
O desfecho ficou indeterminado (TIMEOUT)
Caso mais delicado da API. O liquidante aceitou a submissão mas não confirmou o resultado dentro da janela de espera: o dinheiro pode ter saído. Devolvemos 202 com status: "TIMEOUT" e um warning.
Como na recusa, reenviar com a mesma Idempotency-Key devolve o estado existente e não submete o pagamento de novo. A diferença está na chave nova: depois de uma recusa ela é segura, mas aqui o dinheiro pode ter saído, e pagar de novo sobre um desfecho desconhecido é o cenário clássico de pagamento em duplicidade.
O que fazer:
- Consulte
GET /v1/accounts/{accountId}/pix/payments/lookup?identifier={identifier}&waitForFinalStatus=10— a rota segura a conexão e consulta o liquidante por você, até o status final ou até o prazo, em vez de você repetir a consulta. O webhook continua sendo o caminho autoritativo (pix.out.completedoupix.out.failed). O alias antigoGET /v1/accounts/{accountId}/payments/{identifier}ainda responde, mas está deprecated (sunset em 2026-11-21). - Antes de emitir um pagamento novo, confira o extrato.
- Só use uma
Idempotency-Keynova se tiver confirmado que o valor não saiu.
Você reenvia com uma Idempotency-Key nova
É uma operação nova, e vai gerar um segundo pagamento. Trocar a chave é a forma de dizer “quero pagar de novo, de propósito”, como depois de uma recusa definitiva. Nunca gere uma chave nova dentro de um laço de retry automático.
Com uma ressalva útil: enquanto a primeira tentativa está em andamento ou já foi concluída, trocar a chave mas repetir o mesmo identifier faz o PIX out reconhecer a operação e devolver 202 sem criar um segundo pagamento. Vale como rede de proteção adicional, não como substituto — a garantia forte de não duplicar vem de repetir a mesma Idempotency-Key.
Você reenvia a mesma chave com um payload diferente
Não comparamos payloads: quem manda é a chave. Se já existe pagamento para aquela Idempotency-Key, devolvemos o resultado dele e ignoramos os novos valores — não devolvemos erro de conflito. Portanto, jamais reaproveite uma chave para uma operação diferente, ou você vai receber 200 de um pagamento que não é o que você acabou de pedir.
TED
A TED deduplica só pelo identifier, e nunca reexecuta. Qualquer reenvio com um identifier já usado devolve 200 com o estado atual daquela TED, inclusive quando o estado é de falha:
Para tentar de novo depois de uma TED falhada, envie um identifier novo. Isso é deliberado: a TED tem janela de liquidação longa (até 48h) e o identifier é o que amarra o registro aos webhooks do liquidante.
Expiração
As chaves não expiram. O registro do pagamento é permanente, então uma Idempotency-Key usada meses atrás continua devolvendo o resultado daquela operação. Não reaproveite chaves entre operações diferentes.
Boas práticas
- Gere a
Idempotency-Keyantes da primeira tentativa e persista junto com a ordem de pagamento. Uma chave gerada dentro do retry não protege nada. - Mantenha a mesma chave em todo o backoff exponencial de erros de rede e
5xx. - Envie sempre o
identifier, com o id que a operação já tem no seu sistema. Ele é a chave de rastreio nos webhooks e no suporte. - Trate
TIMEOUTcomo estado próprio, nunca como falha. É o único desfecho em que reemitir pode duplicar dinheiro. - Depois de um
422, resolva a causa e abra uma nova tentativa comIdempotency-Keyeidentifiernovos. A chave antiga continua devolvendo a mesma recusa. OerrorCodediz qual é a causa; a lista completa está em Erros.