Idempotence
Une requête peut se perdre en route : vous ne savez pas si le paiement a été créé, et la renvoyer risquerait d’en créer un second. L’en-tête Idempotency-Key règle ce problème : la même clé donne toujours le même résultat, une seule fois.
curl https://moncashapi.fedtopup.com/api/v1/payments \
-H "Authorization: Bearer $MONCASHAPI_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: commande-1042" \
-d '{"amount": 1000, "reference": "CMD-1042"}'Règles
| Champ | Type | Description |
|---|---|---|
Même clé, même contenu | rejeu | Vous recevez la réponse d’origine, avec l’en-tête Idempotent-Replayed: true. Rien n’est créé en double. |
Même clé, contenu différent | 409 | IDEMPOTENCY_CONFLICT : une clé ne sert qu’à une requête. |
Même clé, en même temps | 409 | REQUEST_IN_PROGRESS : la première requête n’a pas fini. Réessayez un instant plus tard. |
Requête refusée | — | Une requête refusée (validation, solde) ne consomme pas la clé : corrigez et renvoyez avec la même clé. |
Où elle s’applique
POST /v1/withdrawals: obligatoire. Sans elle :400 IDEMPOTENCY_KEY_REQUIRED.POST /v1/payments,POST /v1/projects,POST /v1/webhooks: recommandée.- Les lectures (
GET) n’en ont pas besoin.
Choisir une clé
Une chaîne de 200 caractères au plus, unique par opération : votre numéro de commande, ou un UUID que vous gardez avec la demande. Les clés sont conservées au moins 24 heures.
Pour les paiements, le champ reference offre une seconde protection : la même référence avec le même montant rend le paiement déjà en attente.