> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercy-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotence

> Rejouez une création sans créer de doublon, grâce à l'en-tête Idempotency-Key.

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.

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.