> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercy-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Demander un payout

> Versez des fonds de votre solde vers un compte mobile money, depuis une clé live.

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](/concepts/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.

<Steps>
  <Step title="Consultez vos soldes">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Créez le payout">
    ```bash theme={null}
    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.

    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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_…` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.