Payout API

Envoyez des fonds instantanément vers n'importe quel wallet Mobile Money. Idéal pour les salaires, remboursements, et décaissements.

Endpoint Paramètres Réponse Exemples Fallback

Fonds disponibles requis

Un payout débite directement votre wallet EnvoiFacile. Assurez-vous d'avoir un solde suffisant avant d'initier un payout.

Endpoint

POST /api/v1/merchant/payout Scope requis : payout

Paramètres

Champ	Type	Requis	Description
`amount`	integer	Requis	Montant en XOF (min : 100, max : 10 000 000)
`currency`	string	Optionnel	Code ISO 4217 — défaut `XOF`
`method`	string	Requis	Opérateur : `orange` · `mtn` · `moov` · `wave` · `tmoney` · `yas` · `mobile_money`
`country`	string	Requis	Code ISO alpha-2 du pays du bénéficiaire : `CI` · `SN` · `BF` · `TG` · `ML` · `BJ` · `GN`. Détermine les frais applicables.
`phone`	string	Requis	Numéro du bénéficiaire au format E.164, par exemple `+22893752340` pour le Togo. Le format sans `+` est également accepté.
`reference`	string	Requis	Référence unique côté marchand (max 100 chars)
`recipient_name`	string	Optionnel	Nom du bénéficiaire (recommandé)
`description`	string	Optionnel	Motif du virement (max 255 chars)
`otp`	string	Optionnel	Code OTP si le provider de destination l’exige (ex. InTouch). Non requis pour les payouts standard. Accepté aussi via `metadata.otp`.
`metadata`	object	Optionnel	Données libres retournées dans le webhook

Frais par pays

Le champ country détermine les frais de transaction appliqués. Votre clé API peut avoir des taux différents selon le pays. Contactez l'équipe commerciale pour configurer vos taux par pays.

Exemples

Payout Wave CI

bash curl

curl -X POST https://envoifacile.com/api/v1/merchant/payout \
  -H "X-API-KEY: ef_live_xxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: payout_salaire_avril_001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "XOF",
    "method": "wave",
    "country": "CI",
    "phone": "+2250701234567",
    "reference": "payout_salaire_avril_001",
    "recipient_name": "Kouame Jean",
    "description": "Salaire Avril 2024"
  }'

Payout T-Money Togo

bash curl

curl -X POST https://envoifacile.com/api/v1/merchant/payout \
  -H "X-API-KEY: ef_live_xxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: payout_tg_001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "XOF",
    "method": "tmoney",
    "country": "TG",
    "phone": "+22893752340",
    "reference": "payout_tg_001",
    "recipient_name": "Client Togo"
  }'

Provider sélectionné automatiquement

Le marchand indique uniquement le pays et l'opérateur. EnvoiFacile peut utiliser un provider différent pour le pay-in et le payout selon les capacités et la disponibilité. N'envoyez pas de header de forçage provider en production.

json Réponse

{
  "success": true,
  "status": "initiated",
  "transaction_id": "OUT_XYZABC789012_1719100000",
  "provider": "envoifacile",
  "provider_ref": "wth_abc123def456",
  "requires_action": false,
  "action_url": null,
  "message": "Payment initiated successfully."
}

Exemple JavaScript (Node.js)

javascript fetch API

const response = await fetch('https://envoifacile.com/api/v1/merchant/payout', {
  method: 'POST',
  headers: {
    'X-API-KEY': process.env.ENVOIFACILE_API_KEY,
    'Idempotency-Key': `payout_${payoutId}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 50000,
    currency: 'XOF',
    method: 'orange',
    country: 'CI',
    phone: '+2250701234567',
    reference: `payout_${payoutId}`,
    recipient_name: 'Diallo Moussa',
    description: 'Remboursement commande #4521',
  }),
});

const data = await response.json();
console.log(data.transaction_id); // OUT_XYZABC789012_...

Traitement asynchrone

Le statut initiated signifie que le payout est en cours. Le statut final (success ou failed) vous sera notifié via webhook. Un résultat ambigu peut rester en pending ou timeout_review jusqu'à la réconciliation. Conservez le transaction_id.

Fallback provider

En cas d'erreur réseau ou de timeout côté provider, le payout ne tente pas automatiquement un autre provider. Cette règle évite les double-paiements si le provider initial a traité la transaction malgré un timeout sur la réponse HTTP.

Situation	Résultat
Provider retourne explicitement `failed`	Wallet marchand recrédité automatiquement
Provider timeout / exception réseau	Statut conservé en attente ou placé en `timeout_review`. Aucun fallback, remboursement ou second envoi avant réconciliation.

Ne relancez pas un résultat ambigu

Après un timeout ou un statut timeout_review, consultez le statut avec le transaction_id et attendez la réconciliation. Une nouvelle référence pourrait provoquer un double paiement si le premier provider a exécuté le transfert.