Le verdict en trois phrases
Intégrer Wave à un checkout Next.js, ce n'est pas afficher un bouton : c'est créer une session côté serveur, rediriger, puis vérifier le statut avant tout fulfillment. La règle d'or 2026 : ne jamais faire confiance au retour navigateur, toujours confirmer via un GET status avec votre clé secrète. Une session expire en 30 minutes, le montant minimum est de 100 FCFA, et sans vérification serveur vous livrez des commandes non payées.
Le flux Wave de bout en bout
Le cycle est simple mais chaque étape a un piège. Vous appelez l'API depuis une route serveur (jamais depuis le client, votre clé secrète ne doit jamais partir dans le bundle), Wave renvoie une URL de paiement, vous redirigez, le client paie dans son app Wave, puis vous confirmez.
| Étape | Côté | Endpoint / action | Piège à éviter |
|---|---|---|---|
| 1. Créer la session | Serveur | POST /v1/checkout/sessions | Clé secrète dans une route API, jamais client |
| 2. Rediriger | Client | wave_launch_url | Stocker le session id en base avant redirect |
| 3. Client paie | App Wave | — | Session expire après 30 min |
| 4. Retour navigateur | Client | success_url / error_url | Ne PAS livrer sur ce seul retour |
| 5. Vérifier le statut | Serveur | GET /v1/checkout/sessions/{id} | Livrer uniquement si status = complete |
| 6. Webhook (backup) | Serveur | POST /votre-webhook | Vérifier la signature |
Le point critique est l'étape 5. Le retour navigateur peut être falsifié ou interrompu (le client ferme l'onglet). La seule source de vérité est l'appel serveur qui interroge Wave avec votre clé secrète.
Endpoints, montants et codes d'erreur 2026
Voici les paramètres concrets à connaître avant de coder, en ordre de grandeur 2026.
| Élément | Valeur 2026 | Note |
|---|---|---|
| Montant minimum | 100 FCFA | Rejet en dessous |
| Devise | XOF | Entier, pas de décimales |
| Expiration session | 30 minutes | Statut passe à expired |
| Statut à attendre | complète | Avant fulfillment |
| Erreur 401 | Clé invalide | Vérifiez Authorization: Bearer |
| Erreur 422 | Montant/devise invalide | Montant en entier XOF |
| Erreur 404 | Session inconnue | id erroné ou expiré purge |
| Frais encaissement | ~1 % ordre de grandeur | À confirmer selon contrat |
Côté code, votre route de vérification ressemble à ceci (pseudo-code) : const session = await fetch("https://api.wave.com/v1/checkout/sessions/" + id, { headers: { Authorization: "Bearer " + process.env.WAVE_SECRET } }); if (session.payment_status === "succeeded") { await fulfillOrder(orderId); }. Vous stockez l'état en base et vous rendez l'opération idempotente : un fulfillment déjà effectué ne doit jamais se rejouer.
Mini cas pratique
Awa, gérante d'une boutique de cosmétiques à Dakar, vend un panier moyen de 18 000 FCFA. Sur 300 commandes par mois, elle recevait 12 litiges "j'ai payé mais rien reçu". En analysant, on découvre que son ancien système livrait sur le retour navigateur : quand la 4G coupait après le paiement, la commande partait quand même, parfois sans paiement réel. Après passage à la vérification serveur (GET status obligatoire avant fulfillment), les litiges tombent à 1 par mois. Sur un panier de 18 000 FCFA, éviter ne serait-ce que 8 fulfillments non payés par mois représente 144 000 FCFA de marchandise sauvée chaque mois.
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
Combien de temps une session Wave reste-t-elle valide en 2026 ?
Environ 30 minutes. Passé ce délai, la session passe au statut expired et le client doit repartir d'un nouveau checkout. Stockez toujours le session id en base avec un horodatage.
Quel est le montant minimum encaissable via Wave ?
100 FCFA. Toute session créée sous ce seuil est rejetée avec une erreur 422. Le montant s'exprime en entier XOF, sans décimales.
Puis-je livrer la commande sur le simple retour navigateur ?
Non, jamais. Le retour success_url peut être interrompu ou falsifié. Faites toujours un GET sur la session avec votre clé secrète et ne livrez que si le statut est complete.
Combien de temps prend une intégration Wave Next.js propre ?
En ordre de grandeur 2026, comptez 3 à 5 jours pour un checkout robuste avec vérification serveur, gestion des erreurs et webhook de secours. Un prototype sans garde-fous se fait en une journée mais ne doit pas aller en production.
Le webhook remplace-t-il la vérification GET ?
Non, ils se complètent. Le GET status confirme au moment du retour client, le webhook rattrape les cas où le client a fermé l'onglet. Les deux doivent être idempotents.
Discutons de votre projet. On intègre Wave à votre checkout Next.js avec vérification serveur, webhooks et tests de recette. 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.
