Sessions & security

Everything on the browser side of Wajub runs on one short lived string: the session token. This page covers where it comes from, what it replaces, and why the key that creates it must never leave your server.

Three credentials, three places

The prefix of a Wajub key tells you where the key is allowed to live. Live keys start with sk. or pk., sandbox keys with sk_test. or pk_test..

The session token is what makes the other two unnecessary in the browser. It is scoped to a single payment, it carries no account access, and it dies with that payment.

The flow that is correct

Two steps, in this order, every time.

1. Your server calls POST /payments with the secret key and gets back an authorization_token.
2. Your browser receives that token, and nothing else, and passes it as sessionId.

curl https://api.wajub.com/payments \
-H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
-H "Content-Type: application/json" \
-d '{
  "amount": 35000,
  "currency": "XOF",
  "reference": "ORDER-123",
  "customer": { "email": "[email protected]" }
}'

The response carries three things worth keeping.

const { sessionId } = await fetch('/api/checkout/session', { method: 'POST' })
  .then((r) => r.json());

await mount('#checkout', { sessionId });

Before the order exists

Payment fields shown while the buyer is still on the checkout come before the order. Create their session with deferred: true: the payment is only prepared, stays out of your payments and sends no webhook until your server activates it with the final total and the customer. Before the order exists walks through the three calls.

Creating a session from the browser

Wajub(publishableKey).createPayment() exists and works with a sandbox key: in 1.5.0 a live key, pk.…, is read as a session id, so in live the session is created on your server. It is the right tool for a prototype or a demo page with a fixed price. It is the wrong tool for a shop, because the amount is then decided by code the customer controls.

const client = Wajub('pk_test.xxxxxxxxxxxxxxxx…');

const { sessionId } = await client.createPayment({
  amount: 35000,
  currency: 'XOF',
  customer: { email: '[email protected]' },
});

await client.mount('#checkout');

What the token may do

The session token authorises exactly one payment, and the runtime is what enforces it.

• It mounts the checkout, opens the overlay, or drives the field components.
• It reads the session preview through fetchSession(sessionId).
• On a prepared payment, it shows the ways to pay and charges nothing: every charge answers 409 until your server activates the payment. Activation keeps the token.
• It stays valid while the payment is not terminal, and stops shortly after succeeded, failed, expired or cancelled.
• It survives a remount, so a component that unmounts and comes back reuses the same token.
• It lives as long as the payment: 24 hours by default, or the expires.in minutes you set on POST /payments (5 to 43 200). Past that the payment expires, onExpired fires on the checkout, and a payment field rejects with session_expired.
• Payment attempts on one session are rate limited. Past the limit, the attempt is refused with rate_limited until a short wait has passed.

Mounting a token that has stopped calls onLoadError with session_terminal_expired, and a token Wajub does not know calls it with session_not_found. The embed itself stays empty, which is why that callback is worth wiring even on a page you think cannot reach it. Until the token stops, a checkout mounted on a finished payment reports the outcome instead, through onSuccess, onError, onExpired or onCancel.

The callback URL

callback is a redirect destination, so it only matters for the redirect flow. Pass a plain HTTPS base URL with no query string of your own. Wajub appends its own.

Every return carries reference and trxref, a failed payment's included: that one used to carry status alone.

https://shop.example.com/order/complete?status=succeeded&reference=trx_CSUGajfv9xh0XQ5wu2lx&trxref=ORDER-123

An embed never leaves your page, so callback does nothing there. Use onSuccess for the interface and the webhook for the truth.

Multi domain shops

A single domain needs no configuration. When your checkout runs on a second domain, name the canonical one explicitly.

await mount('#checkout', { sessionId, embedOrigin: 'https://shop.example.com' });

const factory = await components(sessionId, {
  componentOrigin: 'https://shop.example.com',
});

Before you go live