API Payout

L'API Payout permet d'envoyer des fonds vers un portefeuille Mobile Money en Afrique de l'Ouest (Bénin, Togo, Côte d'Ivoire). Vous indiquez le pays, l'opérateur et le numéro du bénéficiaire ; FluxxPay achemine le décaissement vers le réseau choisi.

Base URL : https://api.fluxxpay.com/api/v1/payout/

Vue d'ensemble

Name
Pays
Description
Bénin (BJ), Togo (TG), Côte d'Ivoire (CI).
Name
Opérateurs
Description
MTN, Moov, Celtiis, Togocom, Wave, Orange — voir le catalogue.
Name
Idempotence
Description
Référence unique par opération + en-tête Idempotency-Key sur les POST.
Name
Asynchrone
Description
Décaissement initié puis finalisé par l'opérateur ; statut via GET ou webhooks payout.*.

Authentification

Identique à l'API Collect : en-tête Authorization: Bearer suivi de votre clé API, ou X-API-Key.

Démarrage rapide

Name
1. Catalogue
Description
GET /payout/operators/
Name
2. Décaissement
Description
POST /payout/mobile-money/ avec country, operator, reference, amount, phone.
Name
3. Statut
Description
GET /payout/mobile-money/{reference}/ — option ?sync=true.
Name
4. Webhooks
Description
Événements payout.initiated, payout.completed, payout.failed, etc.

GET/api/v1/payout/operators/

Catalogue opérateurs

Catalogue

GET

/api/v1/payout/operators/

curl -X GET 'https://api.fluxxpay.com/api/v1/payout/operators/' \
  -H 'Authorization: Bearer <votre_clé_api>'

POST/api/v1/payout/mobile-money/

Initier un décaissement

Name
amount
Type
integer
Description
Montant en centimes (minimum 10000 = 100 FCFA pour XOF).
Name
phone
Type
string
Description
Numéro Mobile Money du bénéficiaire.
Name
country
Type
string
Description
BJ, TG, CI.
Name
operator
Type
string
Description
Slug opérateur (ex. mtn, moov).
Name
reference
Type
string
Description
Identifiant unique de l'ordre côté marchand.
Name
recipient_first_name
Type
string
Description
Prénom bénéficiaire (optionnel).
Name
recipient_last_name
Type
string
Description
Nom bénéficiaire (optionnel).

Requête

POST

/api/v1/payout/mobile-money/

curl -X POST 'https://api.fluxxpay.com/api/v1/payout/mobile-money/' \
  -H 'Authorization: Bearer <votre_clé_api>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: payout-WDR-123' \
  -d '{
    "amount": 10000,
    "phone": "2290166000000",
    "country": "BJ",
    "operator": "mtn",
    "reference": "WDR-123",
    "description": "Retrait client"
  }'

Réponse

201

{
  "id": "42",
  "reference": "WDR-123",
  "status": "PENDING",
  "amount": 10000,
  "currency": "XOF",
  "country": "BJ",
  "operator": "mtn",
  "phone": "2290166000000",
  "psp_reference": "TX-abc123",
  "message": "Accepted",
  "idempotent_replay": false
}

GET/api/v1/payout/mobile-money/{reference}/

Statut d'un décaissement

Statut

GET

curl -X GET 'https://api.fluxxpay.com/api/v1/payout/mobile-money/WDR-123/?sync=true' \
  -H 'Authorization: Bearer <votre_clé_api>'

Montants

Tous les montants sont en centimes. Pour le XOF, le minimum est 10000 centimes (100 FCFA).

États

Statut API	Description
`PENDING`	Décaissement accepté, en attente de traitement
`PROCESSING`	Traitement en cours
`COMPLETED`	Fonds envoyés avec succès
`FAILED`	Échec définitif
`CANCELLED`	Annulé ou expiré

Webhooks

Abonnez-vous aux événements :

payout.initiated — décaissement créé (PENDING)
payout.completed — succès
payout.failed — échec
payout.cancelled — annulé
payout.updated — transition intermédiaire

Le corps suit le même schéma que la réponse API, encapsulé dans data avec type et event_version (2025-01).

Erreurs

Code	HTTP	Description
`invalid_operator`	400	Pays ou opérateur non supporté
`invalid_phone`	400	Numéro invalide
`amount_too_low`	400	Montant sous le minimum
`missing_idempotency_key`	400	Header requis (si activé)
`not_found`	404	Référence inconnue
`payout_failed`	500	Erreur serveur

Bonnes pratiques

Utilisez une référence unique par décaissement.
Toujours envoyer Idempotency-Key sur les POST.
Traitez le résultat final via webhooks ; le GET sert au rattrapage (?sync=true).
Vérifiez le solde et les plafonds marchand avant d'initier des décaissements en masse.

Encaissement (Collect)