Idempotência

Redes falham. Para que novas tentativas sejam seguras, envie um cabeçalho Idempotency-Key em toda requisição que cria algo (intenções de pagamento, sessões de checkout, faturas, links de pagamento, carteiras, endpoints de webhook).

POST /v1/payment-intents HTTP/1.1
Authorization: Bearer gp_live_YOUR_KEY
Idempotency-Key: order-123
Content-Type: application/json

Semântica

A primeira requisição com uma chave é processada normalmente e a resposta é armazenada.
Uma repetição com a mesma chave e os mesmos parâmetros retorna a resposta armazenada — nenhum segundo objeto é criado.
Uma repetição com a mesma chave, mas parâmetros diferentes, é recusada com idempotency_error. Use uma nova chave para uma operação diferente.
Enquanto a primeira requisição ainda está em andamento, uma duplicata simultânea aguarda brevemente e depois recebe a resposta armazenada ou um conflito pedindo que você tente de novo.
As chaves são limitadas à sua organização e ao seu ambiente e podem ter até 255 caracteres.

As intenções de pagamento também exigem, no banco de dados, uma chave única por organização e ambiente, de modo que, mesmo com muitas novas tentativas em paralelo, apenas uma intenção é criada.

Como escolher as chaves

Derive a chave do seu próprio identificador de negócio para que as novas tentativas — de qualquer processo — caiam sobre o mesmo objeto:

await gp.paymentIntents.create(params, { idempotencyKey: `order-${order.id}` });

params.IdempotencyKey = "order-" + order.ID
intent, err := client.PaymentIntents.Create(ctx, params)

gp.payment_intents.create(**params, idempotency_key=f"order-{order.id}")

Os SDKs oficiais geram uma chave aleatória nas chamadas de criação quando você não informa uma e a reutilizam nas próprias novas tentativas automáticas.