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

# Payouts

> Demandez un versement vers un compte mobile money et suivez son statut.

Les payouts sont réservés aux clés **live**, et seulement après approbation du KYC, voir [Demander un payout](/guides/request-a-payout) pour le flux complet.

## POST /api/v1/payouts

Crée une demande de payout. Elle n'est pas exécutée immédiatement : elle passe d'abord par une approbation avant d'être transmise à l'opérateur.

### Corps

| Champ | Requis | Description |
| - | - | - |
| `amount` | oui | Entier en unités mineures, au moins `1` |
| `currency` | oui | Devise du solde source, ISO 4217 |
| `destination.type` | oui | `mobile_money` |
| `destination.country` | oui | Pays ISO 3166-1 alpha-3, par exemple `CMR` |
| `destination.provider` | oui | Code opérateur, par exemple `MTN_MOMO_CMR` |
| `destination.phone` | oui | Numéro avec indicatif, sans `+` |

```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"
    }
  }'
```

### Réponse `201`

```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"
  }
}
```

| Champ de réponse | Description |
| - | - |
| `amount` | Montant demandé, débité en totalité de votre solde |
| `fee_amount` | Commission Mercy Pay retenue (2 % de `amount`), voir [Payouts](/concepts/payouts) |
| `net_amount` | Montant réellement envoyé au bénéficiaire (`amount` moins `fee_amount`) |

## GET /api/v1/payouts

Liste vos payouts, du plus récent au plus ancien.

| Paramètre | Description |
| - | - |
| `status` | `requested`, `approved`, `processing`, `paid`, `failed`, `rejected` |
| `currency` | Code ISO 4217 |
| `from`, `to` | Dates `AAAA-MM-JJ`, bornes incluses |
| `per_page` | 20 par défaut, 100 au maximum |

## GET /api/v1/payouts/{uuid}

Renvoie un payout, avec exactement la même structure que la réponse de création, pratique pour réutiliser le même code de lecture des deux côtés.

### Erreurs

| Code | Message |
| - | - |
| `422` | `Les payouts ne sont pas disponibles en environnement sandbox.`, avec `errors.environment` : `Utilisez une clé API live (mp_live_*) pour demander un payout.` |
| `422` | `Solde disponible insuffisant pour ce montant.` ou `Opérateur Mobile Money invalide pour ce pays.` |
| `404` | Payout inconnu, ou appartenant à un autre marchand |


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