MobupayMobupay
Chargement de vos clés API…

Idempotence

Éviter les doubles opérations quand une requête est renvoyée après une erreur réseau.

Pourquoi c'est crucial

Une requête peut échouer côté réseau alors que l'opération a déjà été traitée côté serveur. Si vous la renvoyez sans précaution, vous risquez de débiter ou de rembourser 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 l'en-tête Idempotency-Key avec un identifiant unique pour cette opération (UUID v4 recommandé, 255 caractères au plus) :

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

Si vous renvoyez la même requête avec la même clé, Mobupay retourne la réponse de la première exécution, sans la réexécuter. Les clés de la sandbox et celles de la production sont distinctes.

Quelles routes le supportent

  • POST /payments/:id/refund
  • POST /payments/:id/capture
  • POST /customers
  • POST /customers/:id/sessions
  • POST /customers/:id/card-links
  • POST /payment-methods
  • POST /payouts
  • POST /payments/sessions
  • POST /payments/direct
  • POST /payments/links
  • POST /payments/:id/cancel
  • POST /billing/invoices

Remboursement, capture, client, session de carte, lien de carte, moyen de paiement et virement : la clé vaut 24 heures. Pendant ce délai, un nouvel envoi de la même demande rend la réponse d'origine (même statut, même corps), avec l'en-tête Idempotent-Replayed: true. La même clé employée pour une autre demande (autre paiement, autre montant) est refusée en 409 IDEMPOTENCY_KEY_REUSED, sans rien exécuter.

Issue inconnue : si la première demande a échoué après l'envoi de l'opération à l'acquéreur ou à la banque (remboursement, capture, virement, enregistrement de carte, e-mail d'invitation), l'opération a pu avoir lieu. La clé n'est alors pas libérée : un nouvel envoi sous la même clé est refusé en 409 IDEMPOTENCY_OUTCOME_UNKNOWN, sans rien exécuter, et nos équipes sont prévenues. Une demande qui échoue avant cet envoi libère la clé, et son nouvel envoi s'exécute normalement.

Client (POST /customers) : l'adresse e-mail est unique par marchand. Le nouvel envoi d'une création déjà réussie, sous la même clé et avec le même contenu, rend 201 et la fiche d'origine, et non le 409 CONFLICT de doublon : vous apprenez ainsi que la fiche existe et qu'elle est la vôtre. Avec une nouvelle clé, ou sans clé, une adresse déjà prise reste refusée en 409 CONFLICT.

Session de carte (POST /customers/:id/sessions) : un nouvel envoi rend la même session, même si elle a expiré entre-temps. Pour ouvrir une nouvelle session, utilisez une nouvelle clé.

Lien de carte (POST /customers/:id/card-links) : un nouvel envoi rend le même lien, et l'e-mail demandé par sendByEmail n'est pas envoyé une seconde fois à votre client. Pour lui adresser une nouvelle invitation, utilisez une nouvelle clé.

Virement (POST /payouts) : un nouvel envoi rend le virement d'origine, et aucun second virement n'est émis. Sans clé, deux envois identiques font deux virements : après une réponse perdue, renvoyez toujours la même demande avec la même clé, jamais avec une nouvelle.

Création de paiement (sessions, direct, liens) : la clé reste attachée au paiement créé. Un nouvel envoi rend ce paiement, sans en créer un autre. Utilisez une clé par paiement, et jamais la même pour deux créations différentes.

Annulation : idempotente par nature. Annuler un paiement déjà annulé rend la même réponse.

Facture (POST /billing/invoices) : la clé est conservée aussi longtemps que la facture. Un nouvel envoi rend la facture déjà créée (200), et la même clé avec un contenu différent est refusée en 409 IDEMPOTENCY_KEY_REUSED.

Les lectures (GET) et les suppressions (DELETE) sont idempotentes par nature : aucun en-tête n'est nécessaire.

Après une réponse perdue

  1. Renvoyez la même requête, avec la même clé et le même corps. Si la première avait abouti, vous recevez sa réponse ; sinon, l'opération s'exécute.
  2. Si la réponse est 409 IDEMPOTENCY_REQUEST_IN_PROGRESS, la première requête est encore en cours : renvoyez-la à l'identique quelques secondes plus tard.
  3. Si la réponse est 409 IDEMPOTENCY_OUTCOME_UNKNOWN, l'issue de la première requête est inconnue. Consultez d'abord le paiement (GET /payments/:id) pour un remboursement ou une capture, les moyens de paiement du client pour une carte, ou la liste de vos virements dans votre espace marchand pour un virement. Ne renvoyez la demande, avec une nouvelle clé, que si l'opération n'y figure pas.
  4. Ne générez jamais une nouvelle clé pour la même opération sans avoir d'abord consulté le paiement (GET /payments/:id) : une nouvelle clé est une nouvelle opération.

Bonnes pratiques

  • Générer la clé côté client au moment de l'action utilisateur (clic sur « Payer » ou « Rembourser »), pas à chaque nouvel essai. Sinon le nouvel essai porte une nouvelle clé et perd la protection.
  • Enregistrer la clé en base de données avec l'opération métier associée, pour la réutiliser lors des nouveaux essais automatiques.
  • Format recommandé : UUID v4 (36 caractères) ou une empreinte déterministe de l'opération (ex : SHA256(orderId + refundNumber)), 255 caractères au plus.
  • Durée de validité : 24 heures pour le remboursement et la capture. Au-delà, la clé est réutilisable pour une nouvelle requête.
  • Erreurs : la même clé envoyée pour une demande différente rend 409 IDEMPOTENCY_KEY_REUSED ; une clé dont la première demande a une issue inconnue rend 409 IDEMPOTENCY_OUTCOME_UNKNOWN.