Payouts - Mercy Pay

Les payouts sont réservés aux clés live, et seulement après approbation du KYC, voir Demander un 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 `+`

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`

{
  "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
`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/

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