Idempotence

Réessayez sans risque : une même requête ne s’exécute jamais deux fois.

Une erreur réseau ne dit pas si votre requête est arrivée chez Monerails. Rejouer un paiement à l’aveugle pourrait payer deux fois. Pour l’éviter, envoyez un en-tête Idempotency-Key sur chaque POST :

curl https://api.monerails.com/v1/payouts \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Idempotency-Key: payout-inv-118" \
  -H "Content-Type: application/json" \
  -d '{"amount": 150000, "currency": "XAF", "recipient": {"type": "mobile_money", "name": "Kossi Mensah", "phone": "237660000001", "operator": "MTN"}}'

Fonctionnement#

• La première requête avec une clé s’exécute normalement. Monerails garde son code et sa réponse pendant 24 heures.
• Une requête ultérieure avec la même clé, sur le même point d’accès, avec le même corps (à l’octet près) renvoie la réponse gardée, sans s’exécuter à nouveau, avec l’en-tête Idempotent-Replayed: true. Les erreurs 4xx sont gardées et rejouées elles aussi.
• La même clé avec un autre corps, ou sur un autre point d’accès, échoue avec 422 idempotency_key_reused.
• Si la première requête est encore en cours, une seconde échoue avec 409 idempotency_key_in_use. Patientez un instant et réessayez.
• Une erreur 5xx n’est pas gardée : réessayer avec la même clé exécute à nouveau la requête. Monerails ne répond 5xx que si aucun argent n’est parti. Si un problème survient après l’envoi de l’opération à un partenaire de paiement ou à l’émetteur de cartes, vous recevez à la place 202 avec l’objet (processing ou pending), et ce 202 est gardé : une nouvelle tentative le rejoue et n’envoie jamais l’argent deux fois.
• Une création de point de terminaison rejouée renvoie le point de terminaison sans son secret, présent seulement dans la réponse d’origine.

Les clés sont propres à votre entreprise et à votre mode, 255 caractères au plus. Prenez une valeur liée à l’opération dans votre système (payout-inv-118) ou un UUID que vous enregistrez avec elle. Les requêtes GET et DELETE n’en ont pas besoin.

L’en-tête est facultatif pour l’API, mais envoyez-le sur chaque POST qui déplace de l’argent (encaissements, paiements, reversements, émission et recharge de cartes) : sans lui, une nouvelle tentative après une réponse perdue crée une nouvelle opération.

Si la réponse n’est jamais arrivée#

Donnez à chaque opération un client_reference unique (votre numéro de commande ou de facture) à sa création. Si vous n’avez jamais reçu la réponse, même au-delà des 24 heures de la clé :

1. Retrouvez l’opération par cette référence : GET /v1/payouts?client_reference=inv_118 (ou /v1/collections?client_reference=…).
2. Si elle apparaît, suivez-la avec son id et ses webhooks. Ne la recréez pas.
3. Recréez-la seulement si la liste est vide, avec le même client_reference.

Monerails ne refuse pas une seconde opération avec le même client_reference : la vérification avant une nouvelle soumission vous revient.

Quand réessayer#