Idempotence

Pourquoi c'est crucial

Une requête de paiement peut échouer côté réseau alors que le paiement a déjà été traité côté serveur. Si vous re-tentez sans précaution, vous risquez de débiter votre client deux fois. La clé d'idempotence permet à Mobupay de reconnaître une requête déjà traitée et de renvoyer la même réponse — sans créer de doublon.

Comment l'utiliser

Ajoutez le header Idempotency-Key avec un identifiant unique pour cette opération (UUID v4 recommandé) :

curl -X POST https://api.mobupay.nc/api/v1/payments/sessions \
  -H "Authorization: Bearer sk_test_VOTRE_CLE" \
  -H "Idempotency-Key: 7c3f4a8e-2b81-4d9a-b76e-fc1e3f2a4b89" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Si vous renvoyez la même clé pour la même requête dans les 24h, Mobupay retournera la réponse de la première exécution (sans ré-exécuter).

Quelles routes le supportent

• POST /payments/sessions
• POST /payments/direct
• POST /payments/links
• POST /payments/:id/capture
• POST /payments/:id/refund
• POST /customers
• POST /customers/:id/sessions
• POST /payment-methods

Les autres routes (GET, DELETE) sont nativement idempotentes — pas besoin de header.

Bonnes pratiques

• Générer la clé côté client au moment de l'action utilisateur (clic sur "Payer"), pas au moment de chaque retry. Sinon le retry crée une nouvelle clé et perd la protection.
• Stocker la clé en BD avec la transaction métier associée. Permet de la réutiliser sur les retries automatiques.
• Format recommandé : UUID v4 (36 caractères) ou un hash déterministe (ex : SHA256(orderId + userId + timestamp)).
• Durée de validité : 24h. Au-delà, la clé est purgée et réutilisable pour une nouvelle requête.
• Erreurs : si vous envoyez la même clé avec un body différent, vous recevez une erreur 409 IDEMPOTENCY_KEY_CONFLICT.