Retrait

Un retrait (cash-out) transfère les fonds d'un portefeuille virtuel vers une destination externe : un compte mobile money ou un compte bancaire.

Où vont les fonds

La destination n'est pas transmise dans la requête de retrait : elle est enregistrée sur le portefeuille virtuel, dans sa configuration cash_out. Vous la définissez à la création du portefeuille et la modifiez via la mise à jour du portefeuille.

Deux canaux sont pris en charge :

• mobile_money — Airtel Money, Orange Money, MVola. Requiert un nom et un numéro de téléphone. Si le moyen exact n'est pas précisé, il est déduit du préfixe du numéro.
• bank_transfer — virement bancaire. Requiert un RIB.

Changer de destination

Pour retirer vers un autre compte, mettez d'abord à jour la configuration cash_out du portefeuille, puis lancez le retrait.

Conditions

Un retrait aboutit si :

1. Le solde disponible couvre le montant et les frais. Le disponible correspond au solde du portefeuille diminué des sorties déjà en attente, puis des frais applicables (frais de plateforme + frais du canal de retrait).
2. Aucun retrait n'est déjà en cours sur ce portefeuille. Tant qu'une sortie de fonds est en pending, une nouvelle demande est refusée avec le message « Une transaction de retrait est déjà en cours. Veuillez attendre sa finalisation avant d'en initier une nouvelle. »
3. Le portefeuille possède une configuration cash_out. Sans elle, la demande est rejetée en 422 sur le champ detail_method.

Il n'y a pas de limite au nombre de retraits par jour : la seule limite est celle du retrait en cours et du solde disponible.

Retraits partiels

Vous pouvez retirer une partie du solde autant de fois que nécessaire, en enchaînant les demandes une fois la précédente finalisée. Si vous omettez le champ amount, l'API calcule et retire le maximum possible, frais déduits.

Frais

Deux frais s'additionnent et sont prélevés en plus du montant retiré :

• les frais de plateforme, selon votre grille tarifaire ;
• les frais du canal choisi (mobile money ou virement bancaire).

Vous pouvez les simuler avant de lancer le retrait avec POST /transaction/calc-fee (voir API - Transaction).

Cycle de vie

1. Vous créez la demande : le retrait et sa transaction money-out sont créés en pending, et le montant est immédiatement réservé sur le solde disponible.
2. Le versement est traité vers la destination configurée.
3. Le statut passe à success ou à error, et l'évènement cash-out.create puis les évènements de transaction correspondants sont émis vers votre webhook.

Points d'attention

• Traçabilité : chaque retrait génère une transaction de type money-out visible dans l'historique.
• Asynchrone : la réponse 201 signifie « demande enregistrée », pas « fonds versés ». Attendez la confirmation.
• Solde réservé : dès la création, le montant et les frais sont décomptés du disponible, avant même le versement effectif.