Référence API

Tous les exports, options, méthodes, types, états et codes d'erreur de @wajub/js.

Toute la surface de @wajub/js@1.4.0. Les guides expliquent quand utiliser chaque élément. Cette page les répertorie tous.

Deux façons d'accéder à la même API

Le runtime est un objet unique. Vous pouvez importer des helpers qui le chargent pour vous, ou le conserver vous-même.

Les helpers ou le 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 de `@wajub/js`	Renvoie	Remarques
`mount(container, config)`	`Promise<CheckoutInstance \| null>`	`null` sur le serveur
`open(config)`	`Promise<PopupInstance \| null>`	`null` sur le serveur
`checkout(config)`	`Promise<void \| null>`	Redirige la page
`components(sessionId, options?)`	`Promise<ComponentsFactory \| null>`	`null` sur le serveur
`confirmPayment(options)`	`Promise<{ status, transaction? }>`	Rejette avec `WajubError`
`fetchSession(sessionId)`	`Promise<SessionPreview>`	Fonctionne avant tout montage
`preload(sessionId, options?)`	`Promise<void \| null>`	`{ iframe?: boolean }`
`getVersion()`	`Promise<string \| null>`	La version du runtime chargé
`getCheckoutOrigin()`	`Promise<string \| null>`	L'origine qui sert le checkout
`loadWajub(options?)`	`Promise<WajubRuntime \| null>`	`{ jsOrigin?, jsUrl? }`
`WajubError`	Classe	Chaque rejet en est une instance

loadWajub.setLoadParameters({ jsOrigin }) définit l'origine une fois, avant le premier appel.

Le runtime `WajubRuntime`

La valeur résolue par loadWajub() et placée dans window par le script du CDN.

Membre	Description
`wajub`	L'objet du SDK, décrit dans le tableau ci-dessous
`Wajub`	La fabrique de clients
`WajubError`	La classe d'erreur

L'objet `wajub`

Membre	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`	La fabrique `Wajub`, le même objet
`version`	La chaîne de version du runtime
`sdkMajor`	La version majeure
`checkoutOrigin`	L'origine des iframes
`createHeadless`	Supprimé dans la version 2.1, déclenche une erreur lors d'un appel

Ces méthodes sont synchrones, car le runtime est déjà chargé lorsque vous y accédez.

Le client `Wajub()`

Un client conserve une clé publique, une session ou les deux pour éviter de les répéter.

Appel	Résultat
`Wajub('pk_test.…')`	Un client capable d'appeler `createPayment()`
`Wajub.session(token)`	Un client lié à une session existante
`Wajub({ publishableKey, sessionId })`	Les deux à la fois

Option	Rôle
`sessionId`	Le `authorization_token` de votre serveur
`publishableKey`	Votre clé `pk.` ou `pk_test.`
`apiKey`	Alias obsolète de `publishableKey`
`apiBase`	Remplace l'origine de l'API. Valeur par défaut : `https://api.wajub.com`
`paymentsUrl`	Remplace l'URL complète de `POST /payments`
`useCheckoutProxy`	Passe par le propre endpoint `/api/payments` du checkout
`componentOrigin`	Origine canonique des champs de paiement

Membres du client

Membre	Rôle
`publishableKey`, `sessionId`, `environment`	Les valeurs actuellement conservées par le client
`apiBase`, `checkoutOrigin`	Les origines contactées
`useSession(sessionId)`	Lie une autre session et renvoie le client
`createPayment(params)`	`POST /payments` avec la clé publique
`initCheckout(options)`	Crée et affiche le paiement en un appel
`fetchSession(sessionId?)`	Aperçu de la session
`preload(sessionId?, options?)`	Précharge le runtime
`mount`, `open`, `checkout`	Les trois modes hébergés, avec la session déjà liée
`components(sessionIdOrConfig?, config?)`	La fabrique de champs
`confirmPayment(options?)`	Soumet un composant monté

Méthodes statiques de la fabrique

Membre	Rôle
`Wajub.session(sessionId, options?)`	Un client lié à une session
`Wajub.parsePublishableKey(key)`	`{ key, environment }`, déclenche une erreur avec une clé secrète
`Wajub.createPayment(key, params, options?)`	Un appel unique, sans client à conserver

La configuration `EmbeddedConfig`

Utilisée par mount(), par CheckoutEmbed dans chaque framework et comme base de PopupConfig.

Option	Type	Valeur par défaut
`sessionId`	`string`	Obligatoire
`locale`	`string`	Valeur par défaut de la session
`layout`	`CheckoutLayout`	Valeur par défaut de la session
`appearance`	`AppearanceConfig`	Identité visuelle de la session
`embedOrigin`	`string`	Origine de la page actuelle
`loadingText`	`string`	Vide
`showLoading`	`boolean`	`true`
`theme`	`EmbedTheme`	Dérivé de `appearance`, obsolète

Callback	Reçoit
`onReady`	`CheckoutInstance`
`onSuccess`	`Record<string, unknown>`, la transaction
`onError`	`WajubError`
`onLoadError`	`WajubError`
`onCancel`	Rien
`onExpired`	Rien
`onStateChange`	`{ state?: CheckoutState, method?: string }`
`onMethodChange`	`{ methodId?, method_id? }`
`onBreakdown`	`EmbedBreakdown`
`onResize`	`height: number`, uniquement en ligne
`onClose`	Rien, uniquement en superposition

La configuration `PopupConfig`

Tout le contenu de EmbeddedConfig, avec la fenêtre modale en plus.

Option	Type	Valeur par défaut
`width`	`number`	`920`
`height`	`number`	`680`
`closeOnOverlay`	`boolean`	`false`
`closeOnEscape`	`boolean`	`true`
`closeOnSuccess`	`boolean`	`true`
`closeOnCancel`	`boolean`	`true`
`closeOnExpired`	`boolean`	`true`

Les trois options de résultat closeOn s'exécutent après votre callback, jamais avant.

Les instances `CheckoutInstance` et `PopupInstance`

Méthode	Rôle
`mount()`	Remonte l'instance après `unmount()`
`unmount()`	Retire l'élément du DOM et conserve l'instance
`destroy()`	Détruit entièrement l'instance
`update(partial)`	`locale`, `appearance`, `currency`, `layout` et `theme`, qui est obsolète
`getState()`	Le `CheckoutState` actuel
`submit()`	Soumet le formulaire
`cancel()`	Annule le paiement en cours
`retry()`	Lance une nouvelle tentative après un échec
`selectMethod(methodId)`	Change de moyen de paiement
`close()`	Ferme la superposition
`isOpen()`	Indique si la fenêtre modale est visible, uniquement en superposition

update({ layout }) est stocké, pas envoyé

locale, appearance et currency atteignent le checkout. layout met seulement à jour la configuration locale. Les moyens conservent donc la disposition utilisée lors de leur montage. Remontez l'instance pour la modifier.

La configuration `ComponentConfig`

Transmise à wajub.components(sessionId, options) comme valeurs par défaut et à factory.create(type, config) pour chaque composant.

Option	Type	S'applique à
`sessionId`	`string`	Obligatoire
`locale`	`string`	Tous
`appearance`	`AppearanceConfig`	Tous
`layout`	`CheckoutLayout`	`payment`
`componentOrigin`	`string`	Tous, avec l'origine de la page comme valeur par défaut
`collectAddress`	`shipping` or `billing`	`payment`
`addressMode`	`shipping` or `billing`	`address`
`collectName`	`boolean`	`payment`, `address`
`fields.phone`	`always`, `auto`, `never`	`payment`, `address`

Callback	Reçoit
`onReady`	`ComponentInstance`
`onChange`	`ComponentChangeEvent`
`onFocus`, `onBlur`	Rien
`onLoadError`	`WajubError`
`onSuccess`	La transaction
`onError`	`WajubError`
`onMethodChange`	`{ methodId? }`

La fabrique `ComponentsFactory`

Membre	Description
`sessionId`	La session héritée par chaque composant
`create(type, config?)`	Une nouvelle `ComponentInstance`

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

L'instance `ComponentInstance`

Chaque méthode, sauf les méthodes de lecture, renvoie l'instance. Les appels peuvent donc être enchaînés.

Méthode	Renvoie
`mount(container)`	L'instance
`unmount()`, `destroy()`	Rien
`on(event, fn)`, `off(event, fn)`	L'instance
`update({ locale, appearance, layout })`	L'instance
`focus()`, `blur()`, `submit()`	L'instance
`selectMethod(methodId)`	L'instance
`getState()`	`CheckoutState`
`isComplete()`	`boolean`
`getError()`	`WajubError` or `null`
`getValue()`	`ComponentAddressValue` or `null`

Événements

Événement	Payload
`ready`	`ComponentInstance`
`change`	`ComponentChangeEvent`
`focus`, `blur`	Rien
`loaderror`	`WajubError`
`resize`	`{ height }`
`success`	La transaction
`error`	`WajubError`
`statechange`	`{ state, method }`
`methodchange`	`{ methodId }`

Les options `ConfirmPaymentOptions`

Option	Type	Valeur par défaut
`sessionId`	`string`	Obligatoire
`components`	`ComponentInstance`	Obligatoire, un composant monté
`timeout`	`number`	`60000` millisecondes, `0` attend indéfiniment
`callback`	`string`	Obsolète, jamais lu

Se résout avec { status, transaction }. Rejette avec une WajubError contenant missing_component, wallet_not_supported, address_not_payment ou confirmation_timeout.

Les paramètres `CreatePaymentParams`

Les données envoyées par client.createPayment(). Il s'agit des mêmes champs que POST /payments, limités à ceux qu'un navigateur peut définir.

Champ	Type
`amount`	`number`, obligatoire
`currency`	`string`, obligatoire
`reference`	`string`
`description`	`string`
`customer`	`{ email?, name?, phone?, country? }`
`bearer`	`merchant` ou `customer`, la personne qui paie les frais
`callback`	URL HTTPS, uniquement pour le flux avec redirection
`metadata`	`Record<string, string>`

Le résultat `CreatePaymentResult`

Champ	Description
`sessionId`	Passez cette valeur à `mount`, `open` ou `components`
`authorizationToken`	La même valeur, sous le nom utilisé par l'API
`authorizationUrl`	La page hébergée ou `null`
`transaction`	L'objet de transaction ou `null`
`raw`	La réponse brute de l'API

Les options `InitCheckoutOptions`

Crée et affiche le paiement en un seul appel. Tout le contenu de EmbeddedConfig s'applique aussi.

Option	Type	Rôle
`mode`	`inline`, `overlay`, `redirect`	Mode d'affichage du checkout
`container`	`string` ou `HTMLElement`	Obligatoire pour `inline`
`sessionId`	`string`	Ignore `createPayment()`
`payment`	`CreatePaymentParams`	Utilisé en l'absence de `sessionId`
`checkout`	`Partial<EmbeddedConfig>`	Options de l'intégration elle-même

Se résout avec { session, instance } et déclenche missing_container lorsque le mode inline n'a aucun emplacement de montage.

L'aperçu `SessionPreview`

La valeur résolue par fetchSession(sessionId). Lisez-la avant le montage pour afficher un montant, le nom d'un marchand ou une bannière de sandbox.

Champ	Type
`session_id`	`string`
`status`	`string`
`environment`	`sandbox` ou `live`
`amount`	`number`
`currency`	`string`
`merchant_name`	`string`
`payment_methods`	`Array<{ id, type, label }>`
`saved_methods`	`Array<{ id, type, label }>`, pour les clients existants
`features`	`Record<string, boolean>`

La configuration `AppearanceConfig`

La liste complète des clés, les préréglages et les règles de filtrage se trouvent dans Apparence.

Groupe	Clés
Préréglage	`theme` : `stripe`, `night`, `flat`, `none`
Couleur	`primaryColor`, `secondaryColor`, `backgroundColor`, `buttonTextColor`, `inputBackgroundColor`, `inputBorderColor`, `textMutedColor`, `successColor`, `errorColor`
Forme	`fontFamily`, `borderRadius`, `shadow`
Comportement	`colorScheme`, `labels`, `disableAnimations`
Jetons	`variables`, seize clés associées à `--wj-*`
Sélecteurs	`rules`, uniquement `.Input` et `.Label`

États

getState() et onStateChange utilisent tous deux ce vocabulaire.

CheckoutState

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

Une nouvelle instance indique INITIATED tant que le checkout ne signale pas un autre état.

L'erreur `WajubError`

Chaque rejet et chaque callback d'erreur en reçoit une.

Champ	Type
`message`	`string`, rédigé pour une personne
`type`	`api_error`, `authentication_error`, `invalid_request_error`, `payment_error`, `rate_limit_error`
`code`	`string`, le nom interprété par la machine
`decline_code`	`string` ou `null`, envoyé par le prestataire
`retryable`	`boolean`
`param`	`string` ou `null`, le champ en cause

WajubError.fromPayload(payload) en construit une depuis un objet brut, et toJSON() le restitue.

Codes déclenchés par le SDK

Ces erreurs n'atteignent jamais le réseau. Elles signalent des erreurs d'intégration.

Code	Cause
`secret_key_in_browser`	Une clé `sk.` passée à `Wajub()`
`invalid_publishable_key`	Une clé qui n'est pas publique
`invalid_init`	Une clé secrète passée au constructeur du client
`missing_publishable_key`	`createPayment()` appelé sans clé
`missing_session_token`	Un appel qui exige une session alors qu'aucune n'est définie
`missing_session`	Aucun `sessionId` sur le client
`missing_container`	`initCheckout` en mode `inline` sans emplacement de montage
`missing_component`	`confirmPayment` sans composant pouvant être soumis
`wallet_not_supported`	`confirmPayment` sur un composant `wallet`
`address_not_payment`	`confirmPayment` sur un composant `address`
`confirmation_timeout`	Aucun résultat avant la fin de `timeout`
`components_unavailable`	Le runtime des composants ne s'est pas chargé
`load_error`	Échec du chargement de l'iframe du checkout

Packages des frameworks

Les trois wrappers exportent le même ensemble en respectant les conventions de chaque framework.

Export	Description
`WajubProvider`	Charge le runtime une fois pour une sous-arborescence
`CheckoutEmbed`	Le checkout hébergé, affiché en ligne
`CardComponent`, `MobileMoneyComponent`, `WalletComponent`, `PaymentComponent`, `AddressComponent`	Un groupe de champs chacun
`ComponentEmbed`	La même chose, avec `type` comme prop
`useWajub`, `useWajubOptional`, `useLoadWajub`	Donnent accès au runtime
`useConfirmPayment`	Soumet un composant de champs

Prop du wrapper	S'applique à	Valeur par défaut
`className` dans React et Svelte, `class` dans Vue	Les deux	aucune
`style`	Les deux	aucune
`minHeight`	`CheckoutEmbed`	`480`
`minHeight`	Composants de champs	`200`
`onInstance`	Composants de champs	aucune, appelée avec `null` au démontage

Chaque package possède sa propre page, car leurs différences sont réelles : React, Vue, Svelte.

Pages associées

Deux façons d'accéder à la même API

Le runtime WajubRuntime

L'objet wajub

Le client Wajub()

Membres du client

Méthodes statiques de la fabrique

La configuration EmbeddedConfig

La configuration PopupConfig

Les instances CheckoutInstance et PopupInstance

La configuration ComponentConfig

La fabrique ComponentsFactory

L'instance ComponentInstance