Le verdict en trois phrases
Intégrer Wave Collect au checkout d'un site marchand à Abidjan repose sur une session de paiement, une redirection utilisateur, puis un webhook signé qui confirme l'encaissement. La règle d'or : ne jamais valider une commande depuis le navigateur, seulement depuis le webhook idempotent côté serveur. Sans idempotence, entre 3 et 5 % des commandes se dédoublent lors des retries réseau, ce qui pollue la comptabilité et le stock.
Le flux d'intégration bout-en-bout
Le parcours technique se découpe en cinq étapes. Le front crée une intention, le back appelle l'API Wave pour ouvrir une session de checkout, l'utilisateur paie sur la page hébergée, Wave redirige vers votre success_url, et surtout Wave appelle votre webhook pour confirmer. La confirmation d'affaires (marquer la commande payée) doit venir uniquement du webhook.
Côté frais et délais, l'ordre de grandeur 2026 place la collecte Wave autour de 1 % et un settlement (versement sur votre compte) en J+1. Pour un marchand anglophone, l'équivalent Paystack tourne autour de 1,5 % avec settlement T+1. La comparaison guide le choix selon le marché ciblé.
| Provider | Frais collecte | Settlement | Signature webhook | Retry webhook |
|---|---|---|---|---|
| Wave Collect (CI/SN) | ~1 % | J+1 | HMAC-SHA256 | x3 |
| Paystack (NG/GH) | ~1,5 % | T+1 | x-paystack-signature | x5 (24h) |
| Orange Money (SN/CI) | ~1,5 % | J+2 | Token + IP allowlist | x3 |
| Stripe (international) | 2,9 % + 250 FCFA | J+2 à J+7 | Stripe-Signature | x auto |
Endpoints et codes erreur à gérer
Le cœur de l'intégration Wave est l'endpoint POST /v1/checkout/sessions qui retourne une wave_launch_url. Le timeout recommandé côté serveur est de 30 secondes ; au-delà, relancez ou affichez un état « en attente ». Le webhook arrive avec un header de signature à vérifier en HMAC-SHA256 sur le corps brut de la requête, jamais sur le JSON re-sérialisé.
| Endpoint / événement | Rôle | Code / statut | Action recommandée |
|---|---|---|---|
| POST /checkout/sessions | Créer la session | 201 created | Stocker session_id + reference |
| GET /checkout/sessions/:id | Vérifier l'état | 200 / succeeded | Confirmer si webhook manquant |
| webhook checkout.session.completed | Paiement confirmé | 200 renvoyé par vous | Marquer commande payée (idempotent) |
| erreur signature | Sécurité | 401 côté vous | Rejeter, logguer, alerter |
| session expirée | Timeout 30s+ | expired | Réafficher le panier |
| erreur solde | Refus wallet | payment_failed | Proposer un autre wallet |
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.
Mini cas pratique
Kouassi, développeur d'une boutique de sneakers à Abidjan (Cocody), traitait 600 commandes par mois. Avant idempotence, environ 4 % soit 24 commandes partaient en double lors des coupures réseau 4G, générant des remboursements manuels d'environ 15 000 FCFA chacun de charge de traitement. En ajoutant une clé unique reference avec déduplication à TTL 24h et une validation exclusivement par webhook, les doublons sont tombés à 0. Économie estimée : 360 000 FCFA/mois de temps et remboursements évités, pour une intégration livrée en 4 jours.
FAQ
Faut-il valider la commande depuis la page de succès ? Non. La success_url sert seulement à afficher un message. La validation métier (stock, facture, e-mail) doit venir du webhook serveur, seule source fiable, car un client peut fermer l'onglet avant la redirection.
Comment éviter les doubles paiements ? Générez une reference unique par commande et stockez chaque webhook traité avec un TTL de 24h. Si la même référence revient, renvoyez 200 sans re-traiter. Cela neutralise les 3 à 5 % de doublons observés sur les retries.
Quel timeout configurer côté serveur ? 30 secondes pour l'appel de création de session. Si Wave ne répond pas, affichez un état « en attente » et laissez le webhook trancher plutôt que de forcer une seconde tentative immédiate.
Wave ou Paystack pour un site multi-pays ? Wave à ~1 % avec settlement J+1 est optimal pour la zone UEMOA (Sénégal, Côte d'Ivoire). Paystack à ~1,5 % couvre mieux le Nigeria et le Ghana. Beaucoup de marchands câblent les deux via un module unifié.
Comment tester sans argent réel ? Utilisez l'environnement sandbox du provider et simulez les webhooks avec des payloads signés localement. Testez explicitement le cas du webhook reçu deux fois pour valider l'idempotence.
Discutons de votre projet. Nous intégrons Wave, Orange Money et Paystack à votre checkout avec webhooks signés et idempotents, testés bout-en-bout. 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.
