SDK reference

The complete surface of @wajub/js@1.8.1. 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.

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

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

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

WajubRuntime

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

wajub

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.

Client members

Factory statics

EmbeddedConfig

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

PopupConfig

Everything in EmbeddedConfig, plus the modal.

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

CheckoutInstance and PopupInstance

mount() and unmount() behave the same inline and in the overlay. A checkout that comes back is loaded again from its token: onReady fires once more, and the payment resumes where the session stands. Driving the instance says when submit() has no button to press.

ComponentConfig

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

Each callback is called just before the event of the same name. Passing one changes nothing else.

ComponentsFactory

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

ComponentInstance

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

Events

From 1.8.0, on() and off() type the payload of each event above through ComponentEventMap: card.on('statechange', (event) => event.state) needs no cast.

update({ frameTitle }) renames the iframe itself. The other three are sent to the component. error also carries submission_failed when a submission you asked for, with submit() or confirmPayment(), was refused before any charge.

ConfirmPaymentOptions

Resolves with { status, transaction }, transaction being a PaymentSuccess. Rejects with a WajubError carrying missing_component, wallet_not_supported or address_not_payment before anything is sent. After, it rejects with confirmation_timeout, or with the payment's own error: checkout_validation, submission_failed, payment_error, payment_cancelled, session_expired, component_unmounted, the provider's decline code, or the component's load error.

From Wajub.js 1.8.0, the time does not run while the payment waits on the payer (OTP_REQUIRED, PIN_REQUIRED, PHONE_REQUIRED, BIRTHDAY_REQUIRED, ADDRESS_REQUIRED, APPROVAL_REQUIRED, USSD_REQUIRED, 3DS_REQUIRED, PENDING), nor once the page leaves for the provider's (redirect). It starts over, whole, at the next step. Meanwhile, a component whose iframe has left the page without unmount() rejects with component_unmounted, as unmount() and destroy() do, and a component mounted again starts from INITIATED.

confirmation_timeout only stops the wait. It cancels nothing: the payment goes on and can still succeed. Before offering to pay again, listen for success on the component or wait for the payment.succeeded webhook.

PaymentSuccess

What onSuccess, the success event and confirmPayment() hand over. It is the checkout's own summary, not the API's payment object, and it comes from the browser: confirm the payment on your server, with GET /payments/{id} or the payment.succeeded webhook, before you deliver anything.

Amounts are in major units, like the API: 12.5 for 12.50 EUR, 1500 for 1 500 XAF. Before 1.6.0, onSuccess, onBreakdown and fetchSession() gave them in minor units, 1250 for 12.50 EUR, and onSuccess carried no id.

CreatePaymentParams

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

CreatePaymentResult

InitCheckoutOptions

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

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.

ClientSignals

What signals() resolves to, from 1.6.0: an opaque object. For a charge you make from your own server with a secret key, call signals() in the payer's browser, send the result to your server unchanged and pass it as data._client, so that Shield scores the payer rather than your server. Do not build, edit or store it. signals() never rejects.

AppearanceConfig

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

States

getState() and onStateChange both speak this vocabulary.

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

A new instance reports INITIATED until the checkout says otherwise. PIN_REQUIRED, PHONE_REQUIRED, BIRTHDAY_REQUIRED and ADDRESS_REQUIRED are the steps some providers add after the first submit: a wallet PIN, a phone number to confirm, a date of birth, an address.

On the hosted checkout the outcome does not arrive through onStateChange: it arrives through onSuccess, onError, onCancel or onExpired, and getState() keeps the last step before it.

WajubError

Every rejection and every error callback receives one.

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.

Codes a checkout sends when it cannot start

onLoadError on the hosted checkout, and onLoadError or the loaderror event on a payment field, receive one of these. Nothing was paid.

With readyTimeout, a payment field's onLoadError and loaderror can also receive ready_timeout, which the SDK raises itself when the field is not ready in time.

For one of the three session_terminal_ codes, start a new payment and mount the field on its token. A field whose session is already paid shows its notice and sends ready, not an error. The field's notice, its three codes and component_origin_missing come with the checkout shipped with Wajub.js 1.8.0, whatever the version on your page: before, such a field sent nothing.

Codes a payment can end with

onError, the error event and a confirmPayment() rejection carry the provider's decline code when there is one, insufficient_funds for example. Otherwise they carry one of these.

WajubPay, deprecated

The script also exposes window.WajubPay.create(), an older way to mount an inline checkout. It is deprecated since 1.6.0 and will be removed in a future version: its first call writes a warning to the console. Use mount(), open() or a framework component instead.

Framework packages

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

@wajub/angular, from 1.8.1, exports the Angular forms of the same set.

In Angular, the props are inputs and outputs of the same names: every option is an input, every callback an output named without on, such as (loadError) for onLoadError, and onBeforeSubmit is the beforeSubmit input, since an output cannot answer.

From 1.8.0, every option of ComponentConfig is a prop of the field components, the callbacks included, and the handlers you pass are read when the event comes. appearance, locale, layout and frameTitle reach the mounted field through update(), only when their content changes. A new sessionId, type, variant, fields, loader, readyTimeout, collectAddress, addressMode or collectName mounts a new field in the same container. CheckoutEmbed sends appearance, theme, locale and layout through update(), and loads again for a new sessionId or embedOrigin. @wajub/angular does the same from its first version, 1.8.1.

Each wrapper, Angular's included, also re-exports every type of @wajub/js, so import type { PaymentSuccess } from '@wajub/react' works as well as from @wajub/js.

useWajubOptional() returns the runtime or null in React. From 1.6.0 it returns a ref in Vue and a store in Svelte, both null until the runtime has loaded. In Angular, the runtime signal of WajubService holds null until then.

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