Checkout hébergé

Le checkout hébergé est le chemin le plus court vers un paiement qui fonctionne. Vous créez le paiement, vous envoyez le client vers la page affichée par Wajub, et vous vérifiez le résultat à son retour. La liste des opérateurs, la demande de confirmation, la nouvelle tentative quand le délai est dépassé et le libellé de chaque échec sont de notre ressort, et ils continuent de s'améliorer sans que vous ayez à toucher quoi que ce soit.

Créer le paiement

Tout ce dont la page a besoin vient de l'appel de création. Envoyez-le depuis votre serveur avec la clé secrète : la clé publique crée aussi des paiements, mais elle existe pour le cas où l'appel est fait depuis un navigateur.

Un appel de création qui utilise les champs propres à la page hébergée ressemble à ceci :

curl https://api.wajub.com/payments \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "XAF",
    "customer": { "email": "amina@example.com", "name": "Amina N." },
    "description": "Order #4172",
    "reference": "order-4172",
    "items": [
      { "name": "Wireless earbuds", "quantity": 1 },
      { "name": "Delivery", "quantity": 1 }
    ],
    "expires": { "in": 60 },
    "callback": "https://shop.example.com/order/complete"
  }'

La réponse contient le paiement et la page vers laquelle envoyer le client. Enregistrez transaction.id avec votre commande avant de rediriger :

authorization_url contient un jeton de session opaque, pas l'id de la transaction. Redirigez vers cette URL exactement telle qu'elle est renvoyée : ne l'analysez jamais et n'en construisez jamais une vous-même. L'hôte n'est d'ailleurs pas toujours pay.wajub.com, car un compte sur le plan Scale peut servir son checkout depuis son propre domaine vérifié.

Ce que la page décide seule

Le client voit les opérateurs qui peuvent réellement prendre son argent, pas une liste figée. Wajub filtre par devise, par environnement et par montant : un canal incapable de traiter du XAF n'est jamais proposé, plutôt que d'échouer à la dernière étape.

Le Mobile Money plafonne un débit unique à 500 000 XAF, et au même montant en XOF. En live, un paiement au-dessus est refusé et la page propose au payeur un montant plus faible ou un autre moyen de paiement. Dans la sandbox, la page le découpe en tranches successives et les encaisse l'une après l'autre. C'est la situation dans laquelle un paiement reste en partial, décrite dans le cycle de vie d'un paiement.

Pendant que la demande de l'opérateur est en cours, la page affiche l'instruction propre au canal : le code à composer de type #150# pour un opérateur, la confirmation dans l'application pour un autre. Si vous définissez bearer à customer, elle affiche aussi les frais ajoutés à votre montant et le total réellement débité.

La langue est l'anglais ou le français. Elle suit le réglage Settings → Regional → Language, qui accepte auto, en ou fr. Sur auto, la page utilise le preferred_language du client, et s'ouvre en français quand le client n'en a pas.

Gérer le retour

Une fois la tentative terminée, le client revient sur votre callback, avec le paiement identifié dans les paramètres de l'URL :

https://shop.example.com/order/complete?reference=trx_test_CSUGajfv9xh0XQ5wu2lx&status=succeeded&trxref=order-4172

reference est l'id du paiement Wajub et trxref est la reference que vous avez envoyée, présente seulement si vous en avez défini une. Les deux reviennent quelle que soit l'issue : le retour après un paiement échoué ne portait que status. status vaut succeeded, failed, cancelled ou expired. Après un succès, la page renvoie le client d'elle-même ; après un échec ou une expiration, quand il choisit de revenir. Un client qui ferme la page sans terminer ne revient jamais.

L'appel de vérification prend l'id que vous avez enregistré avant la redirection :

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

Vérifiez le montant et la devise en plus du statut, et laissez le webhook clôturer les commandes dont le client n'est jamais revenu.

Personnaliser la page

L'apparence de la page se règle une fois pour tout le compte, dans Settings → Branding, et s'applique à chaque page de paiement que vous créerez, en sandbox comme en production.

Vous pouvez aussi collecter des informations que le paiement lui-même ne contient pas, une note de livraison ou un numéro de table, en ajoutant des champs dans Settings → Collect → Fields. Chaque champ a un type parmi text, textarea, select, checkbox, number, email et tel, un libellé, un placeholder facultatif et un indicateur obligatoire. Les champs apparaissent sur la page hébergée dans l'ordre où vous les disposez.

Ce que le client saisit dans ces champs n'est pas enregistré sur le paiement aujourd'hui : il ne revient ni à la lecture ni dans un webhook. Si vous avez besoin de la réponse, demandez-la sur votre propre site avant de créer le paiement, et envoyez-la dans metadata.