Démarrage Rapide

Ce guide vous permet d'effectuer votre première collecte Mobile Money avec l'API Collect en quelques minutes.

Prérequis

Name
Compte marchand
Description
Compte FluxxPay actif avec accès au dashboard marchand.
Name
Clé API
Description
Clé générée en environnement Test ou Production (Intégrations → Clés API).
Name
Stack technique
Description
Capacité à appeler une API REST (cURL, fetch, axios, etc.).

Étape 1 : Obtenir votre clé API

Ne commitez jamais votre clé API. Utilisez des variables d'environnement.

Connectez-vous au dashboard marchand FluxxPay.
Allez dans Intégrations → Clés API.
Générez une clé (Test pour commencer).
Copiez-la et stockez-la dans FLUXX_API_KEY (ou équivalent).

Les clés utilisent en général un format UUID (ex. 550e8400-e29b-41d4-a716-446655440000).

Étape 2 : Vérifier l'authentification

Testez votre clé en récupérant le catalogue des opérateurs :

Catalogue opérateurs

GET

/api/v1/collect/operators/

curl -X GET 'https://api.fluxxpay.com/api/v1/collect/operators/' \
  -H 'Authorization: Bearer <votre_clé_api>' \
  -H 'Content-Type: application/json'

En développement local, remplacez l'hôte par votre URL API (ex. http://localhost:8000).

Étape 3 : Initier une collecte

Exemple : 10 000 centimes (100 FCFA) via MTN Bénin.

Collecte Mobile Money

POST

/api/v1/collect/mobile-money/

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

Réponse attendue

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

Le client valide ensuite le paiement sur son téléphone (push Mobile Money). Le statut final arrive via webhook ou via l'étape suivante.

Étape 4 : Consulter le statut

Statut

GET

/api/v1/collect/mobile-money/{reference}/

curl -X GET 'https://api.fluxxpay.com/api/v1/collect/mobile-money/ORDER-123/' \
  -H 'Authorization: Bearer <votre_clé_api>'

Étape 5 : Webhooks (recommandé)

Pour éviter le polling, configurez un endpoint HTTPS et abonnez-vous aux événements collect.completed, collect.failed et collect.updated depuis le dashboard (Intégrations → Webhooks).

Votre endpoint doit répondre HTTP 2xx en moins de 30 secondes.

Cas particulier : opérateur Coris (Bénin)

Si vous utilisez operator: "coris", un code OTP est envoyé au client :

POST /collect/mobile-money/ → statut AWAITING_OTP
Saisie OTP dans votre interface
POST /collect/mobile-money/confirm/ avec reference et otp

Détails dans la référence API Collect.

Environnement de test

Name
URL API
Description
Utilisez l'URL de votre environnement de test (ex. http://localhost:8000 en local).
Name
Montant minimum XOF
Description
10 000 centimes (100 FCFA) pour les collectes en XOF.
Name
Idempotence
Description
Réutilisez la même reference + même payload → idempotent_replay: true sans double encaissement.

Problèmes courants

Name
401 Non autorisé
Description
Clé API absente, invalide ou révoquée. Vérifiez l'en-tête Authorization: Bearer.
Name
400 invalid_operator
Description
Pays ou slug opérateur non supporté — consultez GET /collect/operators/.
Name
400 invalid_phone
Description
Numéro incompatible avec le pays choisi.
Name
400 amount_too_low
Description
Montant inférieur au minimum (100 FCFA en XOF).

Voir Gestion des erreurs pour la liste complète.

Prochaines étapes

Référence API Collect Authentification Gestion des erreurs