Référence du SDK
Tous les exports, options, méthodes, types, états et codes d'erreur de @wajub/js.
Toute la surface de @wajub/js@1.8.1. 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.
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 |
signals() | Promise<ClientSignals> | Pour un débit côté serveur : envoyez le résultat à votre serveur et transmettez-le dans data._client. Ne rejette jamais |
preload(sessionId, options?) | Promise<void | null> | { iframe?: boolean } |
appearanceFrom(container, source?) | Promise<AppearanceConfig | null> | Depuis la 1.8.0. Ce que appearance.inherit lirait pour un composant dans container. null sur le serveur, {} avec un Wajub.js antérieur à 1.8.0 |
componentReserveHeight(type, variant?, fields?) | number | Depuis la 1.8.0. La place que tient loader: 'skeleton', en px. Synchrone : l'estimation tant que le runtime n'est pas chargé, puis la réponse du runtime, qui peut être une hauteur apprise sur la page |
componentEstimatedHeight(type, variant?, fields?) | number | Depuis la 1.8.0. L'estimation seule, la même sur le serveur et dans le navigateur, jamais une hauteur apprise sur la page : ce que tiennent un rendu serveur et son hydratation |
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 | Déclarée dans les types seulement | Non exportée à l'exécution, lisez-la dans loadWajub() |
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> |
signals | () => Promise<ClientSignals> |
preload | (sessionId, options?) => void |
appearanceFrom | (container, source?) => AppearanceConfig, depuis la 1.8.0. {} quand il n'y a rien à lire, ne lève jamais d'erreur |
componentReserveHeight | (type, variant?, fields?) => number, depuis la 1.8.0. La hauteur qu'un composant de ce type a prise au repos sur la page, sinon son estimation |
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é, 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_test.. Une clé live pk. n'est pas reconnue en 1.8.1 |
apiKey | Alias obsolète de publishableKey |
apiBase | Remplace l'origine de l'API. Valeur par défaut : https://api.wajub.com |
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 |
signals() | Ce dont un débit côté serveur a besoin depuis le navigateur du payeur, à transmettre dans data._client |
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 |
appearanceFrom(container, source?) | Ce que appearance.inherit lirait, depuis la 1.8.0 |
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 |
Wajub.signals() | Ce dont un débit fait depuis votre serveur a besoin depuis le navigateur du payeur, à transmettre dans data._client |
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 | Votre image de marque du Dashboard. Depuis la 1.8.0, inherit est lu autour du conteneur pour mount(), sur toute la page pour open() |
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 | PaymentSuccess |
onError | WajubError, un paiement qui a échoué, ou nothing_to_submit lorsque submit() n'avait aucun bouton sur lequel appuyer |
onLoadError | WajubError, un checkout qui n'a jamais démarré : session_not_found, session_terminal_expired ou load_error. Juste après, la superposition se ferme ou le checkout en ligne quitte la page, sans onClose |
onCancel | Rien |
onExpired | Rien |
onStateChange | { state?: CheckoutState, method?: string } |
onMethodChange | { methodId?, method_id? } |
onBreakdown | EmbedBreakdown, { subtotal, discount, tax, total, currency } en unités normales |
onResize | height: number, uniquement en ligne |
onClose | Rien. La superposition a été fermée, ou un checkout en ligne a été terminé par le bouton Terminé du payeur ou par close() |
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(). Sans effet si elle est déjà montée, ou après destroy() ou close() |
unmount() | Retire l'élément du DOM et conserve l'instance. En superposition, onClose n'est pas appelé |
destroy() | Détruit entièrement l'instance. mount() ne la ramène plus |
update(partial) | locale, appearance, currency, layout et theme, qui est obsolète. Depuis la 1.8.0, appearance est fusionnée avec l'actuelle : une clé donnée à undefined ou null est effacée, et appearance: undefined ou null efface tout. Un nouveau preset theme remplace le précédent et ce qu'il apportait |
getState() | Le CheckoutState actuel |
submit() | Appuie sur le bouton de paiement du moyen en cours. S'il n'y a aucun bouton sur lequel appuyer, rien n'est pressé et onError reçoit nothing_to_submit |
cancel() | Annule le paiement en cours |
retry() | Lance une nouvelle tentative après un échec |
selectMethod(methodId) | Change de moyen de paiement |
close() | Termine le checkout, en ligne ou en superposition, et appelle onClose. destroy() le termine sans callback |
isOpen() | Indique si le checkout est encore ouvert, en ligne comme en superposition : false une fois terminé (réussite, annulation, expiration, fermeture) |
mount() et unmount() se comportent de la même façon en ligne et en superposition. Un checkout
remonté est rechargé à partir de son jeton : onReady se déclenche à nouveau, et le paiement
reprend là où en est la session.
Piloter l'instance précise quand
submit() n'a aucun bouton sur lequel appuyer.
update({ layout }) atteint le checkout depuis la 1.8.0
Depuis Wajub.js 1.8.0, update({ layout }) redispose les moyens, en ligne comme dans la
superposition. Auparavant, layout mettait seulement à jour la configuration locale : les moyens
gardaient la disposition de leur montage jusqu'à ce que unmount() puis mount() recharge le
checkout.
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 |
fields.customer | auto ou external | Tous sauf address |
fields.country | ISO 3166 alpha-2 | mobileMoney, payment |
fields.operator | choose ou detect | mobileMoney, payment |
variant | default ou fields | Tous sauf address. Transmis par les enveloppes Vue et Svelte depuis la 1.5.1. Depuis la 1.7.2, fields ne fixe aucun minimum de 120px à l'iframe |
frameTitle | string | Tous. Le nom de l'iframe pour les lecteurs d'écran, Wajub <type> component par défaut. À partir de la 1.7.0, enveloppes comprises |
loader | none ou skeleton | Tous, depuis la 1.8.0. none par défaut, skeleton dans les enveloppes de framework. Charger sans décaler la page |
readyTimeout | number, en millisecondes | Tous, depuis la 1.8.0. Sans ready à temps, onLoadError et loaderror reçoivent ready_timeout. 0 ou absent : jamais, et un squelette skeleton laisse quand même place à l'iframe au bout de 15 secondes, sans erreur |
| Callback | Reçoit |
|---|---|
onBeforeSubmit | Rien. Renvoyez false, ou levez une exception, pour arrêter le débit. 30 secondes au plus. Tous sauf address |
onReady | ComponentInstance |
onChange | ComponentChangeEvent |
onFocus, onBlur | Rien |
onLoadError | WajubError : un code envoyé par un checkout qui ne peut pas démarrer, ou ready_timeout avec readyTimeout |
onSuccess | La transaction |
onError | WajubError |
onMethodChange | { methodId? } |
onStateChange | ComponentStateChangeEvent, { state, method? }, depuis la 1.8.0 |
onResize | { height }, depuis la 1.8.0. Le onResize du checkout hébergé reçoit le nombre lui-même |
onRedirect | ComponentRedirectEvent, { url, method }, depuis la 1.8.0. La page part juste après, même si le callback lève une erreur |
Chaque callback est appelé juste avant l'événement du même nom. En passer un ne change rien d'autre.
La fabrique ComponentsFactory
| Membre | Description |
|---|---|
sessionId | La session héritée par chaque composant |
create(type, config?) | Une nouvelle ComponentInstance |
Types. card, mobileMoney, bankTransfer, crypto, 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, frameTitle }) | L'instance. Depuis la 1.8.0, appearance est fusionnée comme sur le checkout hébergé |
focus(), blur(), submit() | L'instance. Depuis la 1.8.0, focus() pendant que le chargeur skeleton est affiché place le focus dans le formulaire dès qu'il est prêt, sauf si le payeur a agi entre-temps |
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 : un code envoyé par un checkout qui ne peut pas démarrer, ou ready_timeout avec readyTimeout |
resize | { height } |
success | PaymentSuccess |
error | WajubError |
statechange | ComponentStateChangeEvent, { state, method? } |
methodchange | { methodId } |
redirect | ComponentRedirectEvent, { url, method }. À partir de la 1.7.0, juste avant que Wajub.js emmène votre page vers la page du prestataire |
Depuis la 1.8.0, on() et off() typent la donnée de chaque événement ci-dessus avec
ComponentEventMap : card.on('statechange', (event) => event.state) se passe de conversion.
update({ frameTitle }) renomme l'iframe elle-même. Les trois autres sont envoyés au composant.
error porte aussi submission_failed quand un envoi que vous avez demandé, avec submit() ou
confirmPayment(), a été refusé avant tout débit.
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. Depuis la 1.8.0, suspendu pendant que le paiement attend le payeur |
callback | string | Obsolète, jamais lu |
Se résout avec { status, transaction }, transaction étant un PaymentSuccess.
Rejette avec une WajubError contenant
missing_component, wallet_not_supported ou address_not_payment avant tout envoi. Ensuite,
rejette avec confirmation_timeout, ou avec l'erreur du paiement lui-même :
checkout_validation, submission_failed, payment_error, payment_cancelled,
session_expired, component_unmounted, le code de refus du prestataire, ou l'erreur de
chargement du composant.
Depuis Wajub.js 1.8.0, le temps ne court pas pendant que le paiement attend le payeur
(OTP_REQUIRED, PIN_REQUIRED, PHONE_REQUIRED, BIRTHDAY_REQUIRED, ADDRESS_REQUIRED,
APPROVAL_REQUIRED, USSD_REQUIRED, 3DS_REQUIRED, PENDING), ni une fois que la page part chez
le prestataire (redirect). Il repart de zéro, entier, à l'étape suivante. Pendant ce temps, un
composant dont l'iframe a quitté la page sans unmount() rejette avec component_unmounted, comme
unmount() et destroy(), et un composant remonté repart de INITIATED.
confirmation_timeout ne fait qu'arrêter l'attente. Il n'annule rien : le paiement continue et
peut encore réussir. Avant de proposer de payer à nouveau, écoutez success sur le composant ou
attendez le webhook payment.succeeded.
L'objet PaymentSuccess
Ce que remettent onSuccess, l'événement success et confirmPayment(). C'est le résumé propre au
checkout, pas l'objet paiement de l'API, et il vient du navigateur : confirmez le paiement sur votre
serveur, avec GET /payments/{id} ou le webhook payment.succeeded, avant de livrer quoi que ce
soit.
| Champ | Type | Contenu |
|---|---|---|
id | string | L'identifiant Wajub du paiement, celui que prend GET /payments/{id} |
reference | string | Votre référence, celle envoyée sur POST /payments |
amount | number | Ce que le payeur a payé, frais compris quand il les supporte, en unités normales |
currency | string | Code ISO 4217 |
method | string | La famille du moyen : mobile_money, card…, unknown quand la session était déjà payée |
status | "success" | Toujours success |
timestamp | string | Fin du paiement, au format ISO 8601 |
receipt_url | string | Le reçu hébergé du payeur, si vos reçus sont activés |
Les montants sont en unités normales, comme dans l'API : 12.5 pour 12,50 EUR, 1500 pour
1 500 XAF. Avant la 1.6.0, onSuccess, onBreakdown et fetchSession() les donnaient en unités
mineures, 1250 pour 12,50 EUR, et onSuccess ne portait pas d'id.
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? }, obligatoire avec un email ou un phone, sinon l'API répond 422 |
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, en unités normales comme dans l'API |
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> |
L'objet ClientSignals
Ce que renvoie signals(), à partir de la 1.6.0 : un objet opaque. Pour un débit que vous faites
depuis votre propre serveur avec une clé secrète, appelez signals() dans le navigateur du payeur,
envoyez le résultat tel quel à votre serveur et transmettez-le dans data._client, afin que
Shield note le payeur et non votre serveur. Ne le
construisez pas, ne le modifiez pas et ne le stockez pas. signals() ne rejette jamais.
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. Depuis la 1.7.1, light, dark, system ou auto est lu comme colorScheme quand celui-ci n'est pas donné |
| Couleur | primaryColor, secondaryColor, backgroundColor, buttonTextColor, inputBackgroundColor, inputBorderColor, textMutedColor, successColor, errorColor |
| Forme | fontFamily, borderRadius, shadow |
| Comportement | colorScheme, labels, disableAnimations |
| Jetons | variables, seize clés de jetons de design |
| Sélecteurs | rules, uniquement .Input et .Label |
| Votre page | inherit, depuis la 1.8.0 : true, ou un InheritSource, { input?, label?, button?, background? }, chacun un sélecteur CSS ou un élément. Reprendre le style de votre page |
États
getState() et onStateChange utilisent tous deux ce vocabulaire.
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, EXPIREDUne nouvelle instance indique INITIATED tant que le checkout ne signale pas un autre état.
PIN_REQUIRED, PHONE_REQUIRED, BIRTHDAY_REQUIRED et ADDRESS_REQUIRED sont les étapes que
certains prestataires ajoutent après le premier envoi : le code PIN d'un portefeuille, un numéro à
confirmer, une date de naissance, une adresse.
Sur le checkout hébergé, l'issue ne passe pas par onStateChange : elle arrive par onSuccess,
onError, onCancel ou onExpired, et getState() garde la dernière étape qui la précède.
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 | Wajub() appelé sans clé publique ni jeton de session |
missing_publishable_key | createPayment() appelé sans clé |
missing_session_token | createPayment() a reçu une réponse sans jeton de session |
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. Le paiement continue et peut encore réussir |
ready_timeout | Depuis la 1.8.0, un champ de paiement n'a pas envoyé ready avant la fin de readyTimeout. Arrive à onLoadError et à loaderror, et peut être retenté |
component_unmounted | Le composant a été démonté ou détruit pendant que confirmPayment l'attendait. Depuis la 1.8.0, aussi quand son iframe a quitté la page pendant une étape qui attend le payeur |
components_unavailable | Le runtime des composants ne s'est pas chargé |
load_error | Échec du chargement de l'iframe du checkout |
Codes envoyés par un checkout qui ne peut pas démarrer
onLoadError sur le checkout hébergé, et onLoadError ou l'événement loaderror sur un champ de
paiement, reçoivent l'un de ces codes. Rien n'a été payé.
| Code | Cause |
|---|---|
session_not_found | Le jeton est inconnu, ou la session n'a pas pu être lue |
session_terminal_expired | Le paiement est terminé et son jeton n'est plus valide. Sur un champ de paiement, la session a expiré sans être payée, et le champ affiche son message |
session_terminal_cancelled | Champs de paiement uniquement, la session était déjà annulée. Le champ affiche son message |
session_terminal_failed | Champs de paiement uniquement, la session s'était déjà terminée sur un paiement échoué. Le champ affiche son message |
component_origin_missing | Champs de paiement uniquement, le champ ne peut pas savoir dans quelle page il se trouve : une URL construite à la main, ou une page qui n'envoie pas de referrer. Montez-le avec Wajub.js |
invalid_component | Champs de paiement uniquement, un type de composant qui n'existe pas |
method_unavailable | Champs de paiement uniquement, la session ne propose aucun moyen que ce composant accepte |
Avec readyTimeout, onLoadError et loaderror d'un champ de paiement peuvent aussi recevoir
ready_timeout, que le SDK lève lui-même quand le champ n'est pas prêt à temps.
Pour l'un des trois codes session_terminal_, créez un nouveau paiement et montez le champ sur son
jeton. Un champ dont la session est déjà payée affiche son message et envoie ready, pas une
erreur. Le message du champ, ses trois codes et component_origin_missing arrivent avec le
checkout livré avec Wajub.js 1.8.0, quelle que soit la version de votre page : avant, un tel champ
n'envoyait rien.
Codes de fin d'un paiement
onError, l'événement error et un rejet de confirmPayment() portent le code de refus du
prestataire quand il en donne un, insufficient_funds par exemple. Sinon, ils portent l'un de
ces codes.
| Code | Cause |
|---|---|
payment_declined | Le prestataire a refusé le paiement sans motif plus précis |
blocked | Refusé avant le prestataire : un blocage Shield ou une restriction sur votre compte |
validation_error | Un champ rempli par le payeur a été refusé, comme un numéro de téléphone invalide |
rate_limited | Trop de tentatives de paiement sur cette session. Attendez un court instant avant de proposer une nouvelle tentative |
server_error | Wajub ou le prestataire a échoué. retryable indique si une nouvelle tentative vaut la peine |
submission_failed | Champs de paiement uniquement. Un envoi que vous avez demandé avec submit() ou confirmPayment() a été refusé avant tout débit : un formulaire qui n'est pas prêt, quel que soit le moyen, comme un numéro Mobile Money invalide, une carte laissée incomplète chez n'importe quel prestataire, des champs de carte encore en chargement, un virement sans IBAN ni numéro de compte ou un paiement en crypto sans actif, un numéro de carte rejeté par son prestataire, une fenêtre de prestataire qui a échoué, a été fermée ou n'a pas pu s'ouvrir. message indique pourquoi, dans la langue du payeur |
WajubPay, obsolète
Le script expose aussi window.WajubPay.create(), une ancienne façon de monter un checkout en
ligne. Il est obsolète depuis la 1.6.0 et sera retiré dans une version future : son premier appel
écrit un avertissement dans la console. Utilisez mount(), open() ou un composant de framework.
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, et depuis la 1.8.0 BankTransferComponent, CryptoComponent | 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 |
WajubContext en React, WAJUB_INJECTION_KEY en Vue, getWajubContext et setWajubContext en Svelte, et useWajubContext dans les trois | Le contexte brut, pour votre propre hook, composable ou helper |
@wajub/angular, depuis la 1.8.1, exporte les formes Angular du même ensemble.
| Export | Description |
|---|---|
provideWajub(options?) | Configure le chargement du runtime pour l'application ou une route, loadOptions et defer, à la place de WajubProvider |
WajubService | Charge le runtime une fois : les signaux runtime, loading et error, runtime$, load() et getRuntime(), à la place de useWajub, useWajubOptional et useLoadWajub |
WAJUB_OPTIONS | Le jeton d'injection que définit provideWajub() |
WajubCheckoutEmbedComponent | <wajub-checkout-embed>, le checkout hébergé, affiché en ligne |
WajubCardComponent, WajubMobileMoneyComponent, WajubWalletComponent, WajubPaymentComponent, WajubAddressComponent, WajubBankTransferComponent, WajubCryptoComponent | <wajub-card>, <wajub-mobile-money>, <wajub-wallet>, <wajub-payment>, <wajub-address>, <wajub-bank-transfer>, <wajub-crypto> : un groupe de champs chacun |
WajubComponentEmbedComponent | <wajub-component>, la même chose avec un input type |
WajubComponentBase | La classe que partagent les composants de champs : leurs inputs, leurs outputs et componentInstance |
injectConfirmPayment(sessionId?) | Soumet un composant de champs, à la place de useConfirmPayment. isConfirming est un signal |
| Prop du wrapper | S'applique à | Valeur par défaut |
|---|---|---|
className dans React, class dans Vue et Svelte, et sur l'élément hôte en Angular | Les deux | aucune |
style, dans React et Vue, et sur l'élément hôte en Angular | Les deux | aucune |
minHeight | CheckoutEmbed | 480 |
minHeight | Composants de champs | Non définie depuis la 1.8.0. Avec le chargeur skeleton, le conteneur tient, du premier rendu jusqu'au montage du formulaire, componentEstimatedHeight(type, variant, fields) au rendu serveur et à l'hydratation, componentReserveHeight() à un rendu suivant, puis le SDK tient la place. Avec loader: 'none', 200 pour card, 240 pour mobileMoney, 120 pour wallet, 360 pour payment, 280 pour address, 200 pour bankTransfer, 240 pour crypto. Une valeur que vous passez, ou en React, Vue et Angular un min-height dans style, est gardée toute la vie du composant |
loader | Composants de champs | skeleton depuis la 1.8.0, alors que @wajub/js lui-même vaut none par défaut |
onInstance, l'output (instance) en Angular | Composants de champs | aucune, appelée avec null au démontage |
En Angular, les props sont des inputs et des outputs du même nom : chaque option est un input,
chaque callback un output nommé sans on, par exemple (loadError) pour onLoadError, et
onBeforeSubmit est l'input beforeSubmit, car un output ne peut pas répondre.
Depuis la 1.8.0, chaque option de ComponentConfig est une prop des composants de champs, callbacks
compris, et les gestionnaires que vous passez sont lus à l'arrivée de l'événement. appearance,
locale, layout et frameTitle atteignent le champ monté par update(), seulement quand leur
contenu change. Un nouveau sessionId, type, variant, fields, loader, readyTimeout,
collectAddress, addressMode ou collectName monte un nouveau champ dans le même conteneur.
CheckoutEmbed envoie appearance, theme, locale et layout par update(), et se recharge
pour un nouveau sessionId ou embedOrigin. @wajub/angular fait de même dès sa première
version, la 1.8.1.
Chaque wrapper, celui d'Angular compris, réexporte aussi tous les types de @wajub/js :
import type { PaymentSuccess } from '@wajub/react' fonctionne comme depuis @wajub/js.
useWajubOptional() renvoie le runtime ou null dans React. À partir de la version 1.6.0, il
renvoie une ref dans Vue et un store dans Svelte, qui valent null tant que le runtime n'est pas chargé.
En Angular, le signal runtime de WajubService vaut null jusque-là.
Chaque package possède sa propre page, car leurs différences sont réelles : React, Vue, Svelte, Angular.