Intégrer Wave Business API au Sénégal — Guide complet 2025

Wave est devenu incontournable pour les entreprises sénégalaises : avec plus de 7 millions d'utilisateurs actifs au Sénégal, ne pas accepter Wave c'est se priver d'une grande partie de ses clients potentiels. Ce guide vous explique comment intégrer l'API Wave dans votre projet.

Comprendre le fonctionnement de l'API Wave

Wave propose une API basée sur des sessions de paiement (Checkout Sessions). Le flux est le suivant : votre serveur crée une session, Wave retourne un lien (wave_launch_url) que vous affichez à votre client. Le client confirme le paiement sur son téléphone, puis Wave notifie votre serveur via un webhook.

Votre serveur appelle POST /v1/checkout/sessions avec le montant et vos URLs de callback
Wave retourne un wave_launch_url (lien de paiement)
Vous affichez le lien ou le QR code à votre client
Le client ouvre son app Wave et confirme
Wave envoie un webhook POST à votre callback_url
Vous validez la signature et mettez à jour la commande

Prérequis : créer un compte Wave Business

Pour accéder à l'API Wave Business, vous devez créer un compte professionnel sur business.wave.com. Après validation, vous recevrez une clé API (Bearer token) depuis le portail développeur. Paydeck vous évite cette démarche en fournissant un accès unifié : vous utilisez votre clé Paydeck et nous gérons l'authentification Wave en coulisse.

Intégration avec le SDK Paydeck (recommandé)

La façon la plus simple d'intégrer Wave est d'utiliser le SDK Paydeck, qui abstrait les détails de l'API Wave et vous donne une interface unifiée pour tous vos providers.

bash

npm install @paydeck/node

javascript

const Paydeck = require('@paydeck/node')

const client = new Paydeck({
  apiKey: 'sk_live_votre_cle_api',
})

// Créer une session de paiement Wave
const payment = await client.payments.collect({
  amount: 5000,        // en FCFA
  currency: 'XOF',
  provider: 'wave_sn',
  reference: 'commande_12345',
  callbackUrl: 'https://monapp.sn/webhook/paydeck',
  successUrl: 'https://monapp.sn/paiement-reussi',
  cancelUrl: 'https://monapp.sn/paiement-annule',
})

// Rediriger vers Wave
console.log(payment.paymentUrl) // → https://pay.wave.com/m/...

Gérer le webhook de confirmation

Le webhook est la partie critique de l'intégration : c'est lui qui confirme que le paiement a bien été effectué. Paydeck signe chaque webhook avec HMAC-SHA256. Vérifiez toujours la signature avant de valider une commande.

javascript

// Express.js — endpoint de webhook
app.post('/webhook/paydeck', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-paydeck-signature']
  const isValid = client.webhooks.verify(req.body, signature)

  if (!isValid) return res.status(400).send('Signature invalide')

  const event = JSON.parse(req.body)

  if (event.type === 'payment.success') {
    const { reference, amount, provider } = event.data
    // ✅ Valider la commande reference dans votre base de données
    await db.orders.update({ ref: reference, status: 'paid' })
  }

  res.json({ received: true })
})

Intégration directe via l'API REST

Si vous préférez ne pas utiliser le SDK, vous pouvez appeler l'API Paydeck directement via HTTP depuis n'importe quel langage.

bash

curl -X POST https://api.getpaydeck.com/api/v1/payments/collect \
  -H "Authorization: Bearer sk_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "providerCode": "wave_sn",
    "reference": "commande_12345",
    "callbackUrl": "https://monapp.sn/webhook"
  }'

💡 Conseil : En mode sandbox (clé sk_test_), aucun vrai paiement n'est effectué. Utilisez le dashboard Paydeck pour simuler un succès ou un échec et tester votre webhook.

Afficher le QR code Wave

Pour les points de vente physiques ou les sites desktop, afficher un QR code Wave est une meilleure UX que de rediriger vers un lien. Paydeck peut générer le QR code directement. Passez le paramètre displayMode: 'qr' dans votre requête.

Bonnes pratiques

Toujours vérifier la signature HMAC du webhook avant de valider une commande
Rendre le handler de webhook idempotent (même résultat si reçu plusieurs fois)
Stocker le payment_ref Paydeck dans votre base pour les réconciliations
Prévoir un état 'en attente' côté commande avant la confirmation webhook
Tester les cas d'échec en sandbox avant de passer en production

Paydeck gère automatiquement les retries webhook en cas d'échec temporaire de votre serveur. Vous pouvez aussi déclencher un retry manuellement depuis votre dashboard.

Comment intégrer l'API Wave Business dans votre site web ou application