Idempotência
Evite cobranças duplicadas e trate respostas incertas.
Idempotency-Key
POST /v1/payment-intents exige Idempotency-Key de 16 a 128 caracteres seguros: letras, números, ponto, sublinhado ou hífen. A mesma chave com a mesma requisição reproduz a resposta anterior e envia idempotent-replayed: true.
A mesma chave com outro corpo ou outra rota retorna 409 idempotency_conflict; uma chamada ainda em processamento pode retornar 409 request_in_progress. A rota de devolução também exige Idempotency-Key, com validação inicial de 8 a 100 caracteres.
Timeout e reconciliação
Se perder a resposta, repita com a mesma chave e o mesmo corpo. Guarde o UUID da cobrança quando disponível e consulte o estado. Processe webhooks pelo id do evento para evitar entrega ou devolução duplicada.