Skip to navigation

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:

CampoOnde vaiPapel
Idempotency-KeyHeader HTTPIdentifica a tentativa. É por ela que recuperamos o pagamento já registrado e devolvemos o mesmo resultado.
identifierCampo do bodyIdentifica a operação no seu sistema. Ecoamos para o liquidante, e ele o devolve em todos os webhooks.

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.

FluxoDedupe porReenvio com a mesma chave depois de uma falha
PIX out e devolução PIXidentifier + Idempotency-KeyNão executa; devolve a recusa registrada
Transferência internaidentifier + Idempotency-KeyNão executa; devolve a recusa registrada
Pagamento de boletoIdempotency-KeyExecuta de novo se a recusa veio na submissão; recusa que chega depois não executa
TEDidentifierNão executa; devolve o estado da tentativa anterior

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.

{
"paymentId": "pay_9f2c…",
"status": "COMPLETED",
"endToEndId": "E1234567820260803…",
"identifier": "ordem-4471"
}

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:

{
"paymentId": "pay_9f2c…",
"status": "FAILED",
"errorCode": "insufficient_funds",
"errorReason": "PIX não autorizado por falta de saldo na conta"
}

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:

  1. 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.completed ou pix.out.failed). O alias antigo GET /v1/accounts/{accountId}/payments/{identifier} ainda responde, mas está deprecated (sunset em 2026-11-21).
  2. Antes de emitir um pagamento novo, confira o extrato.
  3. Só use uma Idempotency-Key nova 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:

{
"tedId": "ted-ordem-4471",
"status": "FAILED",
"identifier": "ordem-4471",
"note": "TED already exists for this identifier — returning current state (idempotent)"
}

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-Key antes 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 TIMEOUT como 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 com Idempotency-Key e identifier novos. A chave antiga continua devolvendo a mesma recusa. O errorCode diz qual é a causa; a lista completa está em Erros.