Démarrage rapide

Ce guide vous emmène d'un compte vide à un paiement vérifié, avec un webhook qui fonctionne. Il vous faut un compte Wajub (gratuit) et quelques minutes.

1. Créez votre compte et récupérez vos clés

Créez un compte sur le Dashboard. Un nouveau compte ne possède aucune clé : une fois connecté, ouvrez Settings → Developer → API Keys et créez une clé privée pendant que le Dashboard affiche la sandbox. Elle commence par sk_test.….

Les clés de production ne deviennent disponibles qu'une fois votre compte vérifié, et les clés restreintes rk sont présentées dans Environnements et API keys.

Tout ce guide s'exécute sur votre serveur, il utilise donc partout la clé privée sandbox. La clé publique existe pour le seul cas où du code s'exécute dans un navigateur : initialiser un paiement depuis la page elle-même. N'utilisez jamais une clé privée depuis un navigateur : lorsque Wajub en détecte une, il refuse la requête et vous prévient par e-mail, pour qu'une clé divulguée ne passe pas inaperçue.

2. Installez le SDK de votre langage

Les SDKs enveloppent la même API HTTP avec des ressources typées, une Idempotency-Key sur chaque appel qui modifie des données, un délai d'expiration par requête et la vérification de signature des webhooks. Si vous préférez appeler l'API directement, chaque exemple ci-dessous a un onglet cURL.

npm install @wajub/node

Ruby, Java, C#, Kotlin, Flutter, React Native et Swift ont leurs propres SDKs et leurs propres guides. Consultez SDKs pour la liste complète et la référence de configuration.

3. Créez un paiement

Un paiement commence par une requête. Vous envoyez le montant, la devise, la personne qui paie et la page vers laquelle la renvoyer. Wajub crée le paiement, le garde en pending et répond avec une page hébergée où le client choisit son opérateur et confirme. Personne n'est encore débité.

Décrivez le payeur dans l'objet customer. L'API accepte aussi un email au premier niveau, et les deux aboutissent sur la même fiche client, mais l'objet est la structure qui évolue avec vous : il porte aussi name, phone, address et metadata.

curl https://api.wajub.com/payments \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "customer": { "email": "amina@example.com" },
    "callback": "https://shop.example.com/order/complete"
  }'

Wajub répond 201 Created avec le paiement, son id et la page vers laquelle envoyer le client :

Enregistrez transaction.id avec votre commande, puis redirigez le client vers authorization_url.

4. Payez avec un numéro sandbox

Ouvrez authorization_url dans votre navigateur. En mode test, la page de paiement accepte de faux numéros Mobile Money dont les 6 derniers chiffres décident du résultat. Les mêmes suffixes fonctionnent pour tous les opérateurs et tous les pays :

Choisissez un numéro pour l'opérateur que vous voulez tester :

Pays et opérateur	Préfixe	Exemple, succès
Cameroun, MTNCameroun / MTN	+23767	+237670000000
Cameroun, OrangeCameroun / Orange	+23769	+237690000000
Côte d'Ivoire, MTNCôte d'Ivoire / MTN	+22505	+225050000000
Côte d'Ivoire, OrangeCôte d'Ivoire / Orange	+22507	+225070000000
Côte d'Ivoire, WaveCôte d'Ivoire / Wave	+22503	+225030000000
Sénégal, OrangeSénégal / Orange	+22177	+221770000000
Ghana, MTNGhana / MTN	+23324	+233240000000
Nigeria, MTNNigeria / MTN	+2348	+2348000000000
Kenya, M-PesaKenya / M-Pesa	+25470	+254700000000
Ouganda, MTNOuganda / MTN	+25677	+256770000000

La page de paiement sandbox ne demande aucun code PIN : le numéro de test décide seul du résultat.

5. Vérifiez le paiement côté serveur

Le client revient sur votre URL de callback, et ce retour ne prouve rien. N'importe qui peut ouvrir cette URL à la main, et un client qui ferme l'onglet ne l'ouvre jamais. Avant de livrer une commande, demandez à l'API ce qui s'est réellement passé, depuis votre serveur, avec l'id enregistré à l'étape 3.

curl https://api.wajub.com/payments/trx_test_CSUGajfv9xh0XQ5wu2lx \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…"

La réponse contient le paiement tel que Wajub le connaît, quoi qu'ait affiché votre navigateur :

Ne livrez la commande que lorsque status vaut succeeded, et seulement après avoir vérifié que amount et currency correspondent à ce que vous avez facturé. Un paiement encore en pending n'est pas un échec : c'est un client qui n'a pas encore terminé. Laissez donc la commande ouverte, et laissez le webhook de l'étape 6 vous prévenir quand le paiement aboutit.

6. Configurez un endpoint de webhook

Interroger l'API après chaque redirection ne couvre que les clients qui reviennent. Les webhooks couvrent le reste : un paiement confirmé dix minutes plus tard côté opérateur, un remboursement émis depuis le Dashboard, un litige ouvert par le client. Configurez-en un maintenant, avant de construire quoi que ce soit par-dessus.

Enregistrez l'endpoint

Dans Konsole → Webhooks → Endpoints (ou Settings → Developer → Webhooks dans le Dashboard) :

1. Cliquez sur Add Endpoint.
2. Saisissez votre URL publique, par exemple https://yourapp.com/webhooks/wajub.
3. Sélectionnez les événements à recevoir. Commencez par tous les événements de paiement, avec Select all à côté d'eux. Un abonnement ne reconnaît que des noms exacts : saisir payment.* ne recevrait rien.
4. Enregistrez, puis copiez le Signing Secret (whsec_…) dans votre environnement sous le nom WAJUB_WEBHOOK_SECRET.

Donnez le secret de signature au SDK

Le client que vous avez créé à l'étape 3 vérifie aussi les webhooks, dès qu'il connaît le secret de signature. Ajoutez-le au même constructeur, à côté de votre API key :

import { Wajub } from '@wajub/node';

export const wajub = new Wajub({
  apiKey: process.env.WAJUB_API_KEY,
  webhookSecret: process.env.WAJUB_WEBHOOK_SECRET,
});

Écrivez l'endpoint

Quatre règles rendent un endpoint de webhook correct, et le SDK ne gère que la première à votre place.

Vérifiez la signature, dans tous les environnements. Un endpoint qui saute la vérification accepte tout ce que n'importe qui lui envoie, y compris un faux payment.succeeded. constructEvent recalcule le HMAC sur X-Wajub-Timestamp et le corps brut, le compare à X-Wajub-Signature, rejette tout ce qui date de plus de cinq minutes, et seulement ensuite analyse le JSON. Il lui faut le corps brut : désactivez donc l'analyse du corps JSON sur cette route.

Accusez réception avant de travailler. Wajub attend votre 2xx pendant 10 secondes. Au-delà, la livraison compte comme échouée et fait l'objet d'une nouvelle tentative : répondez d'abord, et faites le travail lent ensuite, dans une file d'attente ou une goroutine.

Dédupliquez sur l'id de livraison. Une livraison échouée est retentée avec une attente progressive, pendant 72 heures au plus, et chaque tentative porte le même X-Wajub-Delivery-Id. C'est cet id qui empêche une nouvelle tentative de livrer deux fois la même commande.

Traitez ensuite l'événement. Le type se trouve dans event.event, et event.data contient l'objet concerné par l'événement, avec la même forme que celle renvoyée par l'API. Pour payment.succeeded, event.data.id est l'id du paiement enregistré à l'étape 3.

app.post('/webhooks/wajub', express.raw({ type: '*/*' }), async (req, res) => {
  const event = wajub.webhooks.constructEvent(
    req.body,
    req.headers['x-wajub-signature'],
    req.headers['x-wajub-timestamp'],
  );

  res.sendStatus(200);

  const deliveryId = req.headers['x-wajub-delivery-id'];

  if (await alreadyHandled(deliveryId)) return;

  await markHandled(deliveryId);

  if (event.event === 'payment.succeeded') {
    await fulfillOrder(event.data.id);
  }
});

Recevez les événements sur votre machine

Pas besoin d'URL publique, de déploiement ni d'endpoint enregistré pour commencer. La CLI ouvre une connexion sortante vers Wajub et envoie chaque événement sandbox à une adresse locale :

npm install -g @wajub/cli
wajub listen --forward-to http://localhost:3000/webhooks/wajub

Rien sur votre machine n'est exposé à Internet. wajub listen affiche le secret de signature des événements transférés : c'est ce secret que doit contenir votre WAJUB_WEBHOOK_SECRET local pendant que vous développez. Il reste le même d'une exécution à l'autre : placez-le une seule fois (wajub listen --print-secret l'affiche seul). Ce n'est pas le secret d'un endpoint enregistré : chaque endpoint garde le sien. Consultez la commande CLI listen pour toutes les options.

Et maintenant ?