FluxxPay

API Collect

L'API Collect permet d'encaisser des paiements Mobile Money en Afrique de l'Ouest (Bénin, Togo, Côte d'Ivoire) via une interface unique. Vous indiquez le pays et l'opérateur ; FluxxPay route la transaction en interne. Une seule intégration FluxxPay suffit.

Base URL : https://api.fluxxpay.com/api/v1/collect/ (ou votre environnement de test)

Vue d'ensemble

L'API Collect suit un modèle agrégateur : une requête, un contrat, plusieurs réseaux Mobile Money.

  • Name
    Pays (v1)
    Description

    Bénin (BJ), Togo (TG), Côte d'Ivoire (CI).

  • Name
    Opérateurs
    Description

    MTN, Moov, Celtiis, Coris, Togocom, Wave, Orange — voir le catalogue.

  • Name
    Idempotence
    Description

    Référence marchand unique + en-tête Idempotency-Key sur les POST.

  • Name
    Asynchrone
    Description

    Collecte initiée puis finalisée côté PSP ; statut via GET ou webhooks collect.*.

  • Name
    Confirmation OTP
    Description

    Flux en deux étapes pour l'opérateur Coris (Bénin) uniquement.

Côté marchand, vous configurez uniquement votre clé API FluxxPay et vos webhooks. Aucun autre compte ou identifiant de passerelle à gérer de votre côté.

Authentification

Toutes les requêtes doivent être authentifiées :

  • Name
    Authorization
    Description

    Authorization: Bearer <votre_clé_api> (recommandé).

  • Name
    X-API-Key
    Description

    Alternative équivalente : X-API-Key: <votre_clé_api>.

  • Name
    Idempotency-Key
    Description

    Fortement recommandé sur POST /collect/mobile-money/ (obligatoire si activé côté plateforme).

En-têtes

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

Obtenez votre clé depuis le dashboard marchand FluxxPay → Intégrations → Clés API.

Démarrage rapide

  • Name
    1. Catalogue
    Description

    GET /collect/operators/ — lister pays et opérateurs pour votre UI.

  • Name
    2. Collecte
    Description

    POST /collect/mobile-money/ avec country, operator, reference, amount, phone.

  • Name
    3. Statut
    Description

    GET /collect/mobile-money/&lt;reference&gt;/ — option ?sync=true pour rattrapage PSP.

  • Name
    4. Webhooks
    Description

    Abonnez-vous aux événements collect.* pour le résultat final.

Authentification détaillée
GET/api/v1/collect/operators/

Catalogue opérateurs

Retourne le catalogue des pays et opérateurs supportés en v1 (slug, alias, requires_otp pour Coris).

Catalogue

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'

Opérateurs v1 (résumé)

  • Name
    BJ
    Description

    mtn, moov, celtiis, coris (OTP requis).

  • Name
    TG
    Description

    togocom, moov (alias : tmoney, flooz, etc.).

  • Name
    CI
    Description

    mtn, moov, wave, orange.

POST/api/v1/collect/mobile-money/

Initier une collecte

Initie une collecte Mobile Money. La référence marchand doit être unique par marchand et sert à l'idempotence.

Corps de la requête

  • Name
    amount
    Type
    integer
    Description

    Montant en centimes (ex. 10000 = 100 FCFA).

  • Name
    phone
    Type
    string
    Description

    Numéro Mobile Money (format local ou international selon le pays).

  • Name
    country
    Type
    string
    Description

    Code pays : BJ, TG, CI.

  • Name
    operator
    Type
    string
    Description

    Slug opérateur (ex. mtn, moov, coris).

  • Name
    reference
    Type
    string
    Description

    Identifiant unique de la commande côté marchand.

  • Name
    currency
    Type
    string
    Description

    Défaut : XOF.

  • Name
    description
    Type
    string
    Description

    Libellé court (optionnel, max. 255 caractères).

  • Name
    customer_first_name
    Type
    string
    Description

    Prénom client (optionnel).

  • Name
    customer_last_name
    Type
    string
    Description

    Nom client (optionnel).

Réponses

  • Name
    201 Created
    Description

    Collecte créée.

  • Name
    200 OK
    Description

    Rejeu idempotent (idempotent_replay: true).

  • Name
    400
    Description

    Données invalides (invalid_operator, invalid_phone, amount_too_low, etc.).

Requête

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": "Paiement boutique"
  }'

Réponse

201
{
  "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
}
POST/api/v1/collect/mobile-money/confirm/

Confirmer Coris (OTP)

Après une initiation Coris (operator: coris, statut AWAITING_OTP), confirmez avec le code OTP reçu par le client.

  • Name
    reference
    Type
    string
    Description

    Même référence que l'étape d'initiation.

  • Name
    otp
    Type
    string
    Description

    Code OTP (4 à 8 chiffres).

Confirmation

POST
/api/v1/collect/mobile-money/confirm/
curl -X POST 'https://api.fluxxpay.com/api/v1/collect/mobile-money/confirm/' \
  -H 'Authorization: Bearer <votre_clé_api>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "ORDER-123",
    "otp": "123456"
  }'
GET/api/v1/collect/mobile-money/{reference}/

Statut d'une collecte

Retourne le statut d'une collecte par référence marchand.

Paramètres de requête

  • Name
    sync
    Type
    boolean
    Description

    true, 1 ou yes — force une synchronisation PSP si la collecte est encore en attente.

Statut

GET
/api/v1/collect/mobile-money/{reference}/
curl -X GET 'https://api.fluxxpay.com/api/v1/collect/mobile-money/ORDER-123/?sync=true' \
  -H 'Authorization: Bearer <votre_clé_api>' \
  -H 'Content-Type: application/json'

Montants

  • Name
    Unité
    Description

    amount est en centimes (plus petite unité). Ex. 10000 = 100 FCFA.

  • Name
    Minimum XOF
    Description

    10 000 centimes (100 FCFA) pour les collectes en XOF.

  • Name
    Devise
    Description

    XOF par défaut ; autres devises selon configuration marchand.

États

  • Name
    PENDING
    Description

    Collecte créée, en attente côté PSP.

  • Name
    PROCESSING
    Description

    Traitement en cours.

  • Name
    COMPLETED
    Description

    Paiement réussi.

  • Name
    FAILED
    Description

    Échec définitif.

  • Name
    CANCELLED
    Description

    Annulée ou expirée.

  • Name
    AWAITING_OTP
    Description

    Coris uniquement — OTP envoyé, confirmation requise.

Champs de réponse utiles : id, reference, status, amount, currency, country, operator, phone, psp_reference, message, idempotent_replay.

Confirmation OTP (Coris)

  • Name
    Étape 1
    Description

    POST /collect/mobile-money/ avec country: BJ, operator: coris.

  • Name
    Étape 2
    Description

    Afficher un champ OTP lorsque status vaut AWAITING_OTP.

  • Name
    Étape 3
    Description

    POST /collect/mobile-money/confirm/ avec reference et otp.

Réponse après initiation Coris

{
  "status": "AWAITING_OTP",
  "next_action": "confirm",
  "reference": "ORDER-123",
  "message": "OTP envoyé au client..."
}

Webhooks

Configurez vos URLs dans le dashboard (Intégrations → Webhooks) et abonnez-vous à :

  • Name
    collect.initiated
    Description

    Collecte créée côté FluxxPay.

  • Name
    collect.completed
    Description

    Paiement réussi — mettre à jour commande, envoyer reçu.

  • Name
    collect.failed
    Description

    Échec — notifier ou proposer un autre moyen de paiement.

  • Name
    collect.cancelled
    Description

    Collecte annulée.

  • Name
    collect.updated
    Description

    Changement de statut intermédiaire.

Traitez collect.completed et collect.failed comme source de vérité. Utilisez GET + ?sync=true en secours (webhook manqué, support).

Configurez les URLs et événements collect.* depuis le dashboard marchand (Intégrations → Webhooks).

Erreurs

Corps d'erreur typique :

{
  "error": "Message lisible",
  "code": "invalid_operator"
}
  • Name
    invalid_operator
    Description

    Pays ou opérateur non supporté (400).

  • Name
    invalid_phone
    Description

    Numéro invalide pour le pays (400).

  • Name
    amount_too_low
    Description

    Montant inférieur au minimum XOF (400).

  • Name
    invalid_otp
    Description

    OTP Coris invalide (400).

  • Name
    otp_not_required
    Description

    Confirmation non attendue (400).

  • Name
    missing_idempotency_key
    Description

    En-tête Idempotency-Key manquant (400).

  • Name
    not_found
    Description

    Référence inconnue (404).

  • Name
    collect_failed
    Description

    Erreur interne collecte (500).

  • Name
    collect_confirm_failed
    Description

    Erreur interne confirmation (500).

Gestion des erreurs HTTP

Bonnes pratiques

  • Name
    Idempotence
    Description

    reference stable par commande ; Idempotency-Key identique sur retry réseau identique.

  • Name
    UX
    Description

    État « en attente Mobile Money » pour PENDING / PROCESSING ; écran OTP pour Coris.

  • Name
    Sécurité
    Description

    HTTPS, pas de logs de clés API ni OTP ; vérifier signatures webhooks.

  • Name
    Tests
    Description

    Clé Test, montants minimaux, catalogue GET /operators/ avant l'UI production.

Prochaines étapes

Démarrage rapide FluxxPay

Was this page helpful?