Hosted checkout
Embed the full Wajub payment page inline, as an overlay, or via redirect.
Hosted checkout includes payment method selection, order summary, OTP, 3DS, coupons, and shipping when enabled on the session.
Default styling comes from server branding. Override per embed with Appearance.
Redirect
Simplest flow — send the customer to authorization_url from POST /payments:
// Option A — URL from your backend
window.location.href = authorizationUrl;
// Option B — SDK
wajub.checkout({ sessionId: 'YOUR_SESSION_TOKEN' });After payment, Wajub redirects to your callback URL with ?status=complete|cancelled|failed|expired.
Always confirm server-side via webhooks or GET /payments/{id} — do not trust the query string alone.
Callback URL
Pass callback on POST /payments only for redirect checkout.
For inline or overlay embeds, omit it — confirmation stays in the iframe via
onSuccess.
Inline embed (mount)
const checkout = wajub.mount('#checkout', {
sessionId: 'YOUR_SESSION_TOKEN',
locale: 'fr',
layout: 'tabs',
appearance: { primaryColor: '#6366f1', borderRadius: '12px' },
loadingText: 'Loading checkout…',
showLoading: true,
onReady: () => console.log('ready'),
onSuccess: (transaction) => window.location.href = '/thanks',
onError: (error) => console.error(error.code, error.message),
onCancel: () => console.log('cancelled'),
onExpired: () => console.log('expired'),
onBreakdown: (b) => {
document.getElementById('total').textContent =
b.total.toLocaleString() + ' ' + b.currency;
},
onStateChange: ({ state, method }) => console.log(state, method),
onMethodChange: ({ methodId }) => console.log('method', methodId),
onResize: (height) => { document.getElementById('checkout').style.height = height + 'px'; },
onLoadError: (error) => console.error('load failed', error),
});Container height
Set min-height: 480px on the container while loading. The embed adjusts height after
onReady via onResize(height) — the callback receives the height in pixels as a number,
not an object.
Instance methods
checkout.getState();
checkout.update({ locale: 'en' });
checkout.update({ appearance: { primaryColor: '#0f172a', colorScheme: 'dark' } });
checkout.update({ currency: 'USD' }); // multi-currency sessions
checkout.submit();
checkout.selectMethod('pm_momo');
checkout.cancel();
checkout.retry();
checkout.destroy();Overlay (open)
Same callbacks and instance API as inline, plus modal options:
const popup = wajub.open({
sessionId: 'YOUR_SESSION_TOKEN',
width: 960,
height: 720,
closeOnOverlay: true,
closeOnEscape: true,
closeOnSuccess: true,
appearance: { theme: 'stripe', primaryColor: '#6366f1' },
onClose: () => console.log('overlay dismissed'),
onCancel: () => console.log('payment cancelled'),
onSuccess: (txn) => fulfillOrder(txn),
});
popup.isOpen(); // true while modal visible| Option | Default | Description |
|---|---|---|
width | 920 | Modal max-width (px) |
height | 680 | Modal height (px) |
closeOnOverlay | false | Close when clicking backdrop |
closeOnEscape | true | Close on Escape |
closeOnSuccess | true | Auto-close after success |
Closing the overlay (×, Escape, or backdrop when enabled) dismisses the modal only — the session stays active until it expires or is cancelled.
Main callbacks
| Callback | When | Payload |
|---|---|---|
onReady | Session loaded, form visible | CheckoutInstance |
onSuccess | Payment succeeded | transaction object |
onError | Payment failed | WajubError |
onLoadError | Invalid token, terminal session, embed blocked | WajubError |
onCancel | Customer explicitly cancelled | — |
onExpired | Session expired | — |
onBreakdown | Order totals updated | { subtotal, discount, tax, total, currency } |
onStateChange | State machine transition | { state, method? } |
onMethodChange | Payment method changed | { methodId?, method_id? } |
onResize | Iframe height changed | height: number — inline only |
onClose | Overlay closed | — |
Security
Always use the SDK
Call wajub.mount() or wajub.open() — never paste a checkout URL
manually into an iframe. Your site and callback must use HTTPS in production.
For multi-domain setups, pass your canonical shop origin:
wajub.mount('#checkout', {
sessionId,
embedOrigin: 'https://shop.example.com',
});