GG CheckoutHelp Center
Ferramentas avançadasAPI de pagamentos

Idempotência

O header Idempotency-Key faz a API de pagamentos devolver a resposta original quando o mesmo pedido de cobrança é repetido, sem criar outra cobrança.

Idempotência é a propriedade de um pedido que pode ser repetido sem mudar o resultado. Na API de pagamentos, toda criação de cobrança exige o header Idempotency-Key. Quando a rede falha e o seu sistema repete o pedido com a mesma chave, a API devolve a resposta do primeiro pedido e não cria uma segunda cobrança.

Idempotency-Key: pedido-1234

O valor tem de 1 a 255 caracteres ASCII imprimíveis.

Como a API responde

SituaçãoResposta
Mesma chave e mesmo corpoA resposta original, com o mesmo status. Nenhuma cobrança nova é criada, e a resposta traz o header Idempotent-Replayed: true.
Mesma chave e corpo diferenteErro 409 idempotency_key_reused. A comparação é byte a byte, então o corpo reenviado precisa ser idêntico, sem reformatar o JSON. Essa trava continua depois das 24 horas.
Mesma chave com o primeiro pedido ainda em andamentoErro 409 request_in_progress. O pedido pode ser repetido em instantes.

A resposta original fica guardada por 24 horas.

O valor da chave

A chave identifica o pedido no seu sistema, como o número do pedido ou um UUID gerado uma vez por compra. Um valor novo a cada tentativa é tratado como um pedido novo e cria uma cobrança nova.

Quando o pedido é repetido com a mesma chave

A documentação da API indica repetir o pedido com a mesma Idempotency-Key quando a resposta é 500 internal_error ou 502 gateway_unavailable, e quando a conexão cai sem resposta. No 502, a API consulta a cobrança antes de tentar de novo, então a cobrança não é duplicada.

O cancelamento não precisa de Idempotency-Key: cancelar duas vezes tem o mesmo resultado.

A referência do pedido

O campo external_reference também é único na conta. Mesmo com outra Idempotency-Key, a mesma referência não gera uma segunda cobrança enquanto a primeira estiver aberta ou paga, e a API responde 409 external_reference_taken. Quando a primeira cobrança vence, falha ou é cancelada, a referência fica livre de novo.

Páginas relacionadas

On this page