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.

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 ne voit que les moyens qui peuvent prendre ce paiement, pas une liste figée.

Le Mobile Money plafonne un débit unique à 500 000 XAF, et au même montant en XOF. Un paiement au-dessus est refusé et la page propose au payeur un montant plus faible ou un autre moyen de paiement.

Si vous définissez bearer à customer, la page affiche 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 Paiement — Langue, 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. 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 Paramètres → Image de marque, 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 Paramètres → Collecter. 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.