Hosted Checkout

Hosted Checkout is the shortest path to a working payment. You create the payment, send the customer to the page Wajub renders, and verify the outcome when they come back. The operator list, the prompt, the retry when it times out and the wording of every failure belong to us, and they keep improving without you touching anything.

Create the payment

Everything the page needs comes from the create call. Send it from your server with the secret key: the public key also creates payments, but it exists for the case where the call is made in a browser.

A create call that uses the hosted page's own fields looks like this:

curl https://api.wajub.com/payments \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "XAF",
    "customer": { "email": "[email protected]", "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"
  }'

The response carries the payment and the page to send the customer to. Store transaction.id against your order before you redirect:

authorization_url carries an opaque session token, not the transaction id. Redirect to it exactly as returned: never parse it, and never build one yourself. The host is not always pay.wajub.com either, since an account on the Scale plan can serve its checkout from its own verified domain.

What the page decides on its own

The customer sees the operators that can actually take their money, not a fixed list. Wajub filters by currency, by environment and by the amount, so a channel that cannot process XAF is never offered rather than failing at the last step.

Mobile Money caps a single debit at 500 000 XAF, and the same in XOF. In live a payment above that is refused, and the page asks the payer for a smaller amount or another method. In sandbox the page splits it into successive tranches and collects them one after another. That is the situation where a payment sits in partial, described in the payment lifecycle.

While the operator prompt is out, the page shows the instruction that matches the channel, the #150# style dialling code for one operator and the in-app confirmation for another. If you set bearer to customer, it also shows the fee on top of your amount and the total actually being debited.

The language is English or French. It follows the Settings → Regional → Language setting, which accepts auto, en or fr. On auto, the page uses the customer's own preferred_language, and opens in French when the customer has none.

Handle the return

Once the attempt is over, the customer comes back to your callback with the payment identified in the query string:

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

reference is the Wajub payment id and trxref is the reference you sent, present only when you set one. Both come back whatever the outcome: the return after a failed payment used to carry status alone. status is succeeded, failed, cancelled or expired. After a success the page sends the customer on by itself; after a failure or an expiry, when they choose to come back. A customer who closes the page without finishing never comes back at all.

The verification call takes the id you stored before redirecting:

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

Check the amount and the currency as well as the status, and let the webhook close the orders whose customer never came back.

Make the page yours

The look of the page is set once for the whole account, in Settings → Branding, and applies to every payment page you ever create, in sandbox as in production.

You can also collect information the payment itself does not carry, a delivery note or a table number, by adding fields in Settings → Collect → Fields. Each field has a type among text, textarea, select, checkbox, number, email and tel, a label, an optional placeholder, and a required flag. They appear on the hosted page in the order you arrange them.

What the customer types in those fields is not saved on the payment today, so it never comes back on a read or in a webhook. When you need the answer, ask for it on your own site before creating the payment, and send it in metadata.