Versements

Envoyer des fonds depuis votre solde vers un porte-monnaie mobile ou un compte bancaire.

Créer un versement

POST /v1/payouts

Passez un Idempotency-Key — c'est encore plus important qu'à l'encaissement : un versement rejoué sans idempotence paierait deux fois.

Champ	Requis	Description
asset_id	oui	L'actif, par son identifiant
amount_minor	oui	Chaîne, en unités mineures
country	oui	Pays de l'opération (ISO 3166-1 alpha-2)
platform_id	oui	La plateforme de versement (GET /v1/corridors)
recipient	oui	Le destinataire — voir ci-dessous
platform_account_handle	—	Le sous-compte débité. Vide = le primaire du corridor
rail	—	Force un rail précis
client_ref	—	Votre référence
description	—	Texte libre

Le destinataire est typé

"recipient": {
  "name": "Mouhamadou Sy",
  "identifier_type": "msisdn",
  "identifier": "+221771234567"
}

identifier_type dit quelle sorte d'adresse vous détenez (msisdn, iban, un alias…) et identifier la porte. C'est ce qui permet à une plateforme portant plusieurs rails de résoudre sans que vous ayez à en nommer un.

phone seul reste pleinement accepté et s'interprète comme (msisdn, phone). Fournir les deux formes, ou un type sans valeur, est refusé — jamais deviné.

Le solde d'abord

Un versement se débite sur votre solde disponible :

GET /v1/balances

Les soldes sont rendus par actif et par (plateforme, pays), avec le disponible, l'en attente et le réservé. Le réservé couvre les sorties déjà engagées : il n'est pas dépensable.

Les soldes ne s'additionnent jamais entre actifs. Il n'existe aucune conversion de devise sur cette plateforme, donc un total tous actifs confondus n'aurait pas de sens.

Un versement qui dépasserait le disponible est refusé immédiatement, dans la réponse même : 422 avec le code insufficient_funds. Il n'est jamais mis en attente de fonds — il n'existe aucun découvert.

Demander un retrait de votre solde

POST /v1/payout-requests
GET  /v1/payout-requests
GET  /v1/payout-requests/{id}

C'est une demande, pas un versement. Aucun argent ne bouge et rien n'est réservé : l'opération s'ouvre au statut requested, et une personne la décide dans le tableau de bord. C'est la séparation maker-checker — la clé API demande, un propriétaire du compte décide. Il n'existe délibérément aucune annulation : une demande en attente ne retient rien, donc elle se rejette côté décideur.

Le montant est BRUT : les frais de retrait en sont déduits, ils ne s'y ajoutent pas. Sans grille de frais configurée pour l'actif, la demande est refusée en 409 — un retrait gratuit est une ligne à zéro saisie exprès, jamais une absence.

Suivi

payout.success, payout.failed, payout.cancelled arrivent en webhook ; GET /v1/payouts/{id} donne l'état à la demande.