Demander un payout

Un payout verse des fonds vers un compte mobile money, en débitant le solde du même pays, du même opérateur et de la même devise que le bénéficiaire. Voir Payouts pour le détail de la commission et du cycle de statuts.

Prérequis

Trois choses doivent être vraies avant de demander quoi que ce soit : votre KYC est approuvé, vous utilisez une clé live (les payouts n’existent pas en sandbox), et le solde correspondant couvre le montant.

Consultez vos soldes

curl https://mercy-pay.com/api/v1/wallets \
  -H "Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX"

Repérez le solde channel: mobile_money avec country: "CMR" et provider: "MTN_MOMO_CMR". Sa currency est la devise du payout.

Créez le payout

curl https://mercy-pay.com/api/v1/payouts \
  -H "Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2026-10-03-001" \
  -d '{
    "amount": 4000,
    "currency": "XAF",
    "destination": {
      "type": "mobile_money",
      "country": "CMR",
      "provider": "MTN_MOMO_CMR",
      "phone": "237680000000"
    }
  }'

La réponse (HTTP 201) a le statut requested. amount est ce qui est débité de votre solde ; net_amount, une fois les 2 % de commission retirés, est ce qui part réellement vers le bénéficiaire.

{
  "data": {
    "uuid": "a9d4e6f2-1b3c-4e5d-8f70-2c9b6a1e3d48",
    "amount": 4000,
    "fee_amount": 80,
    "net_amount": 3920,
    "currency": "XAF",
    "destination": {
      "type": "mobile_money",
      "country": "CMR",
      "provider": "MTN_MOMO_CMR",
      "phone": "237680000000"
    },
    "status": "requested",
    "psp_reference": null,
    "failure_reason": null,
    "created_at": "2026-10-03T10:12:00+00:00"
  }
}

Suivez le statut

La demande est approuvée puis transmise à l’opérateur. Inutile d’interroger GET /api/v1/payouts/{uuid} en boucle : le webhook payout.paid ou payout.failed vous prévient dès que l’un des deux survient.

Erreurs fréquentes

Message	Cause
`Solde disponible insuffisant pour ce montant.`	Le solde du pays et de l’opérateur ne couvre pas le montant
`Opérateur Mobile Money invalide pour ce pays.`	Le code opérateur ne correspond pas au pays
`Les payouts ne sont pas disponibles en environnement sandbox.`	Clé sandbox utilisée : utilisez une clé `mp_live_…`

Démarrage

Concepts

Guides

Webhooks

Ressources

Demander un payout

Prérequis

Erreurs fréquentes

​Prérequis

​Erreurs fréquentes

Prérequis

Erreurs fréquentes