Mode test & sandbox

Le mode test FluxxPay permet de valider une intégration complète sans appeler de PSP réel et sans mouvement financier. Vous utilisez le même dashboard, les mêmes APIs et les mêmes webhooks, mais dans l'environnement TEST.

Le sélecteur Test / Live vous permet de passer d'un environnement à l'autre depuis le dashboard. Les données test restent séparées des données de production.

Pourquoi un mode test

Le sandbox sert à plusieurs profils.

Name
Marchands
Description
Créer des clés API test, initier des transactions fictives, vérifier les statuts et valider les parcours avant d'encaisser de vrais clients.
Name
Développeurs
Description
Tester l'authentification, l'idempotence, les erreurs, les webhooks et les retries sans dépendre d'un opérateur Mobile Money ou d'une carte réelle.
Name
Support & QA
Description
Reproduire un problème, tester un scénario failed ou pending, et vérifier l'expérience dashboard sans toucher aux données live.

Dashboard test

Dans le dashboard marchand, utilisez le sélecteur d'environnement dans l'en-tête.

Name
Mode Test
Description
Affiche et crée uniquement des données TEST : clés API test, transactions test, liens de paiement test et événements sandbox.
Name
Mode Live
Description
Affiche et crée uniquement des données PRODUCTION. Les paiements live peuvent appeler les providers réels configurés.
Name
Isolation
Description
Une transaction créée en mode test ne doit jamais apparaître dans les vues live, les rapports live ou les exports de production.

Le dashboard transmet l'environnement actif à l'API via l'en-tête X-Fluxx-Environment lorsque vous utilisez une session JWT (navigation dashboard).

Avec une clé API, l'environnement (TEST ou PRODUCTION) est déterminé par la clé elle-même. L'en-tête X-Fluxx-Environment n'est pas nécessaire et n'est pas pris en compte pour les appels signés par clé API.

Accès progressif

Le sandbox est disponible dès qu'un marchand existe. Les nouveaux marchands démarrent en mode TEST afin de pouvoir créer des liens, clés et transactions de test sans risque.

Name
Test disponible
Description
Vous pouvez utiliser le dashboard, les clés test et les transactions sandbox sans validation KYC complète.
Name
Live limité
Description
Selon l'état du compte marchand, l'encaissement live peut être disponible avant la validation KYC complète. Les sorties de fonds restent bloquées.
Name
Live complet
Description
Les reversements, transferts wallet et paiements en masse sont disponibles uniquement lorsque le marchand est actif avec KYC validé.

Clés API

Créez toujours une clé API test avant d'intégrer un nouveau site, plugin, backend ou application mobile. Depuis le dashboard : Paramètres → Clés API (/dashboard/settings/api-keys).

Name
Clé test
Description
À utiliser avec le mode TEST. Elle permet d'initier des paiements simulés.
Name
Clé production
Description
À utiliser uniquement après validation du parcours de test et activation du compte marchand.
Name
Sécurité
Description
Stockez les clés dans un secret manager ou des variables d'environnement. Ne les exposez jamais côté client public.

Voir l'authentification

Créer des transactions test

En mode TEST, vous pouvez créer des paiements depuis le dashboard ou via l'API Collect. Aucun opérateur Mobile Money réel n'est contacté : FluxxPay simule le résultat.

Paiement sandbox v2

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

Montants en unités majeures (3000 = 3 000 FCFA). Essayez aussi le Playground Collect (direct et hosted).

Scénarios sandbox

Le simulateur Collect réagit à la référence marchand (reference) et au numéro de téléphone (customer.phone). Les statuts API v2 sont en minuscules.

Name
Succès (défaut)
Description
Référence sans mot-clé spécial et numéro standard → completed.
Name
Échec
Description
Inclure FAIL dans reference, ou un numéro se terminant par 0001 → failed.
Name
En attente
Description
Inclure PENDING dans reference, ou un numéro se terminant par 0002 → pending.
Name
Annulé
Description
Inclure CANCEL dans reference, ou un numéro se terminant par 0003 → cancelled.
Name
Coris OTP (Bénin)
Description
operator: coris → awaiting_otp. Confirmez avec POST /collect/payments/{reference}/confirm : OTP 123456 → completed, 000000 → failed, 111111 → reste en attente.
Name
Hosted (checkout)
Description
mode: hosted → awaiting_payment + checkout_url. En TEST : POST /collect/payments/{reference}/pay pour simuler le paiement.

Exemples : order-123, order-FAIL, order-PENDING, order-CANCEL.

Webhooks

Les webhooks Collect ont la même structure en test et en production. Événements principaux : collect.payment.created, collect.payment.completed, collect.payment.failed, collect.payment.cancelled, collect.payment.expired.

Configurez-les depuis Paramètres → Webhooks (/dashboard/settings/webhooks) et abonnez-vous aux événements collect.payment.*.

{
  "type": "collect.payment.completed",
  "event_version": "2026-06",
  "environment": "test",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "object": {
      "reference": "test-order-123",
      "status": "completed",
      "amount": 3000,
      "currency": "XOF",
      "sandbox": true
    }
  }
}

Signature : X-FluxPay-Signature: t=...,v1=<hex> (HMAC sur le body brut). Voir Webhooks.

Vérifiez environment (test ou live) et data.object.sandbox avant toute logique métier. Un webhook test ne doit jamais déclencher une livraison réelle ni un crédit wallet live.

Passage en production

Avant de passer en production :

Créez au moins une transaction sandbox réussie (direct et/ou hosted).
Testez un échec, un pending et un webhook reçu (vérifiez la signature v2).
Vérifiez que votre backend ignore ou sépare bien les webhooks TEST.
Créez une clé API production.
Si vous prévoyez des reversements ou décaissements, complétez votre validation de compte (KYC).
Basculez le dashboard en mode Live.
Lancez un premier paiement réel de faible montant.

Validation du compte (KYC)Démarrage rapide Référence API Collect