Skip to main content
Après un timeout, vous ne savez pas si Mercy Pay a traité votre requête. La renvoyer telle quelle pourrait créer un doublon (deux paiements, deux retraits). Avec un en-tête Idempotency-Key unique par opération, une même clé ne crée jamais deux fois.

Une clé par opération, jamais par tentative

La clé identifie l’opération (cette commande, ce retrait), pas la requête HTTP. Générez-la une seule fois, au moment où vous décidez de créer le retrait (ou la charge, ou la session), par exemple à partir de l’identifiant de commande déjà présent dans votre propre système. Si l’appel échoue ou time-out, vous renvoyez la requête à l’identique, avec la même clé, autant de fois que nécessaire : vous ne générez jamais une nouvelle clé pour « réessayer ».
Dans les deux cas, votre code peut traiter la réponse exactement de la même façon : il n’a pas besoin de savoir si c’était le premier essai ou une relance.
Générer une clé différente à chaque tentative (par exemple un uuid() appelé au moment de l’envoi plutôt que mémorisé avec la commande) annule complètement la protection : chaque relance est alors vue comme une opération différente, et un double paiement redevient possible.

Comportement

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 retrait, 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 toutes les créations : sessions de checkout, charges directes, retraits, liens de paiement, plans et abonnements. Il est obligatoire pour une charge directe (POST /api/v1/payments) et pour un retrait (POST /api/v1/payouts) : la requête est rejetée sans lui. Pour les autres, il reste recommandé mais optionnel.