Guias

Idempotência

Redes falham. A Idempotency-Key garante que repetir uma chamada de criação nunca gere uma segunda cobrança.

Envie o cabeçalho Idempotency-Key em POST /v1/charges com um valor único por tentativa de venda, como o id do pedido somado ao número da tentativa:

HTTP

Idempotency-Key: pedido-1234-tentativa-1

Como funciona

Primeira chamada: cria a cobrança e responde 201.
Mesma chave e mesmos dados: responde 200 com a cobrança original, no estado atual. Nada novo é criado.
Mesma chave com dados diferentes (terminal, valor, método ou referência): responde 409 idempotency_conflict com o charge_id original em details.
As chaves valem por conta e não expiram.

Quando gerar uma chave nova

Gere uma chave nova sempre que for uma nova tentativa de cobrar, por exemplo depois de uma cobrança recusada ou expirada. Reaproveite a chave só para repetir a mesma chamada que pode não ter chegado (timeout, erro 5xx, queda de conexão).

external_reference não é chave de idempotência

Você pode criar várias cobranças com o mesmo external_reference, o que é útil quando o cliente tenta outro cartão no mesmo pedido. Quem impede duplicidade é a Idempotency-Key.

Anterior← Webhooks PróximoApp da maquininha →