Le réseau ment : une demande peut aboutir sans que sa réponse revienne. Posez un en-tête Idempotency-Key sur vos POST — rejouée, la même clé rend la première réponse au lieu d’encaisser deux fois, avec l’en-tête Idempotent-Replayed: true.

Il devient obligatoire quand l’appel touche un téléphone : lancer une demande (POST /v1/payments/{id}/attempts), ou créer un paiement avec payer. Sans lui, l’appel répond idempotency_key_required : un rejeu sans clé ferait sonner le téléphone deux fois.

curl https://api.payiz.app/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: cmd-42" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000, "currency": "XOF" }'

• Une clé se garde 24 h ; passé ce délai, elle redevient libre.
• La même clé avec un autre corps répond 409 : donnez-en une nouvelle.
• Une demande refusée avant d’avoir rien écrit ne retient pas sa clé : corrigez et rejouez la même.
• Le point de non-retour : une fois le geste écrit, la clé lui appartient. Une panne ensuite ne rend jamais une erreur 5xx : vous recevez l’objet tel qu’il est, et un rejeu vous rend le même — la demande n’est jamais relancée.

Une clé par geste métier, pas par tentative : la référence de la commande fait une bonne clé, un identifiant tiré au hasard à chaque essai n’en fait aucune.