Champs de paiement

Les champs de paiement inversent le principe du checkout hébergé. Vous conservez la page, le récapitulatif de commande et le bouton de paiement. Wajub affiche dans des iframes séparées les champs qui ne doivent pas toucher à votre DOM. Vous les envoyez lorsque vous êtes prêt.

Ce compromis vous donne le contrôle de la mise en page, mais retire les parties de la page hébergée qui nécessitent une page complète : vos propres champs de checkout personnalisés. Si vous en avez besoin, utilisez plutôt le checkout hébergé.

Les étapes qu'un paiement peut ajouter après le premier envoi restent dans le composant : un code reçu par SMS (OTP), le code PIN d'un portefeuille, un numéro à confirmer, une date de naissance, une adresse, une validation sur le téléphone, un code USSD à composer et le 3D Secure. Vous n'avez rien à brancher pour elles, et confirmPayment() attend qu'elles soient terminées.

Les sept composants

Structure générale

Une fabrique conserve la session et les options partagées. Chaque appel create() crée un composant, puis mount() le place sur la page.

import { components, confirmPayment } from '@wajub/js';

const factory = await components(sessionId, {
  locale: 'fr',
  appearance: { primaryColor: '#2563eb', labels: 'floating' },
});

const card = factory
  .create('card')
  .on('change', (event) => (payButton.disabled = !event.complete))
  .mount('#card');

payButton.onclick = () => confirmPayment({ sessionId, components: card });

Les options transmises à la fabrique deviennent les valeurs par défaut de tous ses composants. Les options transmises à create() sont prioritaires pour le composant concerné.

Configuration

Les cinq lignes au-dessus de componentOrigin sont lues par l'environnement d'exécution servi depuis js.wajub.com, quelle que soit la version du paquet installé. @wajub/js 1.5.0 apporte leurs types. Avec un framework, React transmet toutes les options. @wajub/vue et @wajub/svelte transmettent fields, onBeforeSubmit depuis la 1.5.0, et variant depuis la 1.5.1.

componentOrigin utilise par défaut l'origine de la page qui effectue le montage. Un domaine unique ne nécessite donc aucune configuration.

factory
  .create('address', { addressMode: 'shipping', collectName: true, fields: { phone: 'auto' } })
  .mount('#address');

factory
  .create('payment', { collectAddress: 'shipping', collectName: true, layout: 'tabs' })
  .mount('#payment');

Événements

Abonnez-vous avec .on(event, handler), qui renvoie le composant et permet de chaîner les appels. Les mêmes handlers existent sous les noms onReady, onChange et autres dans ComponentConfig.

component.on('change', (event) => {
  payButton.disabled = !event.complete;
  errorLabel.textContent = event.error ? event.error.message : '';
});

Envoyer le paiement

confirmPayment reçoit la session et un composant monté, l'envoie et attend le résultat.

import type { WajubError } from '@wajub/js';

try {
  const { status, transaction } = await confirmPayment({ sessionId, components: card });
  showReceipt(status, transaction);
} catch (error) {
  // A caught value is `unknown` in strict mode: confirmPayment rejects with a WajubError.
  const { code, message } = error as WajubError;
  showRetry(code, message);
}

Trois rejets se produisent avant tout envoi. Ils signalent donc des erreurs d'intégration, pas des échecs de paiement.

Une fois l'envoi fait, c'est le paiement qui met fin à l'attente, ou le délai.

Un refus porte le code du prestataire, et un composant qui ne se charge pas rejette avec son erreur de chargement.

Avant que la commande existe

Un checkout affiche ses moyens de paiement avant que la commande soit passée : l'acheteur choisit encore une livraison, saisit un code promo, change de pays. Créez la session à ce moment-là avec deferred: true : le paiement est seulement préparé. Il reste hors de vos paiements et n'envoie aucun webhook tant que votre serveur ne l'a pas activé, une fois la commande passée. Un acheteur qui s'en va ne laisse aucune trace, tant que vous n'envoyez aucun client avant l'activation : un client envoyé à la préparation est créé, avec son customer.created.

curl https://api.wajub.com/payments \
-H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
-H "Content-Type: application/json" \
-d '{ "amount": 35000, "currency": "XOF", "deferred": true, "expires": { "in": 30 } }'

Aucun client n'est encore nécessaire. La réponse a la forme d'un paiement créé : envoyez authorization_token au navigateur comme sessionId, et gardez transaction.id avec le panier. Quand le total change, modifiez ce même paiement au lieu d'en préparer un autre. Les composants montés gardent leur session.

curl -X PATCH https://api.wajub.com/payments/trx_test_CSUGajfv9xh0XQ5wu2lx \
-H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
-H "Content-Type: application/json" \
-d '{ "amount": 37500, "currency": "XOF" }'

PATCH répond 409 une fois le paiement expiré ou activé. Préparez-en alors un nouveau.

Dans le navigateur, c'est dans onBeforeSubmit que la commande est passée. Le composant l'appelle une fois les champs remplis par le payeur, avant tout débit.

const factory = await components(sessionId, { locale: 'fr' });

const momo = factory
  .create('mobileMoney', {
    fields: { customer: 'external' },
    onBeforeSubmit: async () => {
      // Votre serveur vérifie le panier, passe la commande, puis active le paiement.
      const response = await fetch('/checkout/place-order', { method: 'POST' });
      return response.ok;
    },
  })
  .mount('#momo');

payButton.onclick = () => confirmPayment({ sessionId, components: momo });

curl https://api.wajub.com/payments/trx_test_CSUGajfv9xh0XQ5wu2lx/activate \
-H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
-H "Content-Type: application/json" \
-d '{
  "amount": 37500,
  "currency": "XOF",
  "customer": { "email": "[email protected]", "name": "Amina Diallo" },
  "metadata": { "order_id": "4172" }
}'

Le paiement existe désormais, avec l'id que vous avez gardé, et l'événement payment.created est envoyé. Le jeton de session du navigateur reste le même : le composant débite sans être remonté.

Dans votre propre bloc de moyen de paiement

Quand votre checkout liste lui-même les moyens de paiement, un bloc par moyen avec un bouton radio, montez le composant dans le bloc sélectionné avec variant: 'fields'. Il retire sa marge intérieure et son fond : les champs s'insèrent dans votre bloc, qui apporte le titre, la bordure et le logo. Le Mobile Money remplace aussi son panneau d'instructions par une indication d'une ligne. Les autres types gardent leur panneau.

factory
  .create('mobileMoney', {
    variant: 'fields',
    fields: { customer: 'external', country: 'CM', operator: 'detect' },
    onBeforeSubmit: placeOrder,
  })
  .mount('#method-mobile-money .fields');

Un moyen qui regroupe plusieurs réseaux sous un seul canal n'a besoin d'aucun opérateur, et n'en affiche aucun. En Vue et en Svelte, variant demande @wajub/vue ou @wajub/svelte 1.5.1.

Piloter un composant

getValue() renvoie null jusqu'à ce que le composant d'adresse signale une valeur lors de son premier change. Lisez-la dans le handler ou lors de l'envoi par le payeur, pas au montage.

Avec un framework

Chaque composant existe sous forme d'enveloppe prête à l'emploi, avec les mêmes options comme props, variant compris depuis la 1.5.1 en Vue et en Svelte. bankTransfer et crypto n'ont pas d'enveloppe propre : utilisez ComponentEmbed avec type="bankTransfer" ou type="crypto". L'enveloppe surveille aussi appearance, locale et layout, puis appelle update() pour vous.

const { confirm, isConfirming } = useConfirmPayment(sessionId);
const field = useRef<ComponentInstance | null>(null);

<PaymentComponent sessionId={sessionId} onInstance={(i) => (field.current = i)} />;
<button disabled={isConfirming} onClick={() => field.current && confirm(field.current)}>
  Pay now
</button>;

Le provider, les tableaux de props et l'intégration côté serveur figurent dans React, Vue et Svelte.

Fonctionnalités abandonnées