Hosted checkout

Hosted checkout is the whole payment page rendered by Wajub: method selection, order summary, OTP, 3DS. Coupons and the shipping step are switched off on it today, whatever the session carries. You choose where it appears. The configuration is the same in all three cases, so the only real decision is inline, overlay or redirect.

Which one

All three need a sessionId, which is the authorization_token from POST /payments. None of them needs a key.

Inline and overlay frame the checkout in your page. Declare the origins that embed it in Settings → Checkout embedding before you take live payments: once the list is filled, only those origins can show it. The page is on every plan. See where the checkout may be embedded.

Inline

mount takes a selector or an element, and returns the instance you drive afterwards.

import { mount } from '@wajub/js';

const checkout = await mount('#checkout', {
  sessionId,
  onSuccess: () => (window.location.href = '/order/complete'),
  onError: (error) => showRetry(error),
});

Two things fail immediately rather than later: a missing sessionId, and a selector that matches nothing, both with a plain Error before any network request. window.wajub throws it at call time; the @wajub/js helpers are async, so their promise rejects with it instead.

Configuration

Every option below is also a prop on CheckoutEmbed in React, Vue and Svelte.

Callbacks

await mount('#checkout', {
  sessionId,
  onReady: (instance) => (checkoutRef = instance),
  onSuccess: (transaction) => markPaidInTheInterface(transaction),
  onError: (error) => console.error(error.code, error.message),
  onLoadError: (error) => showSessionExpired(error),
  onBreakdown: (b) => (total.textContent = `${b.total.toLocaleString()} ${b.currency}`),
});

onLoadError carries session_not_found for a token Wajub does not know, session_terminal_expired for one whose payment ended and whose token has stopped, and load_error when the iframe itself failed. onError receives none of them: it is for a payment that failed. From Wajub.js 1.6.0, right after the callback, the overlay closes or the inline checkout leaves the page. onClose is not called: the checkout never started, so nothing was closed. Show your own message from the callback.

onSuccess fires in a browser, so treat it as an interface signal. The order ships on the webhook. It receives the checkout's summary of the payment: id is Wajub's id of the payment, the one GET /payments/{id} takes, reference is yours, and amount is in major units like the API.

Inline, the confirmation keeps a Done button. When the payer presses it, onClose fires and the checkout leaves the page, so put your own next step there.

Driving the instance

checkout.getState();                  // 'COLLECTING_DETAILS', 'PROCESSING', …
checkout.update({ locale: 'en' });
checkout.update({ appearance: { colorScheme: 'dark' } });
checkout.update({ currency: 'USD' }); // multi currency sessions only
checkout.selectMethod('pm_momo');
checkout.submit();                    // presses the checkout's own pay button
checkout.retry();
checkout.cancel();
checkout.unmount();                   // off the page, the instance is kept
checkout.mount();                     // back on the page
checkout.destroy();

submit() presses the pay button of the method the payer is on. The checkout validates the form as it does for the payer and shows its own messages, so follow the result with onStateChange. When there is no button to press (before a method is chosen, on an OTP or confirmation step, on Apple Pay and Google Pay, which only answer the payer's own tap, and while a payment is already on its way), nothing is pressed and onError receives a WajubError with the code nothing_to_submit, from Wajub.js 1.6.0. Earlier versions said nothing.

unmount() takes the checkout off the page and keeps the instance, and mount() puts it back, inline and in the overlay alike. The checkout is loaded again from its token when it returns: onReady fires once more, with the locale, appearance and layout last given to update(). On an overlay, unmount() does not call onClose. After destroy(), or close() on an overlay, mount() does nothing.

Overlay

Same configuration, same callbacks, same instance, plus the modal itself.

import { open } from '@wajub/js';

const popup = await open({
  sessionId,
  width: 960,
  closeOnOverlay: true,
  onSuccess: (transaction) => fulfillOrder(transaction),
  onClose: () => console.log('dismissed'),
});

popup.isOpen();

Closing the modal dismisses the interface only. The session stays open until it completes, expires, or is cancelled inside the checkout, so the same token still mounts.

onResize never fires in overlay mode, because the modal has a fixed height.

Redirect

The least code, and the only mode where callback matters.

// The URL your server already received from POST /payments
window.location.href = authorizationUrl;

// Or, when the browser only has the token
import { checkout } from '@wajub/js';
await checkout({ sessionId });

The payer comes back to the callback URL you set when creating the payment, with ?status=succeeded|cancelled|failed|expired, reference, Wajub's id of the payment, and trxref, your own reference, whatever the outcome (the return after a failed payment used to carry status alone). Read the payment with that reference on your server: the query string is a hint. The webhook is the confirmation. See Sessions and security for the full contract.

Styling

The checkout arrives already wearing your account branding, set once in the Dashboard. Pass appearance only to change something for this one embed, a dark mode toggle or a campaign colour.

await mount('#checkout', {
  sessionId,
  layout: 'tabs',
  appearance: { theme: 'night', primaryColor: '#6366f1', labels: 'floating' },
});

The full key list is on Appearance, and the account wide defaults are on Branding and theming.