Le verdict en trois phrases
Pour une boutique à Bamako, l'API Wave Business s'intègre côté serveur afin de ne jamais exposer votre clé secrète dans le navigateur. Vous créez une checkout session, redirigez le client vers l'URL Wave, puis attendez un webhook signé en HMAC pour marquer la commande payée. Les frais marchand tournent autour de 1 %, le settlement est T+1, et un webhook non confirmé sous 30 secondes déclenche jusqu'à 3 tentatives de retry.
Client vs serveur : où placer la logique
La règle d'or : la clé API secrète reste sur le serveur. Le front ne fait qu'afficher un bouton et rediriger vers l'URL renvoyée par votre backend.
| Étape | Côté client | Côté serveur |
|---|---|---|
| Clé secrète | Jamais exposée | Stockée en variable d'env |
| Création session | Non | Oui (POST /checkout/sessions) |
| Redirection paiement | Oui (window.location) | URL générée côté serveur |
| Vérification statut | Non fiable | Oui (webhook + GET statut) |
| Marquage commande payée | Non | Oui (après webhook signé) |
| Remboursement | Non | Oui (API refund) |
Le front reçoit uniquement wave_launch_url. Toute décision de paiement se prend après réception du webhook côté serveur.
Paramètres techniques Wave 2026 à intégrer
| Paramètre | Valeur (ordre de grandeur 2026) |
|---|---|
| Frais marchand | ~1 % par transaction |
| Plafond par transaction | 1 000 000 FCFA |
| Délai de settlement | T+1 (jour ouvré) |
| Timeout webhook | 30 secondes |
| Tentatives de retry | 3 (backoff progressif) |
| Devise | XOF (FCFA) |
| Signature webhook | HMAC-SHA256 |
À la réception du webhook, recalculez la signature HMAC-SHA256 du corps brut avec votre secret, puis comparez en temps constant à l'en-tête Wave-Signature. Si elles diffèrent, répondez 401 et n'actionnez rien : c'est votre première ligne de défense contre les faux callbacks.
Flux d'intégration recommandé
- Le client valide son panier ; votre serveur appelle
POST /v1/checkout/sessionsavec le montant en FCFA et unesuccess_url. - Wave renvoie
wave_launch_urlet unidde session ; vous stockez l'idavec la commande en statutpending. - Le client paie ; Wave envoie un webhook
checkout.session.completedsigné. - Vous vérifiez la signature, passez la commande en
paid, répondez 200 sous 30 s. - En cas de doute, appelez
GET /v1/checkout/sessions/{id}pour reconfirmer le statut (source de vérité).
Mini cas pratique
Awa, gérante d'une boutique de cosmétiques à Bamako, encaisse 180 commandes par mois à 12 500 FCFA en moyenne, soit 2 250 000 FCFA. À 1 % de frais Wave, elle paie 22 500 FCFA de commissions mensuelles. Avec un settlement T+1, sa trésorerie est disponible dès le lendemain ouvré, contre 3 à 4 jours avec certains agrégateurs internationaux. Sur l'année, ses frais Wave s'élèvent à environ 270 000 FCFA pour 27 000 000 FCFA encaissés.
Besoin d'un site web professionnel ?
Kolonell crée des sites web qui attirent des clients, optimisés pour le marché sénégalais. Devis gratuit en 2 minutes.
FAQ
Puis-je appeler l'API Wave directement depuis React ?
Non. La clé secrète serait exposée dans le bundle. Créez la session côté serveur (Node, PHP, Python) et ne renvoyez que l'URL de lancement au navigateur.
Que se passe-t-il si mon webhook ne répond pas sous 30 secondes ?
Wave considère la livraison échouée et retente jusqu'à 3 fois avec un backoff. Répondez 200 immédiatement, puis traitez la logique lourde en tâche de fond.
Quel est le plafond par transaction ?
L'ordre de grandeur 2026 est de 1 000 000 FCFA par transaction. Pour un panier supérieur, fractionnez ou passez par un flux de facturation dédié.
Comment éviter de valider une commande sur un faux webhook ?
Vérifiez systématiquement la signature HMAC-SHA256 et, en cas de doute, reconfirmez via GET sur la session. Ne faites jamais confiance au seul callback côté client.
En combien de temps l'argent arrive-t-il sur mon compte ?
Le settlement est T+1 : les fonds encaissés un jour ouvré sont disponibles le lendemain ouvré.
Discutons de votre projet. Nous intégrons l'API Wave côté serveur, webhooks signés et tests inclus, pour votre boutique à Bamako. WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionné par le digital et l'entrepreneuriat en Afrique, Mohamed accompagne les entreprises sénégalaises dans leur transformation digitale depuis 2020. Fondateur de Kolonell, il croit que chaque PME mérite une présence en ligne professionnelle et accessible.
