SDK reference

Every export, option, method, type, state and error code of @wajub/js. The guide pages explain when to use each piece.

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 });

WajubRuntime

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

wajub

These are synchronous once you hold the runtime.

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. When a checkout comes back, 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

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 frame for screen readers.

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 submitted. 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, a decline code, or the component's load error.

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 your page has left for the provider's (redirect). A component removed from the page while you wait rejects with component_unmounted, as unmount() and destroy() do.

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.

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.

saved_methods lists the methods a customer paid with before, and only on a payment whose customer your server named: one created with POST /payments and your secret key (or a restricted key) with a customer, one activated with POST /payments/{id}/activate, or the payment of an invoice linked to one of your customers. A payment link, a payment created with your publishable key and an invoice addressed to a name only never list any, because the e-mail typed on those pages may be someone else's. Paying with a saved method on such a payment is refused before any charge, with HTTP 422, the code saved_method_not_allowed and the message "Saved payment methods cannot be used for this payment."

ClientSignals

What signals() resolves to: an opaque object holding the payer's device signals, for a charge you make from your own server. Do not build, edit or store it. How to send it is on Shield.

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 payment moves. PIN_REQUIRED, PHONE_REQUIRED, BIRTHDAY_REQUIRED and ADDRESS_REQUIRED are the steps some payments 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.

Codes raised by the SDK itself

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.

Codes a payment can end with

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

Framework packages

@wajub/react, @wajub/vue and @wajub/svelte export these, each in its framework's idiom.

@wajub/angular exports these.

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.

Every option of ComponentConfig is a prop of the field components, the callbacks included, and a new handler takes over without a reload. A change to appearance, locale, layout or frameTitle applies to the mounted field without a reload. A new sessionId, type, variant, fields, loader, readyTimeout, collectAddress, addressMode or collectName mounts a new field in the same container. CheckoutEmbed applies appearance, locale and layout the same way, and loads again for a new sessionId.

Each framework package 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. 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: React, Vue, Svelte, Angular.