API reference

Every export, option, method, type, state and error code of @wajub/js.

The complete surface of @wajub/js@1.4.0. The guide pages explain when to use each piece. This one lists all of them.

Two ways to reach the same API

The runtime is one object. You either import helpers that load it for you, or you hold it yourself.

Helpers, or the runtime

import { mount, open, checkout, components, confirmPayment } from '@wajub/js';

import { loadWajub } from '@wajub/js/pure';
const rt = await loadWajub();
rt?.wajub.mount('#checkout', { sessionId });

Export from `@wajub/js`	Returns	Notes
`mount(container, config)`	`Promise<CheckoutInstance \| null>`	`null` on the server
`open(config)`	`Promise<PopupInstance \| null>`	`null` on the server
`checkout(config)`	`Promise<void \| null>`	Redirects the page
`components(sessionId, options?)`	`Promise<ComponentsFactory \| null>`	`null` on the server
`confirmPayment(options)`	`Promise<{ status, transaction? }>`	Rejects with `WajubError`
`fetchSession(sessionId)`	`Promise<SessionPreview>`	Works before anything is mounted
`preload(sessionId, options?)`	`Promise<void \| null>`	`{ iframe?: boolean }`
`getVersion()`	`Promise<string \| null>`	The loaded runtime version
`getCheckoutOrigin()`	`Promise<string \| null>`	Where the checkout is served from
`loadWajub(options?)`	`Promise<WajubRuntime \| null>`	`{ jsOrigin?, jsUrl? }`
`WajubError`	Class	Every rejection is an instance of it

loadWajub.setLoadParameters({ jsOrigin }) sets the origin once, before the first call.

`WajubRuntime`

What loadWajub() resolves to, and what the CDN script puts on window.

Member	What it is
`wajub`	The SDK object, the table below
`Wajub`	The client factory
`WajubError`	The error class

`wajub`

Member	Signature
`mount`	`(container, config) => CheckoutInstance`
`open`	`(config) => PopupInstance`
`checkout`	`(config) => void`
`components`	`(sessionId, options?) => ComponentsFactory`
`confirmPayment`	`(options) => Promise<{ status }>`
`fetchSession`	`(sessionId) => Promise<SessionPreview>`
`preload`	`(sessionId, options?) => void`
`create`	The `Wajub` factory, same object
`version`	The runtime version string
`sdkMajor`	The major version
`checkoutOrigin`	The origin the iframes come from
`createHeadless`	Removed in 2.1, throws when called

These are synchronous, because the runtime is already loaded by the time you hold it.

`Wajub()` client

A client holds a publishable key, a session, or both, so you stop repeating them.

Call	What you get
`Wajub('pk_test.…')`	A client that can `createPayment()`
`Wajub.session(token)`	A client bound to an existing session
`Wajub({ publishableKey, sessionId })`	Both at once

Option	What it does
`sessionId`	The `authorization_token` from your server
`publishableKey`	Your `pk.` or `pk_test.` key
`apiKey`	Deprecated alias for `publishableKey`
`apiBase`	API origin override, defaults to `https://api.wajub.com`
`paymentsUrl`	Full `POST /payments` URL override
`useCheckoutProxy`	Route through the checkout's own `/api/payments`
`componentOrigin`	Canonical origin for payment fields

Client members

Member	What it does
`publishableKey`, `sessionId`, `environment`	What the client currently holds
`apiBase`, `checkoutOrigin`	Where it talks
`useSession(sessionId)`	Binds another session, returns the client
`createPayment(params)`	`POST /payments` with the publishable key
`initCheckout(options)`	Creates the payment and shows it in one call
`fetchSession(sessionId?)`	Session preview
`preload(sessionId?, options?)`	Warms the runtime
`mount`, `open`, `checkout`	The three hosted modes, session already bound
`components(sessionIdOrConfig?, config?)`	The fields factory
`confirmPayment(options?)`	Submits a mounted component

Factory statics

Member	What it does
`Wajub.session(sessionId, options?)`	A session bound client
`Wajub.parsePublishableKey(key)`	`{ key, environment }`, throws on a secret key
`Wajub.createPayment(key, params, options?)`	One shot, no client to keep

`EmbeddedConfig`

Used by mount(), by CheckoutEmbed in every framework, and as the base of PopupConfig.

Option	Type	Default
`sessionId`	`string`	Required
`locale`	`string`	Session default
`layout`	`CheckoutLayout`	Session default
`appearance`	`AppearanceConfig`	Session branding
`embedOrigin`	`string`	The current page origin
`loadingText`	`string`	Empty
`showLoading`	`boolean`	`true`
`theme`	`EmbedTheme`	Derived from `appearance`, deprecated

Callback	Receives
`onReady`	`CheckoutInstance`
`onSuccess`	`Record<string, unknown>`, the transaction
`onError`	`WajubError`
`onLoadError`	`WajubError`
`onCancel`	Nothing
`onExpired`	Nothing
`onStateChange`	`{ state?: CheckoutState, method?: string }`
`onMethodChange`	`{ methodId?, method_id? }`
`onBreakdown`	`EmbedBreakdown`
`onResize`	`height: number`, inline only
`onClose`	Nothing, overlay only

`PopupConfig`

Everything in EmbeddedConfig, plus the modal.

Option	Type	Default
`width`	`number`	`920`
`height`	`number`	`680`
`closeOnOverlay`	`boolean`	`false`
`closeOnEscape`	`boolean`	`true`
`closeOnSuccess`	`boolean`	`true`
`closeOnCancel`	`boolean`	`true`
`closeOnExpired`	`boolean`	`true`

The three closeOn outcome flags run after your callback, never before it.

`CheckoutInstance` and `PopupInstance`

Method	What it does
`mount()`	Re-attaches after `unmount()`
`unmount()`	Removes from the DOM, keeps the instance
`destroy()`	Full teardown
`update(partial)`	`locale`, `appearance`, `currency`, `layout`, deprecated `theme`
`getState()`	The current `CheckoutState`
`submit()`	Submits the form
`cancel()`	Cancels the payment in progress
`retry()`	Retries after a failure
`selectMethod(methodId)`	Switches payment method
`close()`	Closes the overlay
`isOpen()`	Overlay only, whether the modal is visible

update({ layout }) is stored, not sent

locale, appearance and currency reach the checkout. layout only updates the local config, so the methods keep the arrangement they were mounted with. Remount to change it.

`ComponentConfig`

Passed to wajub.components(sessionId, options) as defaults, and to factory.create(type, config) per component.

Option	Type	Applies to
`sessionId`	`string`	Required
`locale`	`string`	All
`appearance`	`AppearanceConfig`	All
`layout`	`CheckoutLayout`	`payment`
`componentOrigin`	`string`	All, defaults to the page origin
`collectAddress`	`shipping` or `billing`	`payment`
`addressMode`	`shipping` or `billing`	`address`
`collectName`	`boolean`	`payment`, `address`
`fields.phone`	`always`, `auto`, `never`	`payment`, `address`

Callback	Receives
`onReady`	`ComponentInstance`
`onChange`	`ComponentChangeEvent`
`onFocus`, `onBlur`	Nothing
`onLoadError`	`WajubError`
`onSuccess`	The transaction
`onError`	`WajubError`
`onMethodChange`	`{ methodId? }`

`ComponentsFactory`

Member	What it is
`sessionId`	The session every component inherits
`create(type, config?)`	A new `ComponentInstance`

Types. card, mobileMoney, wallet, payment, address.

`ComponentInstance`

Every method except the readers returns the instance, so calls chain.

Method	Returns
`mount(container)`	The instance
`unmount()`, `destroy()`	Nothing
`on(event, fn)`, `off(event, fn)`	The instance
`update({ locale, appearance, layout })`	The instance
`focus()`, `blur()`, `submit()`	The instance
`selectMethod(methodId)`	The instance
`getState()`	`CheckoutState`
`isComplete()`	`boolean`
`getError()`	`WajubError` or `null`
`getValue()`	`ComponentAddressValue` or `null`

Events

Event	Payload
`ready`	`ComponentInstance`
`change`	`ComponentChangeEvent`
`focus`, `blur`	Nothing
`loaderror`	`WajubError`
`resize`	`{ height }`
`success`	The transaction
`error`	`WajubError`
`statechange`	`{ state, method }`
`methodchange`	`{ methodId }`

`ConfirmPaymentOptions`

Option	Type	Default
`sessionId`	`string`	Required
`components`	`ComponentInstance`	Required, one mounted component
`timeout`	`number`	`60000` milliseconds, `0` waits forever
`callback`	`string`	Deprecated, never read

Resolves with { status, transaction }. Rejects with a WajubError carrying missing_component, wallet_not_supported, address_not_payment or confirmation_timeout.

`CreatePaymentParams`

What client.createPayment() sends. The same fields as POST /payments, narrowed to what a browser may set.

Field	Type
`amount`	`number`, required
`currency`	`string`, required
`reference`	`string`
`description`	`string`
`customer`	`{ email?, name?, phone?, country? }`
`bearer`	`merchant` or `customer`, who pays the fee
`callback`	HTTPS URL, redirect flow only
`metadata`	`Record<string, string>`

`CreatePaymentResult`

Field	What it is
`sessionId`	Pass this to `mount`, `open` or `components`
`authorizationToken`	The same value, under the API's name
`authorizationUrl`	The hosted page, or `null`
`transaction`	The transaction object, or `null`
`raw`	The untouched API response

`InitCheckoutOptions`

Creates the payment and shows it in one call. Everything in EmbeddedConfig applies too.

Option	Type	What it does
`mode`	`inline`, `overlay`, `redirect`	How the checkout appears
`container`	`string` or `HTMLElement`	Required for `inline`
`sessionId`	`string`	Skips `createPayment()`
`payment`	`CreatePaymentParams`	Used when there is no `sessionId`
`checkout`	`Partial<EmbeddedConfig>`	Options for the embed itself

It resolves with { session, instance }, and throws missing_container when inline has nowhere to go.

`SessionPreview`

What fetchSession(sessionId) resolves to. Read it before mounting to show an amount, a merchant name, or a sandbox banner.

Field	Type
`session_id`	`string`
`status`	`string`
`environment`	`sandbox` or `live`
`amount`	`number`
`currency`	`string`
`merchant_name`	`string`
`payment_methods`	`Array<{ id, type, label }>`
`saved_methods`	`Array<{ id, type, label }>`, returning customers
`features`	`Record<string, boolean>`

`AppearanceConfig`

The full key list, the presets and the filtering rules are on Appearance.

Group	Keys
Preset	`theme`: `stripe`, `night`, `flat`, `none`
Colour	`primaryColor`, `secondaryColor`, `backgroundColor`, `buttonTextColor`, `inputBackgroundColor`, `inputBorderColor`, `textMutedColor`, `successColor`, `errorColor`
Shape	`fontFamily`, `borderRadius`, `shadow`
Behaviour	`colorScheme`, `labels`, `disableAnimations`
Tokens	`variables`, sixteen keys mapped to `--wj-*`
Selectors	`rules`, `.Input` and `.Label` only

States

getState() and onStateChange both speak this vocabulary.

CheckoutState

INITIATED → COLLECTING_DETAILS → PROCESSING → SUCCESS
                                ↘ OTP_REQUIRED, 3DS_REQUIRED, USSD_REQUIRED
                                ↘ APPROVAL_REQUIRED, VERIFYING, PENDING
                                ↘ FAILED, CANCELLED, EXPIRED

A new instance reports INITIATED until the checkout says otherwise.

`WajubError`

Every rejection and every error callback receives one.

Field	Type
`message`	`string`, written for a human
`type`	`api_error`, `authentication_error`, `invalid_request_error`, `payment_error`, `rate_limit_error`
`code`	`string`, the machine name
`decline_code`	`string` or `null`, from the provider
`retryable`	`boolean`
`param`	`string` or `null`, the field at fault

WajubError.fromPayload(payload) builds one from a raw object, and toJSON() gives it back.

Codes raised by the SDK itself

These never reach the network. They are integration mistakes.

Code	Cause
`secret_key_in_browser`	A `sk.` key passed to `Wajub()`
`invalid_publishable_key`	A key that is not a publishable key
`invalid_init`	A secret key passed to the client constructor
`missing_publishable_key`	`createPayment()` without a key
`missing_session_token`	A call that needs a session and has none
`missing_session`	No `sessionId` on the client
`missing_container`	`initCheckout` in `inline` mode with nowhere to mount
`missing_component`	`confirmPayment` without a submittable component
`wallet_not_supported`	`confirmPayment` on a `wallet` component
`address_not_payment`	`confirmPayment` on an `address` component
`confirmation_timeout`	No outcome within `timeout`
`components_unavailable`	The components runtime did not load
`load_error`	The checkout iframe failed to load

Framework packages

The three wrappers export the same set, with the idioms of each framework.

Export	What it is
`WajubProvider`	Loads the runtime once for a subtree
`CheckoutEmbed`	The hosted checkout, inline
`CardComponent`, `MobileMoneyComponent`, `WalletComponent`, `PaymentComponent`, `AddressComponent`	One field group each
`ComponentEmbed`	The same, with `type` as a prop
`useWajub`, `useWajubOptional`, `useLoadWajub`	Reach the runtime
`useConfirmPayment`	Submit a field component

Wrapper prop	Applies to	Default
`className` in React and Svelte, `class` in Vue	Both	none
`style`	Both	none
`minHeight`	`CheckoutEmbed`	`480`
`minHeight`	Field components	`200`
`onInstance`	Field components	none, fires with `null` on unmount

Each package has its own page, because the differences are real: React, Vue, Svelte.

Two ways to reach the same API

WajubRuntime

wajub

Wajub() client

Client members

Factory statics

EmbeddedConfig

PopupConfig

CheckoutInstance and PopupInstance

ComponentConfig

ComponentsFactory

ComponentInstance