Idempotência

Idempotência é poder repetir a mesma chamada sem que ela aconteça duas vezes.

O problema que ela resolve: você manda criar uma cobrança e a resposta não chega (a internet caiu, deu tempo esgotado). A cobrança foi criada ou não? Sem saber, repetir a chamada pode cobrar o cliente em dobro; não repetir pode deixar o pedido sem cobrança.

Com a chave de idempotência você repete sem medo: se a primeira chamada já tinha dado certo, a API devolve a mesma resposta e não cria nada novo.

Como usar

Mande o cabeçalho Idempotency-Key com um texto que identifica aquela operação:

POST /v2/payment-intents
Authorization: Bearer swp_test_…
Idempotency-Key: pedido-8842-criar

Se precisar repetir a chamada, mande a mesma chave e o mesmo corpo.

Texto livre, até 255 caracteres.
A API lembra da chave por 24 horas.
Cada chave vale dentro da sua chave de API: não há risco de bater com a de outra empresa.

Onde é obrigatória

Chamada	`Idempotency-Key`
Criar intenção de pagamento (`POST /v2/payment-intents`)	Obrigatória
Confirmar intenção (`POST /v2/payment-intents/{id}/confirm`)	Obrigatória
Os outros `POST`	Opcional, mas recomendada

São obrigatórias as chamadas que criam ou movimentam dinheiro.

Escolhendo a chave

A regra é: uma chave por operação, a mesma chave em toda repetição dessa operação.

Bom: o id do pedido no seu sistema mais a etapa. Ex.: pedido-8842-criar e pedido-8842-confirmar.
Bom: um código aleatório (UUID) gerado uma vez e guardado junto do pedido, antes da primeira tentativa.
Ruim: gerar um código novo a cada tentativa. Aí cada repetição é uma operação nova, e a proteção não existe.
Ruim: usar a mesma chave pra criar e pra confirmar. São duas operações: use duas chaves.

O que a API responde

Situação	Resposta
Mesma chave, mesmo corpo, a primeira já terminou	A mesma resposta da primeira (mesmo status, mesmo corpo). Nada novo é criado.
Mesma chave, corpo diferente	`409 IDEMPOTENCY_KEY_REUSED`
Mesma chave, a primeira ainda está processando	`409 IDEMPOTENCY_IN_PROGRESS` — espere 1 segundo e repita
Cabeçalho faltando numa rota que exige	`400 VALIDATION_ERROR` com `details[0].field = "Idempotency-Key"`

A resposta repetida vale também pra erro: se a primeira chamada foi recusada por dado inválido, repetir com a mesma chave devolve a mesma recusa. Corrigiu o pedido? Use uma chave nova.

Quando repetir

Sem resposta (queda de rede, tempo esgotado): repita com a mesma chave.
Erro 5xx: repita com a mesma chave, com um intervalo entre as tentativas.
409 IDEMPOTENCY_IN_PROGRESS: a primeira ainda não terminou. Espere 1 segundo e repita.
Erro 4xx (dado inválido, sem permissão): repetir não adianta. Corrija e mande com outra chave.

Não confunda com `referenceId`

Idempotency-Key protege uma chamada contra repetição, e a API esquece dela depois de 24 horas. referenceId é o seu identificador da venda: fica gravado na transação e serve pra você achá-la depois. Use os dois.