> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# 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:

| Campo             | Onde vai      | Papel                                                                                                           |
| ----------------- | ------------- | --------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | Header HTTP   | Identifica a **tentativa**. É por ela que recuperamos o pagamento já registrado e devolvemos o mesmo resultado. |
| `identifier`      | Campo do body | Identifica 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.

| Fluxo                   | Dedupe por                       | Reenvio com a mesma chave depois de uma falha                                          |
| ----------------------- | -------------------------------- | -------------------------------------------------------------------------------------- |
| PIX out e devolução PIX | `identifier` + `Idempotency-Key` | **Não** executa; devolve a recusa registrada                                           |
| Transferência interna   | `identifier` + `Idempotency-Key` | **Não** executa; devolve a recusa registrada                                           |
| Pagamento de boleto     | `Idempotency-Key`                | Executa de novo se a recusa veio na submissão; recusa que chega depois **não** executa |
| TED                     | `identifier`                     | **Nã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.

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](/baas/guias/referencia/erros).