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.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -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. Un paiement au-dessus n'est pas refusé : 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, puis le preferred_language du client lui-même quand le réglage reste sur auto.

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. status vaut succeeded ou cancelled, rien d'autre : un client qui abandonne sans annuler 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.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…"

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, et ce que le client saisit revient avec le paiement.