🧪 Environnement de test (Sandbox)

Le sandbox est une copie complète d'Efaina dédiée à vos tests. Vous y créez de vrais checkouts, recevez de vrais webhooks et voyez de vraies transactions dans votre dashboard — mais aucun argent ne circule.

• API : https://sandback.efaina.com/api/public/v1
• Dashboard : https://sandbox.efaina.com

Clés séparées

Une clé API générée en sandbox ne fonctionne pas en production, et inversement.

Les moyens mobile money sont simulés

MVola, Orange Money et Airtel Money sont disponibles en sandbox, mais entièrement simulés : aucune requête n'est envoyée aux opérateurs, aucun code USSD n'arrive sur un téléphone, et aucun compte n'est débité.

L'intérêt : le résultat est déterministe. Vous décidez à l'avance si un paiement doit réussir, échouer, rester en attente ou tomber en erreur — et vous pouvez donc tester chaque cas de manière reproductible, y compris ceux qui sont difficiles à provoquer en vrai.

Choisir le résultat d'un paiement

Le résultat est décidé par le numéro de téléphone du payeur, à la manière des numéros de carte de test. Il n'y a rien à configurer ni aucun appel supplémentaire à faire.

Le scénario se lit sur les 4 derniers chiffres. Les chiffres du milieu sont libres : 0341230000 et 0349990000 donnent tous les deux un succès, ce qui vous permet de simuler plusieurs clients distincts pour un même scénario.

4 derniers chiffres	MVola (034 / 036 / 038)	Orange (032 / 037)	Airtel (033 / 035)	Résultat
0000	0340000000	0320000000	0330000000	✅ Succès après ~5 s
0001	0340000001	0320000001	0330000001	❌ Échec — le client a refusé
0002	0340000002	0320000002	0330000002	❌ Échec — solde insuffisant
0003	0340000003	0320000003	0330000003	⏳ Reste en attente indéfiniment
0004	0340000004	0320000004	0330000004	❌ Échec immédiat — opérateur indisponible
0005	0340000005	0320000005	0330000005	❌ Annulé par le client
0006	0340000006	0320000006	0330000006	❌ Expiré — le client n'a jamais répondu
0007	0340000007	0320000007	0330000007	✅ Succès, mais après ~45 s
tout autre	0341234567	0329876543	0335551234	✅ Succès (comportement par défaut)

Cas particuliers à connaître

0004 échoue dès l'initiation. La réponse de POST /handle-payment/{checkout} renvoie directement le statut error : la transaction ne passe jamais par pending. C'est le cas « l'API de l'opérateur est en panne ».

0003 ne se résout jamais. Utilisez-le pour vérifier que votre intégration gère correctement un paiement qui n'aboutit pas : timeout de votre côté, relance, réconciliation.

Le préfixe doit correspondre au moyen choisi. Un numéro 033… envoyé sur MVola est refusé, exactement comme en production. C'est volontaire : ça vous permet de tester ce cas d'erreur.

Préfixes	Moyen
034, 036, 038	MVola
032, 037	Orange Money
033, 035	Airtel Money

Il n'y a pas de statut « annulé » pour MVola et Airtel. Chez ces opérateurs, un refus ou une annulation sur le USSD remonte comme une erreur, pas comme une annulation. Le sandbox reproduit ce comportement plutôt qu'un statut idéalisé, pour que votre code soit prêt pour la production.

Le délai est volontaire

Un paiement simulé passe par pending, puis bascule vers son statut final après environ 5 s (45 s pour 0007). Ce n'est pas de la lenteur : c'est ce qui vous oblige à traiter correctement l'asynchronisme, exactement comme en production.

Trois façons d'apprendre le statut final :

Méthode	Délai
La page de paiement interroge le statut automatiquement	≤ 10 s
Le client revient sur votre return_url	immédiat
Webhook transaction.completed envoyé à votre endpoint	≤ 60 s

Ne livrez jamais sur le seul retour navigateur

Le client peut fermer son onglet avant la redirection. C'est aussi vrai en sandbox : seul le webhook — ou une relecture de la transaction — atteste du paiement. Voir les webhooks.

Si votre intégration ne repose que sur les webhooks et ne consulte jamais le statut, tout fonctionne : les paiements simulés sont résolus automatiquement et votre webhook part quand même.

Orange Money : la page de paiement simulée

Orange Money est le seul moyen qui redirige votre client vers une page hébergée. En sandbox, cette page est servie par Efaina et porte un bandeau « SIMULATEUR SANDBOX — aucun paiement réel ».

Le déroulé est identique à la production :

1. POST /handle-payment/{checkout} renvoie is_checkout: true et une checkout_url.
2. Vous redirigez le client vers cette URL.
3. Sur la page, il saisit un code à 4 chiffres puis clique Payer ou Annuler.
4. Il est redirigé vers votre return_url (ou cancel_url).
5. En parallèle, la notification part et votre webhook est déclenché.

Le code secret accepte n'importe quels 4 chiffres — c'est le numéro payeur qui décide du résultat. Une seule exception : 0000 force un code secret erroné, quel que soit le numéro utilisé.

La page expire au bout de 15 minutes, ou dès que la transaction est résolue, comme une vraie session Orange.

Retraits et remboursements

En sandbox, les demandes de retrait et de remboursement en attente sont acceptées automatiquement chaque minute. Vous n'avez rien à faire et rien à attendre.

Ce qui diffère de la production

	Sandbox	Production
Appels aux opérateurs	aucun	réels
Résultat d'un paiement	décidé par le numéro	décidé par le client
Délai avant statut final	~5 s, fixe	variable, souvent plus long
Page Orange Money	simulée, hébergée par Efaina	hébergée par Orange
Retrait / remboursement	acceptés automatiquement	validation manuelle

Tout le reste est identique : statuts, format des réponses, webhooks, calcul des frais, reçus.

Un moyen de paiement n'apparaît pas ?

La disponibilité de chaque moyen reste pilotée par Efaina et peut être coupée temporairement, même en sandbox. Un moyen indisponible s'affiche grisé sur la page de paiement. Contactez le support si la situation persiste.