Versements

Un versement (payout) envoie de l’argent depuis votre solde available vers un portefeuille mobile money.

curl -s -X POST http://localhost:4000/v1/payouts \
  -H "Authorization: Bearer $XAALIS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-09-25" \
  -d '{"amount":5000,"provider":"wave","recipient":{"phone":"+221770000001","name":"Awa Ndiaye"}}'

Champ	Remarques
amount	entier en XOF
provider	wave ou orange_money (les versements Orange Money ne sont pas encore disponibles en production → 422 unsupported)
recipient.phone	+2217XXXXXXXX
recipient.name	facultatif
client_reference	facultatif, votre identifiant

Comment votre solde évolue

L’argent est réservé avant tout envoi : deux versements ne peuvent donc jamais dépenser les mêmes francs.

Étape	available	pending_payouts
POST /v1/payouts accepté (pending)	− (montant + frais)	+ montant
le prestataire confirme → succeeded	—	− montant
le prestataire refuse → failed	+ (montant + frais)	− montant

Si available ne couvre pas amount + fee, la requête échoue avec 422 insufficient_funds et votre solde ne change pas. La tentative est enregistrée comme un versement status: "failed", failure_reason: "insufficient_funds", et une nouvelle tentative avec la même clé renvoie le même 422. Les frais du versement (fee) figurent sur l’objet (0 par défaut).

Statuts

pending → processing → succeeded | failed. Vous recevez les webhooks payout.succeeded / payout.failed. Interrogez GET /v1/payouts/{id} si vous devez attendre le résultat de façon synchrone. Pour lister : GET /v1/payouts?limit=&starting_after=.

Une Idempotency-Key est obligatoire (400 sans elle) : une requête de versement relancée renvoie le premier versement, jamais un second transfert. La même clé avec un montant, un prestataire ou un bénéficiaire différent renvoie 409.

Si l’API répond 503 temporarily_unavailable, l’issue de la réservation n’est pas encore connue : relancez avec la même clé — vous obtiendrez le versement d’origine ou un refus net, jamais deux versements.