Integração

Idempotência

Envie o cabeçalho Idempotency-Key em todo POST. Assim uma requisição repetida nunca cria um segundo pagamento.

Por que usar

A rede falha. Se a resposta de um POST se perder, você não sabe se o pagamento foi criado. Com a Idempotency-Key, você repete a mesma requisição sem medo: a API devolve o resultado da primeira vez e não cria nada novo.

Faça assim

  1. Gere a chave a partir do seu pedido, por exemplo pedido-1234. Ela precisa ter de 8 a 200 caracteres.
  2. Envie a chave no cabeçalho Idempotency-Key de todo POST.
  3. Ao repetir por falha de rede, envie a mesma chave e o mesmo corpo.
  4. Para um pedido novo, use uma chave nova.
Idempotency-Key: pedido-1234

O que a API responde

SituaçãoResposta
Chave novaA API executa e guarda o resultado.
Mesma chave e mesmo corpoA API devolve o resultado guardado. Nada novo é criado.
Mesma chave e corpo diferente422 com o código idempotency_key_reused.
Mesma chave ainda em andamento409 com o código idempotency_in_progress. Espere e repita.
Sem a chave400 com o código idempotency_key_required.

A API guarda a chave por 24 horas. A resposta repetida é a da criação: para ver o status atual, use Buscar um pagamento.