Démarrage Rapide

Faites votre première collecte Mobile Money avec l'API Collect en quelques minutes.

Prérequis

Étape 1 : Obtenir votre clé API

1. Connectez-vous au dashboard marchand FluxxPay.
2. Allez dans Paramètres → Clés API.
3. Générez une clé (Test pour commencer).
4. 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 :

curl -X GET 'https://api.fluxxpay.me/api/v1/collect/payments/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 : Créer un paiement

Exemple : 3 000 XOF via MTN Bénin en mode direct (push Mobile Money).

curl -X POST 'https://api.fluxxpay.me/api/v1/collect/payments' \
  -H 'Authorization: Bearer <votre_clé_api>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: collect-ORDER-123' \
  -d '{
    "reference": "ORDER-123",
    "amount": 3000,
    "currency": "XOF",
    "country": "BJ",
    "mode": "direct",
    "operator": "mtn",
    "customer": { "phone": "2290166000000" },
    "description": "Premier test"
  }'

Les montants v2 sont en unités majeures (3000 = 3 000 FCFA). L'en-tête Idempotency-Key est obligatoire.

Réponse attendue

{
  "object": "collect.payment",
  "api_version": "2026-06",
  "reference": "ORDER-123",
  "status": "processing",
  "amount": 3000,
  "currency": "XOF",
  "country": "BJ",
  "mode": "direct",
  "operator": "mtn",
  "environment": "test",
  "sandbox": true,
  "idempotent_replay": false
}

En sandbox TEST, le numéro 2290166000000 aboutit à completed. Les autres fins de numéro (0001 échec, 0002 attente, 0003 annulé) sont sur Numéros de test. En production, le client valide sur son téléphone. Le statut final arrive via webhook ou via l'étape suivante.

Étape 4 : Consulter le statut

curl -X GET 'https://api.fluxxpay.me/api/v1/collect/payments/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.payment.completed, collect.payment.failed et collect.payment.processing depuis le dashboard (Paramètres → Webhooks).

Signature : en-tête X-FluxPay-Signature: t=...,v1=<hex> sur le body brut. Détails : 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 :

1. POST /collect/payments → statut awaiting_otp
2. Saisie OTP dans votre interface
3. POST /collect/payments/{reference}/confirm avec { "otp": "..." }

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

Environnement de test

Voir aussi le mode test & sandbox.

Problèmes courants

Voir Gestion des erreurs pour la liste complète.

SDK TypeScript (optionnel)

Plutôt que d'appeler l'API à la main, utilisez le client officiel :

npm install @fluxx/collect

import { FluxxCollect } from '@fluxx/collect'

const collect = new FluxxCollect({
  apiKey: process.env.FLUXX_API_KEY!,
  environment: 'test',
})
const result = await collect.createPayment({
  reference: 'ORDER-001',
  amount: 3000,
  country: 'BJ',
  mode: 'direct',
  operator: 'mtn',
  customer: { phone: '2290166000000' },
}, { idempotencyKey: 'ORDER-001' })

Contrat OpenAPI : https://cdn.fluxxpay.me/v2/collect/openapi.json. Guide complet sur la page SDK.

Voir aussi