Comment tester en sécurité dans la sandbox ?

L’environnement de test lomi. vous permet d’exécuter des parcours de paiement complets, checkout hébergé, formulaire carte intégré et mobile money, sans mouvement de fonds réels ni impact sur les soldes live. Cette page est la référence unique pour simuler les paiements : quels numéros de carte utiliser, le comportement de Wave et MTN MoMo en test, et ce que vous devez observer dans le tableau de bord et via les webhooks.

Pour les clés API, les URL de base et les limites, voir Authentification. Pour votre première requête authentifiée, voir Intégration API.

Environnement de test en bref

L’environnement est déterminé par votre clé API, pas par le nom d’hôte : une clé de test crée et lit toujours des données de test.

Checkout hébergé: démarrage rapide

Paiement carte bac à sable en cinq étapes (recettes complètes dans Recettes API et checkout hébergé) :

1. Créer une session: POST https://sandbox.api.lomi.africa/checkout-sessions avec lomi_sk_test_… (amount, currency_code, success_url, cancel_url minimum). Voir API sessions checkout.
2. Ouvrir l’URL: la réponse contient checkout_url.
3. Payer avec une carte test: Carte, 4242 4242 4242 4242, expiration 12/34, CVC 123 (liste complète).
4. Finaliser: transaction completed ; le solde test augmente.
5. Vérifier: mode Test du tableau de bord et webhooks ("environment": "test").

POST /checkout-sessions  →  { "checkout_url": "https://…" }  →  paiement client  →  webhook + solde test

Comment le mode test est choisi

API REST

Toute requête authentifiée avec une clé secrète de test s’exécute en mode test. Les sessions checkout, payment intents, liens de paiement et transactions créés portent "environment": "test".

Checkout hébergé

L’environnement du lien de paiement ou de la session checkout pilote le grand livre et le mode formulaire carte. Créez liens et sessions en mode Test dans le portail.

Tableau de bord

Basculez Test / Live dans le portail. Les liens, QR codes et articles créés en test n’apparaissent que dans les rapports et soldes de test.

Soldes de test et effets de bord

Lorsqu’une transaction de test passe à completed :

• Votre solde de test augmente (grand livre interne de test), pas votre solde retirable live.
• La trésorerie plateforme et les flux live ne sont pas mis à jour.
• Les métadonnées de transaction peuvent indiquer un crédit sur le grand livre de test.

Les e-mails et WhatsApp clients sont ignorés en mode test.

Pour le fonctionnement des soldes live après complétion, voir Soldes et règlement.

Tester les paiements par carte

En bac à sable, les paiements carte s’appuient sur des numéros de carte de test qui reproduisent le comportement des émetteurs, approbation, refus et authentification forte, sans débiter quiconque. Utilisez-les uniquement avec des clés API de test et des sessions checkout en mode test.

Comment un paiement carte se termine en test

Le formulaire carte du checkout hébergé suit toujours l’environnement du lien de paiement ou de la session (test ou live).

Saisir une carte de test

Dans le navigateur ou dans votre formulaire carte :

• Numéro : une valeur des tableaux ci-dessous (les espaces sont optionnels ; 4242 4242 4242 4242 et 4242424242424242 sont équivalents).
• Expiration : toute date future, par exemple 12/34.
• CVC : trois chiffres pour la plupart des marques ; quatre chiffres pour les numéros de test American Express.
• Titulaire et facturation : toute valeur acceptée par votre formulaire.

Pour tester un échec de validation du CVC, vous devez saisir un CVC. Si le champ est vide, le contrôle peut être ignoré et une carte « CVC incorrect » ne se comportera pas comme prévu.

Paiements réussis par marque

Ces numéros aboutissent à un débit standard en test lorsque la confirmation réussit.

Pour la QA quotidienne, 4242 4242 4242 4242 (Visa) est le choix par défaut.

Paiements refusés ou en échec

Servez-vous de ces numéros pour vérifier les messages d’erreur, les échecs de checkout et les webhooks PAYMENT_FAILED. La transaction ne doit pas passer en completed et le solde de test ne doit pas augmenter.

Voir Erreurs pour la forme des échecs dans les réponses API.

Authentification forte (3D Secure)

Certains numéros déclenchent une étape d’authentification (redirection ou fenêtre modale) avant la réussite du paiement. Utilisez-les pour les cartes enregistrées, les abonnements et les parcours où il faut gérer « authentifier » ou « paiement refusé ».

Testez l’authentification sur votre checkout hébergé ou formulaire carte intégré, pas seulement via l’API, afin de reproduire l’expérience client de production.

Aide-mémoire: numéros les plus utiles

Formulaires carte intégrés

Avec lomi Payment Elements ou l’API Payment Intents : créez un payment intent avec lomi_sk_test_…, montez l’UI carte avec lomi_pk_test_…, puis confirmez avec le client_secret retourné. Utilisez les numéros de test ci-dessus dans le champ carte.

Tester le mobile money

Wave

En mode test, lomi. crée une transaction completed et crédite votre solde de test dès l’enregistrement du checkout Wave. Le client peut encore voir l’interface Wave, mais le solde de test du tableau de bord se met à jour sans attendre un débit réel du portefeuille.

Comment tester :

1. Créer un lien ou une session checkout en test avec Wave activé.
2. Ouvrir le checkout et choisir Wave.
3. Saisir un numéro valide au format E.164 (par ex. +225 07 00 00 00 00 pour la Côte d’Ivoire).
4. Compléter ou annuler sur l’écran Wave ; vérifier transaction et solde de test.

MTN MoMo

En mode test, la transaction est aussi completed et le solde de test est crédité à l’initiation du paiement MTN. Les mises à jour de statut en test sont traitées comme réussies pour le grand livre. Le checkout utilise le bac à sable MTN lorsque la session est en test.

Comment tester :

1. Lien ou session en test avec MTN activé.
2. Saisir un numéro de téléphone valide pour le pays (format international).
3. Vérifier la transaction completed dans la vue test du tableau de bord.

Pour les numéros autorisés en bac à sable MTN, voir le portail développeur MTN MoMo.

Pays pris en charge (checkout hébergé)

Carte vs mobile money en test

Virements en mode test

Avec une clé API test, POST /payouts se comporte ainsi :

Les virements Wave vers un tiers exigent recipient.name et recipient.phone avec une clé live. Le numéro n’a pas besoin de correspondre à un payout_method_id. Voir Virements.

GET /payouts avec une clé test ne liste que les retraits test ; les virements bénéficiaires live sont exclus.

Recettes API et checkout hébergé

curl -sS \
  -H "X-API-Key: $LOMI_SECRET_KEY" \
  "https://sandbox.api.lomi.africa/accounts"

curl -sS -X POST "https://sandbox.api.lomi.africa/checkout-sessions" \
  -H "X-API-Key: $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency_code": "XOF",
    "title": "Test bac à sable",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'

curl -sS -X POST "https://sandbox.api.lomi.africa/charge/card" \
  -H "X-API-Key: $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency_code": "XOF",
    "customer_email": "test@example.com",
    "customer_name": "Utilisateur test"
  }'

Tester les abonnements

Utilisez des clés API test et les flux de Paiements en bac à sable.

1. Créez un produit récurrent avec trial_enabled: true ou first_payment_type: non_initial (voir Produits).
2. Lien de paiement ou session: ouvrez le tunnel hébergé ou l’URL S’abonner de la vitrine avec le product_id récurrent.
3. Essai + carte: utilisez 4242 4242 4242 4242 ; le tunnel enregistre la carte via SetupIntent avec 0 dû aujourd’hui. Attendez SUBSCRIPTION_CREATED à la fin de l’inscription.
4. Essai + Wave / MTN: complétez les coordonnées ; l’inscription doit réussir sans prélèvement en mode test.
5. Inscription payante: first_payment_type: initial et paiement test normal ; vérifiez status: active et une transaction instalment.
6. Webhooks: abonnez-vous à SUBSCRIPTION_CREATED, SUBSCRIPTION_RENEWED, SUBSCRIPTION_CANCELLED et PAYMENT_FAILED pour les échecs de renouvellement.

Les renouvellements planifiés en test utilisent des dates futures ; inspectez next_billing_date via le tableau de bord ou l’API.

Webhooks en test

1. Dans le tableau de bord (Developers → Webhooks), ajoutez une URL en mode Test.
2. Utilisez le secret de signature de cette URL pour vérifier la signature sur le corps brut de la requête.
3. Les paiements de test réussis émettent des événements comme PAYMENT_SUCCEEDED avec "environment": "test" le cas échéant.
4. Utilisez Test webhook pour envoyer un exemple PAYMENT_SUCCEEDED sans paiement réel.

Voir Webhooks. Pour l’automatisation, voir le Guide de tests.

Dépannage

Documentation associée

• Authentification: clés, environnements, sécurité
• Intégration API: première requête et index API
• Sessions checkout: API checkout hébergé
• Encaissements directs: Wave, MTN et carte (POST /charge/card)
• Liens de paiement: liens réutilisables
• lomi Payment Elements: UI carte côté client
• Webhooks: abonnements aux événements
• Soldes et règlement: règles des soldes live
• Guide de tests: automatisation, CI, écouteurs webhook

Passer en production

Passez aux clés live uniquement quand votre intégration est validée de bout en bout. Voir la checklist de mise en production.