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, MTN aboutit souvent directement à completed. Le client valide le paiement sur son téléphone en production. 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