Dépannage de Wajub Components

Le symptôme, sa cause et la ligne qui le corrige.

Presque tous les problèmes de Wajub Components proviennent de quatre causes : un jeton qui n'est plus valide, une page qui a chargé le SDK sur le serveur, un callback non configuré ou une clé de configuration ignorée silencieusement par le SDK. Commencez ici avant de lire le code.

Rien ne s'affiche

Symptôme	Cause	Correction
Conteneur vide sans erreur	Jeton expiré, utilisé ou inconnu	Configurez `onLoadError`. Il contient `session_expired`, `session_used`, `session_not_found`, `invalid_session` ou `session_terminal_expired`
`Embed misconfigured`	URL de checkout collée manuellement dans une iframe	Appelez `mount()`, `open()` ou `CheckoutEmbed`
Aucune action ni requête réseau	`mount()` s'est exécuté sur le serveur	Importez depuis `@wajub/js/pure` ou marquez le fichier avec `'use client'`
`Error` générée lors de l'appel	Aucun `sessionId` ou sélecteur sans correspondance	Les deux génèrent une erreur synchrone avant toute requête
L'iframe n'apparaît jamais	`load_error` dans `onLoadError`	L'origine du checkout est inaccessible. Vérifiez l'onglet réseau et les règles de contenu

onLoadError explique une intégration vide

onError concerne les paiements qui échouent. onLoadError concerne les checkouts qui ne démarrent jamais, comme dans la plupart des lignes ci-dessus. Configurez-le en premier dans chaque intégration.

Clés

Une clé Wajub se compose d'un préfixe, d'un point, puis de 96 caractères. pk. et sk. sont live, pk_test. et sk_test. appartiennent à la sandbox.

Symptôme	Cause	Correction
`secret_key_in_browser`	Clé `sk.` transmise à `Wajub()`	Le navigateur reçoit un jeton de session, jamais une clé secrète
`invalid_publishable_key`	La valeur n'est pas une clé publique	Elle commence par `pk` et ne correspond pas au jeton de session
`missing_publishable_key`	Appel de `createPayment()` sans clé	Configurez-la sur le client ou créez la session sur votre serveur
Réponse `403` de l'API et e-mail	Clé secrète envoyée depuis un navigateur	L'API la refuse et alerte son propriétaire. Renouvelez la clé
CORS sur `createPayment`	Appel direct de l'API depuis le code de la page	Créez la session sur votre backend

Pour distinguer la sandbox du mode live dans le navigateur, lisez la session plutôt que la clé.

La session connaît l'environnement

import { fetchSession } from '@wajub/js';

const preview = await fetchSession(sessionId);
if (preview.environment === 'sandbox') showSandboxBanner();

Champs de paiement

Symptôme	Cause	Correction
`complete` ne devient jamais `true`	Champ obligatoire encore vide ou invalide	Enregistrez `event.error` dans le handler `change`, il identifie le champ
`confirmPayment` rejette avec `wallet_not_supported`	Composant `wallet`	Apple Pay et Google Pay utilisent leur propre bouton
`confirmPayment` rejette avec `address_not_payment`	Composant `address`	Il collecte sans débiter. Lisez-le avec `getValue()`
`confirmPayment` rejette avec `missing_component`	Aucun composant transmis ou composant jamais monté	Conservez l'instance de `onInstance` ou de l'événement `ready`
`confirmation_timeout` après une minute	Aucun résultat reçu	Augmentez `timeout` ou transmettez `0` pour attendre indéfiniment
`getValue()` renvoie `null`	Aucune valeur encore saisie	La valeur arrive au premier `change`. Lisez-la dans le handler
L'OTP n'apparaît jamais	Les champs de paiement ne gèrent pas les OTP	Utilisez le checkout hébergé

Style sans effet

Le SDK filtre appearance avant son départ du navigateur. Une clé inconnue est ignorée sans avertissement. Une faute de frappe ressemble donc exactement à un bug du checkout.

Symptôme	Cause
Bloc `rules` ignoré	Le sélecteur n'est pas `.Input` ou `.Label` avec au maximum un pseudo-élément autorisé
Propriété d'une règle ignorée	Elle ne figure pas parmi les 32 propriétés autorisées
Arrière-plan `url()` ignoré	Les valeurs contenant `url(`, `@import`, `javascript:`, `<` ou `>` sont refusées
Clé `variables` ignorée	Seules les seize clés documentées sont acceptées
`update({ layout })` ne change rien	Le checkout hébergé l'enregistre localement sans l'envoyer
Les props `appearance` ne changent rien après le montage	`CheckoutEmbed` n'appelle jamais lui-même `update()`

Les trois listes figurent dans Apparence. Le comportement propre à chaque framework est présenté dans React, Vue et Svelte.

Mise en page et dimensions

Symptôme	Cause	Correction
L'intégration est coupée	Parent avec `overflow: hidden` ou hauteur fixe	Le SDK définit lui-même la hauteur de l'iframe. Laissez le parent grandir
La page se décale au chargement du checkout	Aucun espace réservé autour de votre contenu	Le SDK réserve déjà 480px. Réservez votre récapitulatif, pas l'intégration
Un composant de champ reste minuscule	Son parent utilise `display: none` lors du montage	Montez-le une fois visible ou après l'ouverture de l'onglet

onResize est fourni à titre informatif. Le SDK a déjà appliqué la hauteur lors de son déclenchement. Utilisez-le pour déplacer un autre élément de la page.

Paiement

Symptôme	Cause	Correction
Moyen de paiement absent du checkout	La session ne contient pas ce canal	Lisez `fetchSession().payment_methods` avant le montage
Commande livrée deux fois	`onSuccess` et le webhook déclenchent tous deux la livraison	Livrez avec le webhook et utilisez `onSuccess` pour l'interface
Commande jamais livrée	`onSuccess` s'est exécuté puis l'onglet s'est fermé	Même réponse. Le navigateur n'est pas une source fiable
`onError` se déclenche avec un `decline_code`	Le prestataire a refusé le paiement	`retryable` indique si une nouvelle tentative doit être proposée

Avant de passer en live

onError et onLoadError sont tous deux configurés.
La session est créée sur votre serveur avec la clé secrète dans une variable d'environnement.
Votre site et votre URL de callback utilisent HTTPS.
La commande est livrée à la réception du webhook, pas dans le navigateur.
L'intégration utilise mount(), open() ou un composant de framework, jamais une URL construite à la main.
onBreakdown maintient votre total à jour s'il apparaît à côté d'une intégration en ligne.
Un paiement réel d'un petit montant a été effectué en mode live.

Les cartes et numéros Mobile Money de test figurent dans Scénarios de test.

Le problème persiste ?

Écrivez à support@wajub.com avec la référence de transaction, le domaine de votre marchand et le code de onLoadError ou onError. N'envoyez jamais de clé.

Pages associées