API reference

Complete public API for @wajub/js — global wajub, Wajub client, checkout instance, popup overlay, and payment fields.

30 min read

Global `wajub`

Available after loading https://js.wajub.com or loadWajub() from @wajub/js.

Member	Description
`wajub.mount(container, config)`	Inline hosted checkout → `CheckoutInstance`
`wajub.open(config)`	Modal overlay → `PopupInstance`
`wajub.checkout(config)`	Full-page redirect
`wajub.preload(sessionId, opts?)`	Preload checkout UI
`wajub.fetchSession(sessionId)`	Session preview (amount, methods, features)
`wajub.components(sessionId, opts?)`	Payment fields factory
`wajub.confirmPayment(opts)`	Submit mounted payment field(s)
`Wajub(keyOrSession)`	Client factory
`WajubError`	Normalized error class
`wajub.version`	SDK version string

`loadWajub()` (@wajub/js)

import { loadWajub, mount } from '@wajub/js';
import { loadWajub } from '@wajub/js/pure'; // no auto-load side effect

Export	Description
`loadWajub()`	Load runtime from CDN; returns `null` during SSR
`mount(container, config)`	Async helper — load + mount

Returns { wajub, Wajub } after load.

`Wajub()` client

Call	Result
`Wajub('pk_test_…')`	Client with `createPayment()`
`Wajub('trx_…')` / `Wajub.session('trx_…')`	Client bound to existing session
`Wajub({ publishableKey, sessionId })`	Combined client

Client methods

Method	Description
`createPayment(params)`	Create session (requires `pk_…`)
`useSession(sessionId)`	Switch active session
`fetchSession(sessionId?)`	Session preview
`preload(sessionId?, opts?)`	Preload UI
`mount(container, config?)`	Inline embed
`open(config?)`	Overlay
`checkout(config?)`	Redirect
`components(sessionId?, config?)`	Payment fields factory
`confirmPayment(opts?)`	Submit components
`initCheckout(opts)`	One-shot create + mount/open/redirect

`EmbeddedConfig` (mount / CheckoutEmbed)

Used by wajub.mount(), CheckoutEmbed, and as the base of PopupConfig.

Option	Type	Description
`sessionId`	`string`	Required — `authorization_token` from your backend
`locale`	`string`	`fr` · `en` · `es` · `pt` · `ar`
`layout`	`CheckoutLayout`	`classic` · `compact` · `tabs` · `accordion`
`appearance`	`AppearanceConfig`	Appearance
`embedOrigin`	`string`	Canonical site URL (multi-domain embeds)
`theme`	`EmbedTheme`	Deprecated — use `appearance`
`loadingText`	`string`	Placeholder text before `onReady`
`showLoading`	`boolean`	Show placeholder (default `true`)
`onReady`	`(instance) => void`	Checkout visible
`onSuccess`	`(transaction) => void`	Payment succeeded
`onError`	`(WajubError) => void`	Payment failed
`onLoadError`	`(WajubError) => void`	Invalid token / embed blocked
`onCancel`	`() => void`	Customer cancelled
`onExpired`	`() => void`	Session expired
`onBreakdown`	`(EmbedBreakdown) => void`	`{ subtotal, discount, tax, total, currency }`
`onStateChange`	`({ state, method }) => void`	State machine transition
`onMethodChange`	`({ methodId, method_id }) => void`	Payment method changed
`onResize`	`(height: number) => void`	Inline only — iframe height in px
`onClose`	`() => void`	Overlay dismissed (session still active)

`PopupConfig` (open / overlay)

Extends EmbeddedConfig with modal options for wajub.open():

Option	Type	Default	Description
`width`	`number`	`920`	Modal max-width (px)
`height`	`number`	`680`	Modal height (px)
`closeOnOverlay`	`boolean`	`false`	Close when clicking backdrop
`closeOnEscape`	`boolean`	`true`	Close on Escape key
`closeOnSuccess`	`boolean`	`true`	Auto-close after success (`onSuccess` fires first)

Plus all EmbeddedConfig options and callbacks.

Node.js

wajub.open({
sessionId,
width: 960,
height: 720,
closeOnOverlay: true,
closeOnSuccess: true,
appearance: { theme: 'night' },
onSuccess: (txn) => fulfillOrder(txn),
onClose: () => console.log('modal closed'),
});

`CheckoutInstance` / `PopupInstance`

Method	Description
`mount()`	Re-attach if unmounted
`unmount()`	Remove from DOM, keep instance
`destroy()`	Full teardown (alias: use on cleanup)
`update(partial)`	Update `locale`, `appearance`, `layout`, `currency`, deprecated `theme`
`getState()`	Current `CheckoutState`
`submit()`	Submit payment programmatically
`cancel()`	Cancel in-progress payment
`retry()`	Retry after failure
`selectMethod(methodId)`	Switch payment method
`close()`	Close overlay
`isOpen()`	Popup only — modal visible

`ComponentConfig` (payment fields)

Passed to wajub.components(sessionId, opts) and factory.create(type, config):

Option	Type	Description
`sessionId`	`string`	Required
`locale`	`string`	UI language
`componentOrigin`	`string`	Canonical origin (multi-domain), like `embedOrigin`
`appearance`	`AppearanceConfig`	Styling — Appearance
`layout`	`CheckoutLayout`	Method selector layout
`collectAddress`	`shipping` · `billing`	payment component — inline address collection
`addressMode`	`shipping` · `billing`	address component — label mode
`collectName`	`boolean`	Collect payer name on address component
`fields.phone`	`always` · `auto` · `never`	Phone field visibility
`onReady`	`(component) => void`	Component mounted
`onChange`	`(ComponentChangeEvent) => void`	`{ complete, empty, error?, value? }`
`onFocus`	`() => void`	Field focused
`onBlur`	`() => void`	Field blurred
`onLoadError`	`(WajubError) => void`	Load failed
`onSuccess`	`(transaction) => void`	Payment succeeded
`onError`	`(WajubError) => void`	Payment failed
`onMethodChange`	`({ methodId }) => void`	Method changed

`ComponentInstance`

Method	Description
`mount(container)`	Mount to DOM element or selector
`unmount()`	Remove from DOM
`destroy()`	Full teardown
`on(event, fn)`	Subscribe — see events below
`off(event, fn)`	Unsubscribe
`update(partial)`	Live update `locale`, `appearance`, `layout`
`focus()`	Focus first field
`blur()`	Blur active field
`submit()`	Submit component
`selectMethod(methodId)`	Switch method (payment component)
`getState()`	Current `CheckoutState`
`isComplete()`	All required fields valid
`getError()`	Current `WajubError` or `null`
`getValue()`	Address values `{ name, phone, address, mode }`

Component events

Event	Payload
`ready`	`ComponentInstance`
`change`	`{ complete?, empty?, error?, value? }`
`focus`	—
`blur`	—
`loaderror`	`WajubError`
`resize`	height-related payload
`success`	transaction
`error`	`WajubError`
`statechange`	`{ state, method? }`
`methodchange`	`{ methodId? }`

Component types: card · mobileMoney · wallet · payment · address

`AppearanceConfig`

Full reference: Appearance.

Field	Values
`theme`	`stripe` · `night` · `flat` · `none`
`primaryColor`, `secondaryColor`, `backgroundColor`, …	CSS colors
`fontFamily`, `borderRadius`, `shadow`	CSS values
`buttonTextColor`, `inputBackgroundColor`, `inputBorderColor`, `textMutedColor`, `successColor`, `errorColor`	CSS colors
`colorScheme`	`light` · `dark` · `auto`
`labels`	`above` · `floating`
`disableAnimations`	`boolean`
`variables`	Design tokens → `--wj-*` CSS vars
`rules`	Selector → CSS declarations

Framework exports

Same SDK behavior across @wajub/react, @wajub/vue, @wajub/svelte:

Export	Description
`WajubProvider`	Load SDK once for subtree
`CheckoutEmbed`	Hosted checkout inline
`CardComponent`	Card fields
`PaymentComponent`	Method selector + form
`AddressComponent`	Address block
`MobileMoneyComponent`	Mobile Money form
`WalletComponent`	Apple Pay / Google Pay
`ComponentEmbed`	Generic component wrapper (React)
`useWajub()`	Access runtime (throws while loading)
`useWajubOptional()`	Safe access — `null` during SSR
`useConfirmPayment()`	Submit mounted component

Framework wrapper props

Prop	Applies to	Description
`className` / `class`	`CheckoutEmbed`, components	Wrapper CSS class
`style`	React `CheckoutEmbed`	Wrapper inline styles
`minHeight`	`CheckoutEmbed`, `ComponentEmbed`	Min height px (default `480`)
`onInstance`	React `ComponentEmbed`	`(instance) => void` ref callback

Live prop updates

Payment field components react to appearance, locale, and layout prop changes via instance.update(). CheckoutEmbed remounts only when sessionId changes — use an instance ref and update() for live hosted-checkout styling.

See framework pages: React · Vue · Svelte

Checkout states

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

Listen via onStateChange or component.on('statechange', …).

`WajubError`

Field	Description
`message`	Human-readable message
`type`	`api_error` · `authentication_error` · `invalid_request_error` · `payment_error` · `rate_limit_error`
`code`	Machine code
`decline_code`	Provider decline code when applicable
`retryable`	Whether retry may succeed
`param`	Related request field

Appearance Branding & theming Hosted checkout Payment fields TypeScript

Edit this page on GitHub

Need help?

Contact support GitHub Discussions Service Status

API reference

Complete public API for @wajub/js — global wajub, Wajub client, checkout instance, popup overlay, and payment fields.

30 min read

Global `wajub`

Available after loading https://js.wajub.com or loadWajub() from @wajub/js.

Member	Description
`wajub.mount(container, config)`	Inline hosted checkout → `CheckoutInstance`
`wajub.open(config)`	Modal overlay → `PopupInstance`
`wajub.checkout(config)`	Full-page redirect
`wajub.preload(sessionId, opts?)`	Preload checkout UI
`wajub.fetchSession(sessionId)`	Session preview (amount, methods, features)
`wajub.components(sessionId, opts?)`	Payment fields factory
`wajub.confirmPayment(opts)`	Submit mounted payment field(s)
`Wajub(keyOrSession)`	Client factory
`WajubError`	Normalized error class
`wajub.version`	SDK version string

`loadWajub()` (@wajub/js)

import { loadWajub, mount } from '@wajub/js';
import { loadWajub } from '@wajub/js/pure'; // no auto-load side effect

Export	Description
`loadWajub()`	Load runtime from CDN; returns `null` during SSR
`mount(container, config)`	Async helper — load + mount

Returns { wajub, Wajub } after load.

`Wajub()` client

Call	Result
`Wajub('pk_test_…')`	Client with `createPayment()`
`Wajub('trx_…')` / `Wajub.session('trx_…')`	Client bound to existing session
`Wajub({ publishableKey, sessionId })`	Combined client

Client methods

Method	Description
`createPayment(params)`	Create session (requires `pk_…`)
`useSession(sessionId)`	Switch active session
`fetchSession(sessionId?)`	Session preview
`preload(sessionId?, opts?)`	Preload UI
`mount(container, config?)`	Inline embed
`open(config?)`	Overlay
`checkout(config?)`	Redirect
`components(sessionId?, config?)`	Payment fields factory
`confirmPayment(opts?)`	Submit components
`initCheckout(opts)`	One-shot create + mount/open/redirect

`EmbeddedConfig` (mount / CheckoutEmbed)

Used by wajub.mount(), CheckoutEmbed, and as the base of PopupConfig.

Option	Type	Description
`sessionId`	`string`	Required — `authorization_token` from your backend
`locale`	`string`	`fr` · `en` · `es` · `pt` · `ar`
`layout`	`CheckoutLayout`	`classic` · `compact` · `tabs` · `accordion`
`appearance`	`AppearanceConfig`	Appearance
`embedOrigin`	`string`	Canonical site URL (multi-domain embeds)
`theme`	`EmbedTheme`	Deprecated — use `appearance`
`loadingText`	`string`	Placeholder text before `onReady`
`showLoading`	`boolean`	Show placeholder (default `true`)
`onReady`	`(instance) => void`	Checkout visible
`onSuccess`	`(transaction) => void`	Payment succeeded
`onError`	`(WajubError) => void`	Payment failed
`onLoadError`	`(WajubError) => void`	Invalid token / embed blocked
`onCancel`	`() => void`	Customer cancelled
`onExpired`	`() => void`	Session expired
`onBreakdown`	`(EmbedBreakdown) => void`	`{ subtotal, discount, tax, total, currency }`
`onStateChange`	`({ state, method }) => void`	State machine transition
`onMethodChange`	`({ methodId, method_id }) => void`	Payment method changed
`onResize`	`(height: number) => void`	Inline only — iframe height in px
`onClose`	`() => void`	Overlay dismissed (session still active)

`PopupConfig` (open / overlay)

Extends EmbeddedConfig with modal options for wajub.open():

Option	Type	Default	Description
`width`	`number`	`920`	Modal max-width (px)
`height`	`number`	`680`	Modal height (px)
`closeOnOverlay`	`boolean`	`false`	Close when clicking backdrop
`closeOnEscape`	`boolean`	`true`	Close on Escape key
`closeOnSuccess`	`boolean`	`true`	Auto-close after success (`onSuccess` fires first)

Plus all EmbeddedConfig options and callbacks.

Node.js

wajub.open({
sessionId,
width: 960,
height: 720,
closeOnOverlay: true,
closeOnSuccess: true,
appearance: { theme: 'night' },
onSuccess: (txn) => fulfillOrder(txn),
onClose: () => console.log('modal closed'),
});

`CheckoutInstance` / `PopupInstance`

Method	Description
`mount()`	Re-attach if unmounted
`unmount()`	Remove from DOM, keep instance
`destroy()`	Full teardown (alias: use on cleanup)
`update(partial)`	Update `locale`, `appearance`, `layout`, `currency`, deprecated `theme`
`getState()`	Current `CheckoutState`
`submit()`	Submit payment programmatically
`cancel()`	Cancel in-progress payment
`retry()`	Retry after failure
`selectMethod(methodId)`	Switch payment method
`close()`	Close overlay
`isOpen()`	Popup only — modal visible

`ComponentConfig` (payment fields)

Passed to wajub.components(sessionId, opts) and factory.create(type, config):

Option	Type	Description
`sessionId`	`string`	Required
`locale`	`string`	UI language
`componentOrigin`	`string`	Canonical origin (multi-domain), like `embedOrigin`
`appearance`	`AppearanceConfig`	Styling — Appearance
`layout`	`CheckoutLayout`	Method selector layout
`collectAddress`	`shipping` · `billing`	payment component — inline address collection
`addressMode`	`shipping` · `billing`	address component — label mode
`collectName`	`boolean`	Collect payer name on address component
`fields.phone`	`always` · `auto` · `never`	Phone field visibility
`onReady`	`(component) => void`	Component mounted
`onChange`	`(ComponentChangeEvent) => void`	`{ complete, empty, error?, value? }`
`onFocus`	`() => void`	Field focused
`onBlur`	`() => void`	Field blurred
`onLoadError`	`(WajubError) => void`	Load failed
`onSuccess`	`(transaction) => void`	Payment succeeded
`onError`	`(WajubError) => void`	Payment failed
`onMethodChange`	`({ methodId }) => void`	Method changed

`ComponentInstance`

Method	Description
`mount(container)`	Mount to DOM element or selector
`unmount()`	Remove from DOM
`destroy()`	Full teardown
`on(event, fn)`	Subscribe — see events below
`off(event, fn)`	Unsubscribe
`update(partial)`	Live update `locale`, `appearance`, `layout`
`focus()`	Focus first field
`blur()`	Blur active field
`submit()`	Submit component
`selectMethod(methodId)`	Switch method (payment component)
`getState()`	Current `CheckoutState`
`isComplete()`	All required fields valid
`getError()`	Current `WajubError` or `null`
`getValue()`	Address values `{ name, phone, address, mode }`

Component events

Event	Payload
`ready`	`ComponentInstance`
`change`	`{ complete?, empty?, error?, value? }`
`focus`	—
`blur`	—
`loaderror`	`WajubError`
`resize`	height-related payload
`success`	transaction
`error`	`WajubError`
`statechange`	`{ state, method? }`
`methodchange`	`{ methodId? }`

Component types: card · mobileMoney · wallet · payment · address

`AppearanceConfig`

Full reference: Appearance.

Field	Values
`theme`	`stripe` · `night` · `flat` · `none`
`primaryColor`, `secondaryColor`, `backgroundColor`, …	CSS colors
`fontFamily`, `borderRadius`, `shadow`	CSS values
`buttonTextColor`, `inputBackgroundColor`, `inputBorderColor`, `textMutedColor`, `successColor`, `errorColor`	CSS colors
`colorScheme`	`light` · `dark` · `auto`
`labels`	`above` · `floating`
`disableAnimations`	`boolean`
`variables`	Design tokens → `--wj-*` CSS vars
`rules`	Selector → CSS declarations

Framework exports

Same SDK behavior across @wajub/react, @wajub/vue, @wajub/svelte:

Export	Description
`WajubProvider`	Load SDK once for subtree
`CheckoutEmbed`	Hosted checkout inline
`CardComponent`	Card fields
`PaymentComponent`	Method selector + form
`AddressComponent`	Address block
`MobileMoneyComponent`	Mobile Money form
`WalletComponent`	Apple Pay / Google Pay
`ComponentEmbed`	Generic component wrapper (React)
`useWajub()`	Access runtime (throws while loading)
`useWajubOptional()`	Safe access — `null` during SSR
`useConfirmPayment()`	Submit mounted component

Framework wrapper props

Prop	Applies to	Description
`className` / `class`	`CheckoutEmbed`, components	Wrapper CSS class
`style`	React `CheckoutEmbed`	Wrapper inline styles
`minHeight`	`CheckoutEmbed`, `ComponentEmbed`	Min height px (default `480`)
`onInstance`	React `ComponentEmbed`	`(instance) => void` ref callback

Live prop updates

See framework pages: React · Vue · Svelte

Checkout states

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

Listen via onStateChange or component.on('statechange', …).

`WajubError`

Field	Description
`message`	Human-readable message
`type`	`api_error` · `authentication_error` · `invalid_request_error` · `payment_error` · `rate_limit_error`
`code`	Machine code
`decline_code`	Provider decline code when applicable
`retryable`	Whether retry may succeed
`param`	Related request field

Appearance Branding & theming Hosted checkout Payment fields TypeScript

Edit this page on GitHub

Need help?

Contact support GitHub Discussions Service Status

Global wajub

loadWajub() (@wajub/js)

Wajub() client

Client methods

EmbeddedConfig (mount / CheckoutEmbed)

PopupConfig (open / overlay)

CheckoutInstance / PopupInstance

ComponentConfig (payment fields)

ComponentInstance

Component events

AppearanceConfig

Framework exports

Framework wrapper props

Checkout states

WajubError

Global wajub

loadWajub() (@wajub/js)

Wajub() client

Client methods

EmbeddedConfig (mount / CheckoutEmbed)

PopupConfig (open / overlay)

CheckoutInstance / PopupInstance

ComponentConfig (payment fields)

ComponentInstance

Component events

AppearanceConfig

Framework exports

Framework wrapper props

Checkout states

WajubError

Global `wajub`

`loadWajub()` (@wajub/js)

`Wajub()` client

`EmbeddedConfig` (mount / CheckoutEmbed)

`PopupConfig` (open / overlay)

`CheckoutInstance` / `PopupInstance`

`ComponentConfig` (payment fields)

`ComponentInstance`

`AppearanceConfig`

`WajubError`

Global `wajub`

`loadWajub()` (@wajub/js)

`Wajub()` client

`EmbeddedConfig` (mount / CheckoutEmbed)

`PopupConfig` (open / overlay)

`CheckoutInstance` / `PopupInstance`

`ComponentConfig` (payment fields)

`ComponentInstance`

`AppearanceConfig`

`WajubError`