Wajub.js

Tous les checkouts Wajub reposent sur le package @wajub/js. Les packages React, Vue et Svelte l'enveloppent. Cette page présente uniquement le package principal : ce qu'il charge, ce qu'il exporte et les trois façons d'accéder à la même API.

Le package npm est un chargeur, pas l'environnement d'exécution

L'installation de @wajub/js n'ajoute pas le checkout à votre bundle. Ce petit chargeur récupère le véritable environnement d'exécution depuis https://js.wajub.com lors du premier appel.

Content Security Policy

Une page qui applique une Content-Security-Policy stricte doit autoriser les hôtes que le SDK charge, intègre et appelle. Sans eux, le navigateur bloque le runtime ou le cadre du checkout et signale la violation dans la console.

script-src https://js.wajub.com;
frame-src https://pay.wajub.com;
connect-src https://pay.wajub.com https://api.wajub.com;
img-src https://pay.wajub.com;

Si vous servez le checkout depuis votre propre domaine vérifié, utilisez cet hôte partout où pay.wajub.com apparaît. La page du checkout définit elle-même sa politique ; la vôtre ne régit que la page qui l'entoure.

Trois points d'entrée

Ils fournissent la même API. Seuls le moment du chargement de l'environnement d'exécution et la nécessité d'un bundler changent.

Installez le package avec votre gestionnaire habituel. Il est uniquement distribué comme module ES. Un appel CommonJS require() ne peut donc pas le résoudre.

npm install @wajub/js

Sans bundler, la balise script ajoute wajub, Wajub et WajubError à window. Le build .mjs utilise le même environnement d'exécution avec des exports nommés.

<script src="https://js.wajub.com"></script>

<!-- or, as a module -->
<script type="module">
  import { mount } from 'https://js.wajub.com/wajub.mjs';
</script>

Trois façons d'appeler la même API

Chaque méthode ci-dessous existe sous les trois formes. Choisissez-en une par projet et conservez-la. Leur mélange rend l'ordre de chargement difficile à comprendre.

Les helpers nommés constituent la solution la plus courte. Chacun charge et attend lui-même l'environnement d'exécution.

import { mount, open, checkout, fetchSession, confirmPayment } from '@wajub/js';

const instance = await mount('#checkout', { sessionId });

loadWajub() vous remet plutôt l'environnement d'exécution. Le chargement intervient donc au moment que vous choisissez. Il renvoie null en l'absence de window, ce qui sécurise le rendu serveur.

import { loadWajub } from '@wajub/js/pure';

const rt = await loadWajub();
if (rt) {
  const instance = await rt.wajub.mount('#checkout', { sessionId });
}

Depuis le CDN, les mêmes objets se trouvent sur window et rien ne doit être attendu.

const instance = await wajub.mount('#checkout', { sessionId });

Éléments exportés par le package

loadWajub() et les helpers qui reproduisent l'environnement d'exécution. wajub, Wajub et WajubError ne sont pas exportés par le module, même si les types déclarent WajubError : prenez-les dans ce que renvoie loadWajub().

Retenez surtout preload() : appelez cette fonction lorsque le client atteint le panier afin que l'environnement d'exécution se trouve déjà en cache au moment du paiement.

Le client Wajub()

Les méthodes de l'environnement d'exécution nécessitent un sessionId à chaque appel. Le client le conserve plutôt une seule fois. Il constitue aussi le seul moyen de créer un paiement depuis le navigateur.

const client = Wajub('pk_test.xxxxxxxxxxxxxxxx…');

const client = Wajub.session(sessionId);

const client = Wajub({ publishableKey: 'pk_test.xxxxxxxxxxxxxxxx…', sessionId });

initCheckout couvre tout le flux sans backend. Il nécessite une clé publique, car la page définit le montant.

await Wajub('pk_test.xxxxxxxxxxxxxxxx…').initCheckout({
  mode: 'inline',
  container: '#checkout',
  payment: { amount: 35000, currency: 'XOF', customer: { email: '[email protected]' } },
  onSuccess: (transaction) => console.log('paid', transaction),
});

Sur le serveur

loadWajub() et chaque helper renvoient null en l'absence de window. Le rendu serveur ne génère donc jamais d'erreur. La différence concerne l'importation : @wajub/js charge le script comme effet de bord, tandis que @wajub/js/pure ne fait rien avant son appel.

import { loadWajub } from '@wajub/js/pure';

payButton.addEventListener('click', async () => {
  const rt = await loadWajub();
  await rt?.wajub.open({ sessionId });
});

Les trois packages de framework importent déjà /pure pour vous. Ce point est important lorsque vous intégrez vous-même le package principal.

Où chaque sujet est documenté

Cette page se limite au package. Chaque fonctionnalité de l'environnement d'exécution possède sa propre page.