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.

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": "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"
  }'

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 only the methods that can take this payment, not a fixed list.

Mobile Money caps a single debit at 500 000 XAF, and the same in XOF. A payment above that is refused, and the page asks the payer for a smaller amount or another method.

If you set bearer to customer, the page shows the fee on top of your amount and the total actually being debited.

The language is English or French. It follows the Checkout — 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. 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. 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.