Sandbox Wave Business + Orange Money : guide complet de test pour développeurs (2026)

Pourquoi un sandbox dédié change tout

En 2026, l'écosystème paiement sénégalais s'est structuré et Wave Business + Orange Money proposent désormais des environnements de test (sandbox) sérieux. Avant 2024, les devs testaient sur des comptes merchants réels avec de vrais petits montants — fastidieux, coûteux, et impossible de tester les scénarios d'échec.

Aujourd'hui, un dev e-commerce qui intègre Wave + OM doit commencer par le sandbox. Bénéfices :

• Itération rapide (zéro frais, zéro friction transactions réelles).
• Test exhaustif des cas d'erreur (timeout, refusé, fraude, 3DS).
• Sécurité (pas de clés API prod sur la machine du dev).
• CI/CD automatisable.

Ce guide donne le setup complet : credentials, numéros de test, scénarios à couvrir, mocking webhooks, test de la signature HMAC. Audience : devs back-end et full-stack qui intègrent les paiements la première fois.

H2 : Setup environnement Wave Business sandbox

Étape 1 — Compte développeur. Créer un compte sur developer.wave.com (distinct du compte merchant prod). Activer le mode sandbox dans le dashboard. Vous recevez :

• WAVE_API_KEY_SANDBOX (format : wave_sandbox_sk_...)
• WAVE_WEBHOOK_SECRET_SANDBOX (format : whsec_sandbox_...)
• Endpoint sandbox : https://api.sandbox.wave.com/v1/

Étape 2 — Configuration env vars. Fichier .env.local :

`

WAVE_API_KEY=wave_sandbox_sk_xxxxxxxxxxxxx

WAVE_WEBHOOK_SECRET=whsec_sandbox_xxxxxxxxxxxxx

WAVE_API_BASE_URL=https://api.sandbox.wave.com/v1

`

Étape 3 — Tunneling pour webhooks en local. Wave a besoin d'un endpoint HTTPS public pour livrer les webhooks. En dev local, utiliser ngrok, localtunnel ou cloudflared :

`bash

ngrok http 3000

# → https://abcd-1234.ngrok-free.app

`

Configurer cette URL dans le dashboard sandbox sous Webhooks → Endpoint URL.

Étape 4 — Numéros de test Wave. Wave sandbox fournit ces numéros virtuels :

H2 : Setup environnement Orange Money sandbox

OM Business propose son sandbox via la plateforme developer.orange.com (programme Orange Developer Africa).

Étape 1 — Inscription. Compte gratuit sur developer.orange.com → souscription au produit Orange Money Web Payment ou Orange Money Mobile Money API. Validation manuelle 2-5 jours ouvrés.

Étape 2 — Récupération credentials.

• OM_CLIENT_ID et OM_CLIENT_SECRET (auth OAuth2)
• OM_MERCHANT_KEY_SANDBOX
• Endpoint sandbox : https://api.sandbox.orange-sonatel.com/

Étape 3 — Numéros de test OM.

Étape 4 — Test du flux OAuth2. OM exige un token OAuth2 généré à chaque session :

`bash

curl -X POST https://api.sandbox.orange-sonatel.com/oauth/token \

-u $OM_CLIENT_ID:$OM_CLIENT_SECRET \

-d "grant_type=client_credentials"

`

Token valide 1h, à rafraîchir.

H2 : Scénarios de test indispensables

1. Paiement accepté nominal

Créer une commande, lancer le checkout, payer avec +221700000001 (Wave) ou +221770000001 (OM). Webhook payment.completed doit arriver < 30s. Vérifier statut commande paid.

2. Paiement refusé (solde insuffisant)

Numéro +221700000002 (Wave). Webhook payment.failed avec error_code: insufficient_funds. La commande doit rester en pending, pas failed permanente (le client peut retenter avec un autre wallet).

3. Timeout client

Numéro +221700000003. Aucun webhook ne doit arriver dans les 5-10 min. Votre back-end doit avoir un job cron qui requête l'API Wave GET /payments/:id pour les paiements pending depuis >10 min et reconcilier.

4. Webhook livré 2x (idempotence)

Activer Webhook → Test → Replay dans le dashboard. Votre endpoint doit retourner already_processed: true au deuxième appel. Aucun double-débit, aucune double-livraison côté métier.

5. Signature HMAC invalide

Modifier manuellement la signature en envoyant un payload custom via curl. Votre endpoint doit retourner 401 invalid_signature. Logger l'incident avec IP source.

6. 3DS (si carte ajoutée)

Si Wave Card ou OM Card est intégré, tester avec carte de test 3DS challenge : 4000 0027 6000 3184 (Visa 3DS Required). Vérifier que le flux redirect challenge → callback → webhook fonctionne.

7. Refund partiel

API POST /refunds avec amount < montant initial. Webhook refund.created puis refund.completed. Vérifier comptabilité partielle.

8. Race condition création commande / webhook

Provoquer le scénario : payer AVANT que la commande ne soit insérée en DB (retarder l'insert avec un sleep en dev). Le webhook arrive, votre endpoint ne trouve pas la commande. Comportement attendu : créer la commande en pending AVANT l'appel API checkout, jamais après.

H2 : Mocking en CI/CD

Pour les tests automatisés (Jest, Vitest, Pytest), ne pas appeler le sandbox à chaque CI run (rate-limited à ~1000 req/h). Utiliser un mock local :

`ts

// __mocks__/wave-client.ts

export const waveClient = {

createPayment: jest.fn().mockResolvedValue({

id: 'pay_test_01HZK7Y',

status: 'pending',

checkout_url: 'https://sandbox.wave.com/checkout/pay_test_01HZK7Y',

}),

getPayment: jest.fn(),

};

`

Pour tester votre handler webhook end-to-end, générer un payload signé manuellement :

`ts

const payload = JSON.stringify({ id: 'evt_test', type: 'payment.completed', data: {...} });

const ts = Math.floor(Date.now() / 1000);

const sig = crypto.createHmac('sha256', secret).update(${ts}.${payload}).digest('hex');

// POST avec header Wave-Signature: t=${ts},v1=${sig}

`

H2 : Erreurs fréquentes en sandbox

• Confondre clés sandbox et clés prod (le préfixe _sandbox_ aide, mais à vérifier en CI : assertSandboxKey()).
• Oublier de redémarrer ngrok et garder une URL périmée dans le dashboard webhook (les webhooks arrivent dans le vide).
• Tester avec un numéro réel — pas en sandbox, ça consomme des frais réels.
• Ne pas tester les scénarios d'échec — vous découvrez les bugs en prod.
• Skipper la vérification de signature en dev "parce que c'est sandbox" — vous livrez du code non-testé.

FAQ

Combien de temps Wave/OM mettent à activer le sandbox ?

Wave : instantané après création compte développeur (10 min). OM : validation manuelle 2-5 jours ouvrés via Orange Developer Africa. Anticiper si deadline projet.

Peut-on tester sans tunnel (ngrok) ?

Oui : utiliser l'option Test webhook dans le dashboard Wave/OM qui POST manuellement un payload signé vers une URL de votre choix. Mais pour un test end-to-end réaliste, ngrok reste indispensable en local.

Différence sandbox vs prod côté API ?

Endpoints identiques (/payments, /refunds, /customers), seul l'URL de base change. Quelques restrictions : pas de KYC réel client en sandbox, pas de fonds réels, rate-limits plus stricts (1000 req/h vs 10000 req/h prod).

Comment partager le sandbox avec une équipe dev ?

Compte développeur Wave/OM partagé via mot de passe (préférer un coffre-fort comme 1Password Teams). Chaque dev utilise les mêmes credentials sandbox. En prod : compte merchant unique, secrets dans le vault (AWS Secrets Manager, Doppler, Infisical).

Sandbox supporte-t-il les paiements multi-devises ?

Wave sandbox : FCFA uniquement (cohérent avec la prod). OM sandbox : FCFA + EUR pour le test des flux diaspora. Pour multi-devise réelle (USD, XAF, NGN), passer par Stripe ou un agrégateur (cf article Wave vs Stripe).

Discutons de votre intégration

Si vous lancez l'intégration Wave + OM sur un projet e-commerce et voulez gagner 2-3 semaines en mettant un sandbox propre dès le départ, nous pouvons livrer le boilerplate complet (Next.js + Prisma + signature HMAC + tests). WhatsApp +221 77 596 93 33.