Le verdict en trois phrases
Integrer Wave a un checkout Next.js, ce n'est pas afficher un bouton : c'est creer une session cote serveur, rediriger, puis verifier le statut avant tout fulfillment. La regle d'or 2026 : ne jamais faire confiance au retour navigateur, toujours confirmer via un GET status avec votre cle secrete. Une session expire en 30 minutes, le montant minimum est de 100 FCFA, et sans verification serveur vous livrez des commandes non payees.
Le flux Wave de bout en bout
Le cycle est simple mais chaque etape a un piege. Vous appelez l'API depuis une route serveur (jamais depuis le client, votre cle secrete 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.
| Etape | Cote | Endpoint / action | Piege a eviter |
|---|---|---|---|
| 1. Creer la session | Serveur | POST /v1/checkout/sessions | Cle secrete 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 apres 30 min |
| 4. Retour navigateur | Client | success_url / error_url | Ne PAS livrer sur ce seul retour |
| 5. Verifier le statut | Serveur | GET /v1/checkout/sessions/{id} | Livrer uniquement si status = complete |
| 6. Webhook (backup) | Serveur | POST /votre-webhook | Verifier la signature |
Le point critique est l'etape 5. Le retour navigateur peut etre falsifie ou interrompu (le client ferme l'onglet). La seule source de verite est l'appel serveur qui interroge Wave avec votre cle secrete.
Endpoints, montants et codes d'erreur 2026
Voici les parametres concrets a connaitre avant de coder, en ordre de grandeur 2026.
| Element | Valeur 2026 | Note |
|---|---|---|
| Montant minimum | 100 FCFA | Rejet en dessous |
| Devise | XOF | Entier, pas de decimales |
| Expiration session | 30 minutes | Statut passe a expired |
| Statut a attendre | complete | Avant fulfillment |
| Erreur 401 | Cle invalide | Verifiez Authorization: Bearer |
| Erreur 422 | Montant/devise invalide | Montant en entier XOF |
| Erreur 404 | Session inconnue | id errone ou expire purge |
| Frais encaissement | ~1 % ordre de grandeur | A confirmer selon contrat |
Cote code, votre route de verification ressemble a 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'etat en base et vous rendez l'operation idempotente : un fulfillment deja effectue ne doit jamais se rejouer.
Mini cas pratique
Awa, gerante d'une boutique de cosmetiques a Dakar, vend un panier moyen de 18 000 FCFA. Sur 300 commandes par mois, elle recevait 12 litiges "j'ai paye mais rien recu". En analysant, on decouvre que son ancien systeme livrait sur le retour navigateur : quand la 4G coupait apres le paiement, la commande partait quand meme, parfois sans paiement reel. Apres passage a la verification serveur (GET status obligatoire avant fulfillment), les litiges tombent a 1 par mois. Sur un panier de 18 000 FCFA, eviter ne serait-ce que 8 fulfillments non payes par mois represente 144 000 FCFA de marchandise sauvee 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. Passe ce delai, 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 creee sous ce seuil est rejetee avec une erreur 422. Le montant s'exprime en entier XOF, sans decimales.
Puis-je livrer la commande sur le simple retour navigateur ?
Non, jamais. Le retour success_url peut etre interrompu ou falsifie. Faites toujours un GET sur la session avec votre cle secrete et ne livrez que si le statut est complete.
Combien de temps prend une integration Wave Next.js propre ?
En ordre de grandeur 2026, comptez 3 a 5 jours pour un checkout robuste avec verification serveur, gestion des erreurs et webhook de secours. Un prototype sans garde-fous se fait en une journee mais ne doit pas aller en production.
Le webhook remplace-t-il la verification GET ?
Non, ils se completent. Le GET status confirme au moment du retour client, le webhook rattrape les cas ou le client a ferme l'onglet. Les deux doivent etre idempotents.
Discutons de votre projet. On integre Wave a votre checkout Next.js avec verification 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.
