Virements sortants

L'API encaisse ; elle décaisse aussi. Envoyez de l'argent depuis votre solde vers un compte Orange Money, par API ou depuis le dashboard.

À quoi ça sert

Un virement est l'inverse d'un paiement : vous envoyez de l'argent à quelqu'un. C'est ce qui permet à une place de marché de payer ses vendeurs, à une application de verser des commissions, ou à vous de retirer votre solde vers votre propre compte.

Tout se pilote par API avec votre clé secrète : votre back-office déclenche les virements sans ouvrir le dashboard NguePay. Certains virements passent par une validation de l'équipe NguePay avant de partir ; votre intégration n'a rien de particulier à faire pour ça.

Le solde, d'abord

Un virement est financé par votre solde NguePay, alimenté par les paiements que vous encaissez. Vous ne pouvez pas envoyer ce que vous n'avez pas encore reçu.

curl https://api.live.nguepay.com/api/v1/balance \
  -H "Authorization: Bearer sk_live_VOTRE_CLE"

{
  "success": true,
  "data": {
    "available": 1250000,
    "available_xof": 12500,
    "pending": 400000,
    "pending_xof": 4000,
    "total_xof": 16500,
    "currency": "XOF",
    "updated_at": "2026-09-18T10:14:02.000000Z"
  },
  "message": ""
}

Envoyer un virement

* Deux formes de bénéficiaire, exclusives : soit payout_account_uuid (retrait vers un de vos comptes), soit le trio beneficiary_* (versement à un tiers). Envoyer les deux est refusé — il ne doit jamais y avoir de doute sur qui reçoit l'argent.

curl -X POST https://api.live.nguepay.com/api/v1/payouts \
  -H "Authorization: Bearer sk_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "reference": "vir_vendeur_10452",
    "beneficiary_provider": "orange",
    "beneficiary_number": "+2250700000000",
    "beneficiary_name": "Awa Kone",
    "description": "Commission vendeur septembre"
  }'

La réponse

{
  "success": true,
  "data": {
    "uuid": "5c8e1a70-2b31-4f0c-9d22-77ab3e1f9c44",
    "reference": "vir_vendeur_10452",
    "status": "pending",
    "review": "awaiting_execution",
    "amount": 500000,
    "amount_xof": 5000,
    "currency": "XOF",
    "provider": "orange",
    "beneficiary": {
      "type": "mobile_money",
      "provider": "orange",
      "name": "Awa Kone",
      "number": "orange — ************00",
      "payout_account_uuid": null
    },
    "description": "Commission vendeur septembre",
    "metadata": [],
    "failure_reason": null,
    "awaiting_operator_funds": false,
    "attempts": 0,
    "processed_at": null,
    "created_at": "2026-09-18T10:15:00.000000Z",
    "links": { "self": "/api/v1/payouts/5c8e1a70-2b31-4f0c-9d22-77ab3e1f9c44" }
  },
  "message": "Virement enregistré."
}

Description complète : objet Virement. La même forme est renvoyée par GET /payouts (liste data.payouts), GET /payouts/{uuid} et POST /payouts/{uuid}/cancel.

Idempotence

Une même reference ne peut donner qu'un seul virement. Rejouez l'appel — retry réseau, double clic, worker relancé — et vous récupérez le virement existant avec un 200 au lieu d'un 201. Aucun second virement, aucune seconde provision retenue.

C'est la protection la plus importante de cette API : un paiement créé deux fois se rembourse, un virement envoyé deux fois est parti chez le bénéficiaire.

Rejouer suppose de redemander la même chose. Une reference déjà utilisée avec un autre montant est refusée en 422 avec NGP005 : vous rendre l'ancien virement vous ferait croire que le nouveau est parti.

Validation par l'équipe NguePay

Les virements automatiques sont activés compte par compte, par l'équipe NguePay, après vérification de vos documents (KYC). Tant qu'ils ne sont pas activés, chaque virement est validé par un administrateur NguePay avant de partir, le montant restant réservé sur votre solde pendant ce temps.

Une fois activés, un virement part automatiquement, sauf s'il remplit l'une des conditions ci-dessous : il attend alors la validation de l'équipe NguePay.

Vos plafonds sont fixés par NguePay à l'activation (500 000 XOF par virement et 2 000 000 XOF par jour par défaut) et peuvent être ajustés ; NguePay peut aussi désactiver les virements automatiques à tout moment. Votre état et vos plafonds sont renvoyés dans le champ automatic de GET /payouts/providers et affichés sur la page Virements du dashboard. Les motifs de la validation ne sont pas exposés : vous voyez seulement que le virement est en validation.

Le contrat ne change pas : pendant la validation, status reste pending. Le champ review de l'objet Virement précise l'étape :

Cycle de vie

POST /payouts ─▶ pending · review = awaiting_approval   (validation NguePay, si requise)
                    │      ├─ refusé ─────────────────────▶ failed (rejected_by_review)
                    │      └─ validé
                    ▼
             pending · review = awaiting_execution  (Orange : envoi par l'équipe NguePay)
                    ├─ envoyé ────────────────────────────▶ succeeded
                    └─ échec de l'envoi ──────────────────▶ failed (manual_execution_failed)

Envoi automatique (Wave, MTN — bientôt) : pending · review = null ─▶ processing ─▶ succeeded | failed
Tant qu'il est pending (review compris) : POST /payouts/{uuid}/cancel ─▶ canceled

Après un échec, relancez avec une nouvelle référence : l'ancienne rend le virement échoué.

Quand l'opérateur n'a pas encore les fonds

Pour les opérateurs à envoi automatique (Wave et MTN MoMo, bientôt disponibles), le virement est payé par le compte NguePay chez l'opérateur du bénéficiaire. Votre solde NguePay peut être suffisant alors que ce compte-là est momentanément à court.

Avant chaque envoi automatique, NguePay vérifie donc que ce compte peut payer. S'il ne le peut pas, le virement n'est pas envoyé et ne part pas en échec tout de suite :

• il reste en pending, provision retenue, avec awaiting_operator_funds: true dans l'API et dans les webhooks payout.* ;
• NguePay réessaie toutes les 15 minutes, et l'envoie dès que le compte est approvisionné — awaiting_operator_funds repasse alors à false ;
• après 24 heures sans approvisionnement, il passe en failed avec failure_reason: "operator_float_insufficient", et le montant est rendu à votre solde.

Tant qu'il est en pending (hors envoi par l'équipe NguePay), vous pouvez l'annuler.

Annuler

curl -X POST https://api.live.nguepay.com/api/v1/payouts/{uuid}/cancel \
  -H "Authorization: Bearer sk_live_VOTRE_CLE"

Possible tant que le virement est en pending, y compris pendant la validation NguePay (review: "awaiting_approval") : la provision revient aussitôt à votre solde disponible et payout.canceled est émis. Plus d'annulation une fois review: "awaiting_execution" (l'équipe NguePay peut être en train d'envoyer), ni une fois parti chez l'opérateur — il ne s'annule plus : NguePay ne peut pas rappeler de l'argent déjà parti. L'annulation est alors refusée en 422.

Être notifié

Trois événements partent vers vos destinations webhook : payout.succeeded, payout.failed et payout.canceled. Un virement envoyé par l'équipe NguePay émet lui aussi payout.succeeded ; un refus de validation ou un échec d'envoi émet payout.failed. L'entrée en validation n'émet pas d'événement : la réponse de création porte déjà review.

{
  "event": "payout.succeeded",
  "data": {
    "payout_id": "5c8e1a70-2b31-4f0c-9d22-77ab3e1f9c44",
    "reference": "vir_vendeur_10452",
    "status": "succeeded",
    "review": null,
    "amount": 500000,
    "amount_xof": 5000,
    "currency": "XOF",
    "provider": "orange",
    "beneficiary": "orange — ************00",
    "failure_reason": null,
    "awaiting_operator_funds": false,
    "processed_at": "2026-09-18T14:02:11+00:00"
  }
}

Le webhook reprend les champs du virement sous une forme aplatie : payout_id (= uuid), beneficiary est la chaîne masquée, review y figure aussi (null : ces événements sont émis une fois le virement conclu), et il ne porte ni description, ni metadata, ni attempts, ni created_at. Détail dans la Référence des événements.

Comme pour les paiements, c'est le webhook qui fait foi. La réponse 201 dit seulement que le virement est enregistré et provisionné, pas qu'il est arrivé.

Le grand livre

Chaque mouvement de solde laisse une écriture : paiement encaissé, remboursement, virement, contre-passation d'un virement échoué. C'est ce qui vous permet de justifier votre solde ligne à ligne.

curl "https://api.live.nguepay.com/api/v1/ledger?source_type=payout&per_page=50" \
  -H "Authorization: Bearer sk_live_VOTRE_CLE"

curl "https://api.live.nguepay.com/api/v1/payouts?status=failed" \
  -H "Authorization: Bearer sk_live_VOTRE_CLE"

Le filtre status=pending de GET /payouts inclut les virements en validation NguePay.

Le grand livre est en lecture seule : une écriture ne se corrige pas, elle se contre-passe par une écriture inverse. balance_after est figé à l'écriture, ce qui permet de répondre « quel était mon solde ce jour-là » sans rejouer tout l'historique.

Opérateurs et plafonds

curl https://api.live.nguepay.com/api/v1/payouts/providers \
  -H "Authorization: Bearer sk_live_VOTRE_CLE"

{
  "success": true,
  "data": {
    "providers": ["orange"],
    "automatic": {
      "auto_enabled": true,
      "auto_max_xof": 500000,
      "auto_daily_max_xof": 2000000,
      "enabled_at": "2026-10-15T09:00:00+00:00"
    },
    "limits": { "min_xof": 200, "max_xof": 2000000, "daily_max_xof": 5000000 }
  },
  "message": ""
}

providers liste les opérateurs de bénéficiaire acceptés (valeurs de beneficiary_provider) ; limits donne les bornes par virement et le plafond journalier cumulé, en XOF entiers.

automatic décrit vos virements automatiques : auto_enabled (activés ou non par NguePay après vérification de vos documents), auto_max_xof et auto_daily_max_xof (vos plafonds sans validation, en XOF entiers ; 500 000 et 2 000 000 par défaut) et enabled_at (date d'activation, sinon null). Tant que auto_enabled vaut false, chaque virement est validé par NguePay.

Tous les opérateurs qui encaissent ne décaissent pas, et la liste dépend de la configuration de la plateforme : interrogez-la plutôt que de coder les codes en dur.

L'opérateur du bénéficiaire reste lisible dans beneficiary.provider. Stripe ne verse pas sur un compte Mobile Money ivoirien et n'apparaît pas dans la liste.

Vos comptes de reversement Mobile Money

Pour un retrait vers vos propres comptes (payout_account_uuid), le numéro doit d'abord être vérifié par un code reçu par SMS. Ces comptes se gèrent depuis le dashboard (session de connexion, pas de clé API). Un compte ajouté ou modifié depuis moins de 48 heures fait passer ses virements par la validation NguePay.

Erreurs propres aux virements

Ces refus ont lieu avant toute retenue : un virement refusé ne laisse ni trace exécutable ni provision immobilisée. La validation NguePay, elle, n'est pas une erreur : le virement est créé (201) et attend.

Ce qu'il faut éviter

• Dériver la référence d'un aléatoire ou d'un horodatage — vous perdez l'idempotence, et un retry enverra l'argent deux fois
• Considérer un 201 comme une preuve de réception — attendez payout.succeeded
• Recréer sous une autre référence un virement resté en validation — les deux finiraient par partir ; annulez-le d'abord
• Boucler sur GET /payouts/{uuid} en attendant un changement — les webhooks existent pour ça
• Laisser traîner une clé secrète : le plafond journalier et la validation NguePay limitent les dégâts, ils ne les évitent pas