Idempotence - Mercy Pay

Un timeout ne vous dit jamais si la requête a échoué avant ou après traitement par Mercy Pay. Rejouer bêtement risquerait de créer un doublon (deux sessions, deux payouts). Envoyez un en-tête Idempotency-Key unique par opération et ce risque disparaît : une même clé ne crée jamais deux fois.

curl https://mercy-pay.com/api/v1/payouts \
  -H "Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-10-03-001" \
  -d '{"amount": 4000, "currency": "XAF", "destination": {"type": "mobile_money", "country": "CMR", "provider": "MTN_MOMO_CMR", "phone": "237680000000"}}'

Comportement

Situation	Réponse
Première requête	Création, `201`
Même clé, même contenu	Réponse d’origine rejouée, `200`, sans nouvelle création
Même clé, contenu différent	`409` : `Cette clé idempotente a déjà été utilisée avec un payload différent.`

Les clés sont conservées 24 heures. Au-delà, la même clé n’est plus reconnue et recrée une ressource.

Conseils

Générez une clé par opération logique (une commande, un payout, une charge directe), pas une par tentative réseau.
Ne réutilisez jamais une clé pour une autre opération, même après un échec : son rôle est justement d’identifier une seule opération sans ambiguïté.
Idempotency-Key est accepté sur les quatre créations qui comptent : sessions de checkout, charges directes, payouts et liens de paiement.