Le verdict en trois phrases
L'API Wave Côte d'Ivoire repose sur un endpoint checkout qui crée une session de paiement et un webhook de confirmation que vous devez signer, vérifier et rendre idempotent. Sans idempotence ni file de rejeu, un simple HTTP 500 de votre serveur fait perdre l'événement et laisse la commande en attente. Ce guide détaille l'intégration complète, du passage sandbox vers production au retry exponentiel sur 3 tentatives en 24 heures.
Anatomie de l'intégration 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 numéro de commande). Wave renvoie une wave_launch_url vers laquelle rediriger le client. Une fois le paiement effectué, Wave notifie votre serveur via un webhook checkout.session.completed.
Le point critique : chaque webhook porte un en-tête de signature (Wave-Signature) que vous devez recalculer avec votre clé secrète webhook avant de faire confiance à l'événement. Ne livrez jamais une commande sur la seule base d'un retour navigateur.
| Élément technique | Valeur Wave CI 2026 (ordre de grandeur) |
|---|---|
| Endpoint checkout | POST /v1/checkout/sessions |
| Devise | XOF (FCFA) |
| Événement webhook clé | checkout.session.completed |
| Signature | HMAC via en-tête Wave-Signature |
| Délai réponse attendu | HTTP 200 sous 5 secondes |
| Rejeu si échec | oui, backoff sur ~24 h |
| Frais marchand indicatifs | 1 % du montant encaissé |
Côté 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 représente 250 FCFA de frais.
Idempotence, signature et retry
La règle d'or : votre endpoint webhook doit pouvoir recevoir deux fois le même événement sans créer deux commandes. Stockez l'event_id reçu ; si vous l'avez déjà traité, répondez 200 OK immédiatement sans rejouer la logique métier.
Pour la robustesse, distinguez le webhook entrant (que Wave rejoué) de votre propre file de traitement. Si votre base est indisponible, répondez 500 volontairement : Wave rejouera. Comparons Wave CI et Paystack Nigeria, deux approches signées mais différentes.
| Critère | Wave CI | Paystack Nigeria |
|---|---|---|
| Algorithme signature | HMAC (Wave-Signature) | HMAC-SHA512 |
| En-tête à vérifier | Wave-Signature | x-paystack-signature |
| Événement de succès | checkout.session.completed | charge.success |
| Devise | XOF | NGN |
| Politique de rejeu | backoff ~24 h | jusqu'à 72 h |
| Clés 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 côté traitement : tentative 1 immédiate, tentative 2 après 30 minutes, tentative 3 après plusieurs heures, avec abandon et alerte au-delà de 24 heures.
Mini cas pratique
Kouadio gère une boutique de sneakers à Abidjan (Cocody). Avant intégration propre, il livrait sur retour navigateur : 4 % de ses 300 commandes mensuelles restaient "en attente" faute de confirmation fiable, soit 12 commandes bloquées. Après mise en place du webhook signé + idempotence + retry sur 24 h, le taux de commandes non confirmées tombe à 0,3 %, soit moins d'une commande par mois. Sur un panier moyen de 45 000 FCFA, il récupère environ 11 x 45 000 = 495 000 FCFA de chiffre d'affaires auparavant fantôme chaque mois, pour un coût d'intégration unique de l'ordre de 350 000 FCFA amorti en trois semaines.
FAQ
Faut-il obligatoirement vérifier la signature du webhook Wave ? Oui, sans exception. Un attaquant pourrait forger un faux checkout.session.completed. La vérification HMAC avec votre clé secrète garantit que l'événement vient bien de Wave.
Que faire si mon serveur renvoie un HTTP 500 pendant la maintenance ? Rien de grave : Wave considère l'échec et rejoue l'événement selon son backoff (~24 h). C'est justement pour cela que l'idempotence est indispensable avant tout rejeu.
Comment passer de la sandbox à la production ? Vous remplacez vos clés sk_test par sk_live, mettez à jour l'URL de webhook en production (HTTPS obligatoire) et rejouez au moins un scénario réel de 100 FCFA avant d'ouvrir aux clients.
Le polling de statut est-il utile si le webhook fonctionne ? Oui, en filet de sécurité. Un cron qui interroge les sessions restées "pending" toutes les 15 minutes rattrape les rares webhooks perdus sur réseau instable.
Combien coûte réellement l'intégration ? Pour une boutique standard, comptez un ordre de grandeur de 300 000 à 600 000 FCFA selon la complexité, hors frais Wave de ~1 % par transaction.
Discutons de votre projet. Nous intégrons Wave, Orange Money et Paystack avec webhooks signés, idempotence et retry testés 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.
