Le verdict en trois phrases
L'API Wave Cote d'Ivoire repose sur un endpoint checkout qui cree une session de paiement et un webhook de confirmation que vous devez signer, verifier et rendre idempotent. Sans idempotence ni file de rejeu, un simple HTTP 500 de votre serveur fait perdre l'evenement et laisse la commande en attente. Ce guide detaille l'integration complete, du passage sandbox vers production au retry exponentiel sur 3 tentatives en 24 heures.
Anatomie de l'integration Wave CI
Wave Business expose une API REST simple : vous appelez POST /v1/checkout/sessions avec le montant, la devise XOF et une client_reference unique (votre numero de commande). Wave renvoie une wave_launch_url vers laquelle rediriger le client. Une fois le paiement effectue, Wave notifie votre serveur via un webhook checkout.session.completed.
Le point critique : chaque webhook porte un en-tete de signature (Wave-Signature) que vous devez recalculer avec votre cle secrete webhook avant de faire confiance a l'evenement. Ne livrez jamais une commande sur la seule base d'un retour navigateur.
| Element technique | Valeur Wave CI 2026 (ordre de grandeur) |
|---|---|
| Endpoint checkout | POST /v1/checkout/sessions |
| Devise | XOF (FCFA) |
| Evenement webhook cle | checkout.session.completed |
| Signature | HMAC via en-tete Wave-Signature |
| Delai reponse attendu | HTTP 200 sous 5 secondes |
| Rejeu si echec | oui, backoff sur ~24 h |
| Frais marchand indicatifs | 1 % du montant encaisse |
Cote frais, comptez un ordre de grandeur de 1 % par transaction pour un compte marchand Wave en 2026. Sur une commande de 25 000 FCFA, cela represente 250 FCFA de frais.
Idempotence, signature et retry
La regle d'or : votre endpoint webhook doit pouvoir recevoir deux fois le meme evenement sans creer deux commandes. Stockez l'event_id recu ; si vous l'avez deja traite, repondez 200 OK immediatement sans rejouer la logique metier.
Pour la robustesse, distinguez le webhook entrant (que Wave rejoue) de votre propre file de traitement. Si votre base est indisponible, repondez 500 volontairement : Wave rejouera. Comparons Wave CI et Paystack Nigeria, deux approches signees mais differentes.
| Critere | Wave CI | Paystack Nigeria |
|---|---|---|
| Algorithme signature | HMAC (Wave-Signature) | HMAC-SHA512 |
| En-tete a verifier | Wave-Signature | x-paystack-signature |
| Evenement de succes | checkout.session.completed | charge.success |
| Devise | XOF | NGN |
| Politique de rejeu | backoff ~24 h | jusqu'a 72 h |
| Cles test / live | sk_test / sk_live | sk_test / sk_live |
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.
Mettez en place un retry exponentiel cote traitement : tentative 1 immediate, tentative 2 apres 30 minutes, tentative 3 apres plusieurs heures, avec abandon et alerte au-dela de 24 heures.
Mini cas pratique
Kouadio gere une boutique de sneakers a Abidjan (Cocody). Avant integration propre, il livrait sur retour navigateur : 4 % de ses 300 commandes mensuelles restaient "en attente" faute de confirmation fiable, soit 12 commandes bloquees. Apres mise en place du webhook signe + idempotence + retry sur 24 h, le taux de commandes non confirmees tombe a 0,3 %, soit moins d'une commande par mois. Sur un panier moyen de 45 000 FCFA, il recupere environ 11 x 45 000 = 495 000 FCFA de chiffre d'affaires auparavant fantome chaque mois, pour un cout d'integration unique de l'ordre de 350 000 FCFA amorti en trois semaines.
FAQ
Faut-il obligatoirement verifier la signature du webhook Wave ? Oui, sans exception. Un attaquant pourrait forger un faux checkout.session.completed. La verification HMAC avec votre cle secrete garantit que l'evenement vient bien de Wave.
Que faire si mon serveur renvoie un HTTP 500 pendant la maintenance ? Rien de grave : Wave considere l'echec et rejoue l'evenement selon son backoff (~24 h). C'est justement pour cela que l'idempotence est indispensable avant tout rejeu.
Comment passer de la sandbox a la production ? Vous remplacez vos cles sk_test par sk_live, mettez a jour l'URL de webhook en production (HTTPS obligatoire) et rejouez au moins un scenario reel de 100 FCFA avant d'ouvrir aux clients.
Le polling de statut est-il utile si le webhook fonctionne ? Oui, en filet de securite. Un cron qui interroge les sessions restees "pending" toutes les 15 minutes rattrape les rares webhooks perdus sur reseau instable.
Combien coute reellement l'integration ? Pour une boutique standard, comptez un ordre de grandeur de 300 000 a 600 000 FCFA selon la complexite, hors frais Wave de ~1 % par transaction.
Discutons de votre projet. Nous integrons Wave, Orange Money et Paystack avec webhooks signes, idempotence et retry testes en production. 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.
