> ## 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 retrait

> Versez vos fonds vers un compte mobile money depuis le tableau de bord ou l'API, ou un solde carte vers un compte bancaire depuis le tableau de bord.

Un retrait 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 [Retraits](https://docs.mercy-pay.com/payouts/overview.md) pour le détail de la commission et du cycle de statuts.

## Depuis le tableau de bord

Les retraits se font en **Live**, après la vérification de votre identité. Choisissez **Live** en bas du menu, puis ouvrez **Retraits** et **Demander un retrait**.

**1. Solde**

Le solde à retirer : chaque pays et chaque opérateur a le sien, avec ce qui est disponible.

**2. Montant**

Le **Montant retiré**. Les **Frais** et ce que **Vous recevez** s'affichent tout de suite.

**3. Destination**

Un [compte de retrait](https://docs.mercy-pay.com/payouts/accounts.md) enregistré, ou un nouveau numéro.

**4. Confirmation**

Relisez, puis confirmez. Pour votre sécurité, un code envoyé par e-mail peut vous être demandé.

![Demander un retrait, première étape : le choix du solde](https://docs.mercy-pay.com/images/payouts/create-light.webp)
![Demander un retrait, première étape : le choix du solde](https://docs.mercy-pay.com/images/payouts/create-dark.webp)

**Retraits** liste ensuite chaque retrait avec son état et ce que le bénéficiaire a reçu, filtrable par origine : **Tableau de bord**, **API** ou **Automatiques**.

![La liste des retraits avec leur statut et leur origine](https://docs.mercy-pay.com/images/payouts/index-light.webp)
![La liste des retraits avec leur statut et leur origine](https://docs.mercy-pay.com/images/payouts/index-dark.webp)

Depuis le tableau de bord, un solde carte peut aussi partir vers un compte bancaire. Par l'API, seules les destinations mobile money sont acceptées.

## Par l'API

Les mêmes retraits, depuis votre serveur.

### Prérequis

En live, il vous faut un KYC approuvé et un solde qui couvre le montant. En sandbox, le retrait part tout de suite depuis votre solde de test, sans KYC ni validation : utilisez les numéros de [la page Environnements](https://docs.mercy-pay.com/start/environments.md).

**1. Consultez vos soldes**

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://mercy-pay.com/api/v1/wallets \
  -H "Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX"
```

```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
$ch = curl_init('https://mercy-pay.com/api/v1/wallets');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX',
]);

$response = curl_exec($ch);
curl_close($ch);
```

```js JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://mercy-pay.com/api/v1/wallets', {
  headers: {
    Authorization: 'Bearer mp_live_XXXXXXXXXXXXXXXX',
  },
});

const data = await response.json();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests

response = requests.get(
    'https://mercy-pay.com/api/v1/wallets',
    headers={'Authorization': 'Bearer mp_live_XXXXXXXXXXXXXXXX'},
)

data = response.json()
```

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

**2. Créez le retrait**

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
    }
  }'
```

```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
$ch = curl_init('https://mercy-pay.com/api/v1/payouts');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX',
    'Content-Type: application/json',
    'Idempotency-Key: payout-2026-10-03-001',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'amount' => 4000,
    'currency' => 'XAF',
    'destination' => [
        'type' => 'mobile_money',
        'country' => 'CMR',
        'provider' => 'MTN_MOMO_CMR',
        'phone' => '237680000000',
    ],
]));

$response = curl_exec($ch);
curl_close($ch);
```

```js JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://mercy-pay.com/api/v1/payouts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mp_live_XXXXXXXXXXXXXXXX',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'payout-2026-10-03-001',
  },
  body: JSON.stringify({
    amount: 4000,
    currency: 'XAF',
    destination: {
      type: 'mobile_money',
      country: 'CMR',
      provider: 'MTN_MOMO_CMR',
      phone: '237680000000',
    },
  }),
});

const data = await response.json();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests

response = requests.post(
    'https://mercy-pay.com/api/v1/payouts',
    headers={
        'Authorization': 'Bearer mp_live_XXXXXXXXXXXXXXXX',
        'Idempotency-Key': 'payout-2026-10-03-001',
    },
    json={
        'amount': 4000,
        'currency': 'XAF',
        'destination': {
            'type': 'mobile_money',
            'country': 'CMR',
            'provider': 'MTN_MOMO_CMR',
            'phone': '237680000000',
        },
    },
)

data = response.json()
```

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={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "id": "po_a9d4e6f21b3c4e5d8f702c9b6a1e3d48",
    "object": "payout",
    "livemode": false,
    "created": "2026-10-03T10:12:00+00:00",
    "amount": 4000,
    "fee_amount": 80,
    "net_amount": 3920,
    "currency": "XAF",
    "destination": {
      "type": "mobile_money",
      "country": "CMR",
      "provider": "MTN_MOMO_CMR",
      "phone": "237680000000"
    },
    "status": "requested",
    "failure_code": null,
    "failure_reason": null,
    "metadata": null
  }
}
```

**3. Suivez le statut**

En live, notre équipe valide chaque retrait à la main, y compris ceux de l'API, puis le transmet à l'opérateur. Prévoyez ce délai si vous versez de l'argent à vos propres clients. Inutile d'interroger `GET /api/v1/payouts/{id}` en boucle : le webhook `payout.paid` ou `payout.failed` vous prévient dès que l'un des deux survient.

## Utiliser un compte enregistré

Enregistrez vos numéros dans **Paramètres, Comptes de retrait**, puis envoyez `destination_id` à la place de `destination`. L'API refuse un compte qui n'appartient pas à votre boutique.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "amount": 4000,
  "currency": "XAF",
  "destination_id": "5f1c2a7e-8d34-4b19-a6e2-0c7d9e3b1f42"
}
```

## Retraits automatiques

Sur la page **Soldes**, ouvrez un solde et réglez son retrait automatique :

* **Fréquence :** chaque jour, chaque semaine ou chaque mois.
* **Compte qui reçoit :** un compte enregistré. Un solde mobile money part vers un numéro du même opérateur.
* **Minimum :** en dessous de ce montant, le retrait attend la prochaine échéance.
* **Réserve :** la somme qui reste sur le solde.

À chaque échéance, nous demandons le solde disponible moins la réserve. Rien n'est demandé si un retrait de ce solde est encore en cours. Chaque retrait automatique est validé par notre équipe et porte l'origine `automatic`.

## 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 |
| `Ce compte de retrait est introuvable.` | Le `destination_id` n'existe pas ou appartient à une autre boutique |


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