API Payout

L'API Payout envoie des fonds vers un portefeuille Mobile Money en Afrique de l'Ouest. Le bénéficiaire est identifié par une destination vérifiée (destination_id) ou par corridor + numéro (country, operator, phone).

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

Testez sans code : Playground Payout. SDK Node (optionnel) : @fluxx/payout.

Montants : amount: 100 = 100 FCFA (unité de la devise, sans conversion).

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
Montants
Description
amount dans l’unité de la devise : 100 = 100 FCFA.
Name
Idempotence
Description
Référence unique + en-tête Idempotency-Key sur les POST.
Name
Asynchrone
Description
Statut via GET ou webhooks payout.*.

OpenAPI & outils


OpenAPI CDN	v2/payout/openapi.json
OpenAPI live	`GET /api/v1/payout/openapi.json`
Playground	/lab/payout
SDK Node (optionnel)	@fluxx/payout

Authentification

Identique à Collect : Authorization: Bearer <clé_api> ou X-API-Key.

Démarrage rapide

Name
1. Catalogue
Description
GET /payout/operators/
Name
2. Destinations
Description
GET /payout/destinations/ (ou CRUD /api/v1/payout-destinations/)
Name
3. Décaissement
Description
POST /payout/mobile-money/ avec destination_id ou country + operator + phone.
Name
4. Statut
Description
GET /payout/mobile-money/{reference}/. Option ?sync=true.

GET/api/v1/payout/operators/

Catalogue opérateurs

Catalogue

GET

/api/v1/payout/operators/

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

GET/api/v1/payout/destinations/

Destinations

Liste les destinations Mobile Money actives du marchand. En live, le numéro doit correspondre à une destination vérifiée. En test, une destination peut être provisionnée automatiquement si phone est fourni.

cURL

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

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

Initier un décaissement

Name
amount
Type
integer
Description
Montant dans l’unité de la devise (minimum BJ 50 FCFA, CI/TG 100 FCFA).
Name
reference
Type
string
Description
Identifiant unique de l'ordre côté marchand.
Name
destination_id
Type
uuid
Description
Destination pré-enregistrée (prioritaire si fournie).
Name
country
Type
string
Description
BJ, TG, CI. Requis si destination_id est absent.
Name
operator
Type
string
Description
Slug (ex. mtn). Requis si destination_id est absent.
Name
phone
Type
string
Description
Numéro bénéficiaire. Recommandé avec country/operator.
Name
recipient_first_name
Type
string
Description
Prénom (optionnel).
Name
recipient_last_name
Type
string
Description
Nom (optionnel).

Requête

POST

/api/v1/payout/mobile-money/

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

Réponse

201

{
  "id": "42",
  "reference": "WDR-123",
  "status": "PENDING",
  "amount": 100,
  "currency": "XOF",
  "country": "BJ",
  "operator": "mtn",
  "phone": "2290166000000",
  "destination_id": "550e8400-e29b-41d4-a716-446655440000",
  "psp_reference": "TX-abc123",
  "message": "Accepted",
  "environment": "live",
  "idempotent_replay": false
}

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

Statut d'un décaissement

cURL

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

Préférez les webhooks pour le résultat final ; sync=true sert au rattrapage.

Montants

amount est dans l’unité de la devise : 100 = 100 FCFA.

Minimums XOF : BJ 50, CI/TG 100.

États

PENDING → COMPLETED | FAILED | CANCELLED

Webhooks

payout.initiated
payout.completed
payout.failed
payout.cancelled
payout.updated

Voir Webhooks.

Erreurs

Code	HTTP	Signification
`invalid_phone`	400	Numéro invalide
`invalid_operator`	400	Corridor non supporté
`invalid_destination`	400	destination_id inconnu
`destination_not_found_for_phone`	400	Pas de destination pour ce numéro (live)
`destination_not_verified`	400	Destination non vérifiée
`missing_default_destination`	400	Pas de défaut pour le corridor
`amount_too_low`	400	Sous le minimum corridor
`insufficient_balance`	400	Solde insuffisant
`compliance_blocked`	400	Capacités conformité LIVE
`missing_idempotency_key`	400	Header manquant (si exigé)
`payout_failed`	500	Erreur serveur

Bonnes pratiques

Enregistrez et vérifiez les destinations avant le live.
Toujours envoyer Idempotency-Key.
Traitez les webhooks comme source de vérité.
Utilisez le mode test + playground avant la production.