Guides

Retraits

Un retrait envoie de l'argent depuis votre solde MivaaPay vers un compte Mobile Money : le vôtre, ou celui d'un de vos utilisateurs. C'est le mouvement inverse d'un paiement, et il obéit à des règles différentes.

Deux régimes de bénéficiaire

Le régime se déduit de votre requête : sans phone_number, l'argent part vers le moyen de reversement validé de votre compte. Avec, il part vers le numéro que vous indiquez.

Créer un retrait

curl -X POST https://api.mivaapay.com/api/v1/payouts \
  -H "Authorization: Bearer $MIVAAPAY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "operator": "mtn",
    "phone_number": "22997000000",
    "external_id": "WDR-1042",
    "beneficiary_name": "Ada Lovelace",
    "reason": "Retrait joueur"
  }'

$payout = Http::withToken(env('MIVAAPAY_SECRET_KEY'))
    ->post('https://api.mivaapay.com/api/v1/payouts', [
        'amount'       => 5000,
        'operator'     => 'mtn',
        'phone_number' => '22997000000',
        'external_id'  => 'WDR-1042',
    ])
    ->json('data');

const res = await fetch('https://api.mivaapay.com/api/v1/payouts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MIVAAPAY_SECRET_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,
    operator: 'mtn',
    phone_number: '22997000000',
    external_id: 'WDR-1042'
  })
});
const { data } = await res.json();

import os, requests

res = requests.post(
    'https://api.mivaapay.com/api/v1/payouts',
    headers={'Authorization': f"Bearer {os.environ['MIVAAPAY_SECRET_KEY']}"},
    json={
        'amount': 5000,
        'operator': 'mtn',
        'phone_number': '22997000000',
        'external_id': 'WDR-1042',
    },
    timeout=30,
)
data = res.json()['data']

La réponse :

{
  "success": true,
  "data": {
    "reference": "pyo_9f2c7a41e8b3d6c05f1a",
    "status": "pending",
    "amount": 5000,
    "fee_amount": 0,
    "total_debited": 5000,
    "currency": "XOF",
    "operator": "mtn",
    "phone_number": "229970*****",
    "beneficiary_name": "Ada Lovelace",
    "external_id": "WDR-1042",
    "livemode": true,
    "completed_at": null,
    "created_at": "2026-08-09T17:41:02+00:00"
  }
}

Paramètres

Rejouer sans payer deux fois

Un réseau qui coupe après l'envoi ne vous dit pas si le retrait a été créé. Envoyez un external_id et rejouez sans crainte : le second appel renvoie le retrait existant au lieu d'en créer un nouveau.

L'identifiant est unique par compte et par environnement : le même WDR-1042 reste disponible en test et en production.

Suivre un retrait

Un retrait naît pending. Il devient succeeded quand l'opérateur confirme, ou failed s'il refuse — auquel cas votre solde est recrédité automatiquement.

curl https://api.mivaapay.com/api/v1/payouts/pyo_9f2c7a41e8b3d6c05f1a \
  -H "Authorization: Bearer $MIVAAPAY_SECRET_KEY"

GET /payouts liste vos retraits, filtrable par status, from et to.

Être notifié

Deux évènements, signés du secret de l'environnement émetteur comme tous les autres — voir Webhooks.

Plafonds

Les retraits vers un numéro tiers sont bornés. Ces limites protègent votre solde : une clé secrète dérobée ne peut pas le vider d'un coup.

Les valeurs applicables à votre compte sont visibles dans votre tableau de bord. Si votre volume les dépasse régulièrement, demandez leur relèvement : elles se règlent compte par compte.

Erreurs propres aux retraits

Voir Erreurs pour l'enveloppe commune et les codes partagés.

Essayer sans risque

Avec une clé sk_test_…, aucun argent ne bouge et aucun opérateur n'est contacté. L'issue est décidée par les quatre derniers chiffres du numéro du bénéficiaire, exactement comme pour les encaissements — voir Mode test.