Choisir une intégration

Les quatre façons d'encaisser un paiement, comparées sur le contrôle, le code et les contraintes.

Chaque paiement commence de la même façon, avec POST /payments. Ce qui distingue les quatre modes d'intégration, c'est qui affiche l'écran où le client confirme, et si l'appel de débit est à votre charge ou à la nôtre.

Choisissez sur ce seul critère. Les opérateurs que vous atteignez, les webhooks que vous recevez et les remboursements que vous pouvez émettre sont identiques pour les quatre : rien de ce que vous choisissez ici ne limite ce que vous pourrez faire plus tard.

La décision en un tableau

Mode	Qui affiche l'écran de paiement	Ce que vous écrivez	Idéal pour
Checkout hébergé	Wajub, sur sa propre page	Une redirection et un handler de retour	Aller vite en production, sur n'importe quelle stack
Composants intégrés	Wajub, dans votre page	Une route serveur plus le SDK navigateur	Rester sur votre domaine, avec votre marque
Liens de paiement	Wajub, sur sa propre page	Rien	Vendre sans site ni serveur
API directe	Vous	Toute l'interface de paiement	Applications natives et parcours sur mesure

Ce que vous renvoie la réponse de création

Créer un paiement ne débite personne. L'appel enregistre l'intention, la garde en pending et répond avec deux champs. Celui que vous utilisez dépend de votre mode d'intégration.

authorization_urlstringfacultatif

**Checkout hébergé.** L'URL complète de la page de paiement hébergée par Wajub. Redirigez-y votre client. C'est une URL de session opaque : ne l'analysez jamais et n'en construisez jamais une vous-même.

authorization_tokenstringfacultatif

**Composants intégrés.** Un jeton de session à usage unique, utilisable dans le navigateur et limité à ce paiement. Passez-le en sessionId à wajub.mount(). Il n'est renvoyé qu'à la création, jamais lors d'une récupération ultérieure.

Dans le code, toute la différence entre les deux modes tient en une ligne :

Le champ utilisé par chaque mode

// Hosted Checkout: send the customer to the page Wajub renders.
res.redirect(payment.authorization_url);

// Embedded Components: hand the token to the browser and mount in place.
wajub.mount('#checkout', { sessionId: payment.authorization_token });

L'API directe n'utilise ni l'un ni l'autre. Elle fait un second appel à la place, détaillé plus bas.

Checkout hébergé

Votre serveur crée le paiement et redirige vers authorization_url. Le client choisit un opérateur, saisit son numéro et confirme sur son téléphone, puis revient sur votre callback. Wajub envoie le webhook en parallèle : le résultat vous parvient même si le client ferme l'onglet en revenant.

Vous écrivez deux choses : la route qui crée le paiement, et le handler qui le vérifie avant de livrer la commande. Tout ce que voit le client, la liste des opérateurs, la nouvelle tentative quand une demande de confirmation expire, la formulation de chaque échec, appartient à Wajub et reste à jour sans que vous y touchiez.

La page affiche votre logo et vos couleurs grâce à l'objet theming de l'appel de création. C'est le mode que nous recommandons, et celui que parcourt le Démarrage rapide Paiements.

Composants intégrés

Le même checkout, monté dans votre propre mise en page. Votre serveur crée le paiement et transmet authorization_token au navigateur, qui appelle wajub.mount() avec ce jeton en sessionId. Le client ne quitte jamais votre domaine.

Vous écrivez une route serveur et quelques lignes de code front-end. Ce que vous n'écrivez pas, c'est l'interface de paiement elle-même : Mobile Money, cartes, OTP et 3DS viennent tous du composant monté, et vous fournissez l'habillage autour.

Il existe un package JavaScript vanilla et des wrappers React, Vue et Svelte. Commencez par le démarrage rapide des composants, puis la page du framework qui correspond à votre stack.

Liens de paiement

Un lien à partager, sous forme d'URL ou de QR code. Vous le créez depuis le Dashboard ou avec un seul appel API, vous l'envoyez par WhatsApp, SMS ou e-mail, et le client paie sur une page Wajub. Il n'y a de code serveur à aucun moment.

Deux limites sont à connaître avant de construire autour. Les liens de paiement fonctionnent en production uniquement, la sandbox n'a pas d'équivalent, et l'offre gratuite autorise 25 liens. Consultez Liens de paiement pour savoir ce qu'un lien peut porter et comment suivre ce qu'il encaisse.

API directe

Vous collectez vous-même le numéro de téléphone ou la carte, puis vous débitez avec un second appel, POST /payments/{id}, en passant un channel comme cm.mtn et les détails du paiement. La demande de confirmation de l'opérateur part vers le téléphone du client, et vous affichez chaque écran autour, y compris l'attente et le résultat.

C'est le seul mode où l'interface de paiement vous appartient entièrement, c'est pourquoi il existe pour les applications mobiles natives et pour les parcours qu'aucune page hébergée ne peut exprimer. C'est aussi le seul mode où c'est à vous de repérer les erreurs.

L'API directe a sa place sur votre serveur, jamais dans un navigateur

Une requête portant un en-tête Origin ou Referer avec une clé sk.… est rejetée avec un 403, et le propriétaire de la clé reçoit un e-mail. Le code front-end utilise la clé publique ou le jeton de session de la réponse de création. Si votre interface de paiement vit dans un navigateur, ce sont les Composants intégrés qu'il vous faut, pas ce mode.

Toujours indécis

Commencez par le Checkout hébergé. C'est le chemin le plus court vers un paiement qui fonctionne, et passer plus tard aux Composants intégrés ne change que votre front-end : l'appel de création, le traitement des webhooks et la vérification restent exactement tels quels.

Optez plutôt pour les liens de paiement si vous n'avez pas de site où intégrer, et pour l'API directe seulement après avoir étudié les Composants intégrés et trouvé quelque chose qu'ils ne peuvent vraiment pas afficher.

Pages associées