Composants embarqués
Montrez à un vendeur ses ventes, ses versements, son solde, son compte, ses litiges et ce qui l'attend, dans vos propres pages, à vos couleurs.
Vos vendeurs se connectent déjà à votre produit. Les composants embarqués y mettent des morceaux de leur espace Wajub, dans vos pages et à vos couleurs : leurs ventes, leurs versements, leur solde, les actions qui les attendent. Ils ne quittent jamais votre site, et vous ne refaites pas des écrans que Wajub tient déjà à jour.
Les composants
| Composant | Montre | lite | relay |
|---|---|---|---|
notifications | Les actions qui attendent le vendeur : vérification d'identité, compte de versement manquant, pièce d'identité demandée, versements retenus | Oui | Oui |
payments | Ses ventes, page par page (montant, frais, votre commission, remboursé, net, statut), et le détail de chaque vente avec ses remboursements | Oui | Non |
payouts | Les versements que Wajub lui a envoyés, ce que chacun règle ligne à ligne, le prochain versement, ce qui retient ses versements, et ses relevés annuels | Oui | Oui, les versements de ses dus |
balance | Lite : disponible, en attente, en réserve, bloqué jusqu'à la livraison. Relay : ce qui lui est dû et à verser, ce qui est encore retenu | Oui | Oui |
account | La vérification d'identité à terminer, ses comptes de versement (4 derniers caractères), et en option leur changement | Oui | Non |
disputes | Les litiges sur ses ventes, et sa réponse quand vous le laissez la donner (Litiges sur les ventes de vos vendeurs) | Oui | Non |
Un marchand direct a son propre Dashboard : une session embarquée pour lui est refusée avec
account_type_not_embeddable. Tout fonctionne en sandbox, avec une clé de test et un compte sandbox.
Le portail entier dans une iframe (portal_sessions)
reste disponible. Les composants sont la voie recommandée : vous choisissez quoi montrer, et où.
Comment les pièces s'assemblent
Étape 1, Déclarez les origines de vos pages
Sous Paramètres, Sync, Plateforme, listez jusqu'à 5 origines
httpsd'où vos pages sont servies. Les composants s'affichent là, et nulle part ailleurs.Étape 2, Votre serveur demande une session
POST /accounts/{id}/embedded_sessionsavec votre clé secrète, en nommant les composants à activer. Vous recevez unclient_secret, valable une fois pendant 5 minutes, etloader_url.Étape 3, Votre page charge le script
WajubConnect.init({ fetchClientSecret })appelle votre serveur quand il lui faut un secret, l'échange contre une session de 30 minutes, puis monte chaque composant dans son propre cadre.Étape 4, La session finit, une autre commence
Quand la session expire, le chargeur redemande un secret à votre
fetchClientSecret. Si le vendeur a quitté votre plateforme entre-temps, le composant envoieexit.
Créer une session
curl https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ/embedded_sessions \
-H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
-H "Content-Type: application/json" \
-d '{
"components": {
"notifications": { "enabled": true },
"payments": { "enabled": true },
"payouts": { "enabled": true },
"account": { "enabled": true, "features": { "edit_payout_account": true } }
}
}'| Champ | |
|---|---|
components | Requis. Des clés parmi notifications, payments, payouts, balance, account, disputes ; au moins une avec enabled: true |
components.*.enabled | false par défaut |
components.account.features.edit_payout_account | Laisse le vendeur changer son compte de versement depuis le composant. Toujours après un code envoyé au propriétaire de son espace, valable pour ce nouveau compte seulement, jamais sur votre seule parole, et le nouveau compte attend la période de refroidissement habituelle (Changer de compte de versement) |
components.payments.features.refund_management | Réservée : true est refusé avec feature_not_available pour l'instant |
components liste toujours les six composants, chacun avec enabled et ses fonctions, que vous
l'ayez activé ou non.
Le client_secret sert une fois, avant expires_at, et seulement depuis une page d'une de vos
origines déclarées. Wajub n'en garde que l'empreinte. Donnez-le au navigateur qui l'a demandé et à
rien d'autre : ne le journalisez jamais, ne le mettez jamais dans une URL.
loader_url est sur l'adresse de vos vendeurs : votre propre domaine quand il
est actif, votrenom.wajub.app une fois le nom validé par Wajub, lite.wajub.com avant.
error_code | Statut | Quand |
|---|---|---|
account_type_not_embeddable | 400 | Un compte direct |
component_not_available | 400 | payments, account ou disputes sur un compte relay |
feature_not_available | 400 | payments.refund_management: true |
unknown_component, unknown_feature | 400 | Une clé que Wajub ne connaît pas |
no_component_enabled | 400 | Rien d'activé |
account_not_active | 409 | La connexion n'est pas encore active |
frame_origins_missing | 409 | Vous n'avez déclaré aucune origine |
Un compte d'une autre plateforme, ou de l'autre environnement, répond 404.
Une intégration complète
Votre serveur détient la clé secrète et sait quel vendeur est connecté. Il crée la session et ne
donne au navigateur que le client_secret.
import express from 'express';
const app = express();
app.post('/wajub/embedded-session', requireSellerLogin, async (req, res) => {
const accountId = req.user.wajubAccountId; // acc_…
const response = await fetch(`https://api.wajub.com/accounts/${accountId}/embedded_sessions`, {
method: 'POST',
headers: {
Authorization: process.env.WAJUB_SECRET_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
components: {
notifications: { enabled: true },
payments: { enabled: true },
payouts: { enabled: true },
balance: { enabled: true },
account: { enabled: true, features: { edit_payout_account: true } },
},
}),
});
const body = await response.json();
if (!response.ok) return res.status(502).json({ error: body.error_code });
res.json({ client_secret: body.embedded_session.client_secret });
});$session = Http::withHeaders(['Authorization' => config('services.wajub.secret')])
->post("https://api.wajub.com/accounts/{$accountId}/embedded_sessions", [
'components' => [
'payments' => ['enabled' => true],
'payouts' => ['enabled' => true],
],
])
->throw()
->json('embedded_session');
return ['client_secret' => $session['client_secret']];Votre page charge le script depuis loader_url et monte les composants où vous les voulez.
<div id="wajub-notifications"></div>
<div id="wajub-balance"></div>
<div id="wajub-payments"></div>
<script src="https://acme.wajub.app/embed/v1.js"></script>
<script>
const wajub = WajubConnect.init({
fetchClientSecret: async () => {
const response = await fetch('/wajub/embedded-session', {
method: 'POST',
credentials: 'same-origin',
});
return (await response.json()).client_secret;
},
appearance: {
colors: { primary: '#0f766e' },
border_radius: '8px',
font: 'Inter',
mode: 'system',
},
locale: 'fr',
});
for (const name of ['notifications', 'balance', 'payments']) {
wajub
.create(name)
.on('loaderror', (error) => console.error(name, error))
.on('exit', () => console.info('Session terminée'))
.mount(`#wajub-${name}`);
}
</script>Avant d'essayer : déclarez https://votre-site.example sous Paramètres, Sync, Plateforme, et en
test utilisez une clé de test et un compte sandbox.
Le chargeur
WajubConnect est en version 1, et reste tel quel : un changement ultérieur sortira à une autre
adresse.
| Appel | Fait |
|---|---|
WajubConnect.init({ fetchClientSecret, appearance, locale }) | Démarre une session. Tous les composants créés depuis elle la partagent |
wajub.create(name) | Un composant : notifications, payments, payouts, balance, account ou disputes |
component.mount(target) | Le dessine dans un sélecteur CSS ou un élément. Il prend toute la largeur du conteneur, et sa hauteur suit son contenu |
component.unmount() | Le retire |
component.on(event, handler) | Écoute ready, loaderror ou exit ; renvoie le composant, les appels s'enchaînent |
wajub.destroy() | Retire tous les cadres et l'écouteur |
locale vaut en ou fr ; sans elle, la langue du navigateur, et le français à défaut.
WajubConnect.version vaut '1' et WajubConnect.components liste les noms.
| Événement | Quand |
|---|---|
ready | Le composant est dessiné : { component } |
loaderror | Il n'a pas pu se charger : { type, message }, avec un type comme frame_timeout (rien n'a répondu en 15 secondes : vérifiez vos origines déclarées), invalid_client_secret, origin_not_allowed, component_not_enabled ou load_error |
exit | La session est finie et ne peut pas être renouvelée |
L'apparence
L'apparence est vérifiée par Wajub : pas de CSS libre.
| Clé | Valeurs |
|---|---|
colors.primary, colors.background, colors.text | #rgb ou #rrggbb |
border_radius | 0px, 4px, 8px, 12px ou 9999px |
font | Instrument Sans, Inter, Roboto, Open Sans, Lato, Montserrat, Poppins, DM Sans, Plus Jakarta Sans, Raleway, Nunito, Work Sans, Manrope, Outfit, Space Grotesk, Public Sans, Figtree, Lexend, Sora, Source Sans 3 ou IBM Plex Sans |
mode | light, dark ou system |
Toute autre valeur est ignorée, signalée dans la console, et remplacée par votre marque de Paramètres, Image de marque. Une couleur qui manque de contraste est ajustée pour rester lisible, comme sur le portail.
Changer de compte de versement
Avec edit_payout_account, le composant account permet à un vendeur Lite de changer l'endroit où
il est payé. Ni votre parole ni votre session n'y suffisent :
| Étape | |
|---|---|
| Le vendeur saisit le nouveau compte | L'opérateur et le numéro, ou le compte bancaire, vérifiés comme dans son portail avant tout envoi de code |
| Un code part au propriétaire de son espace | À l'adresse e-mail qui ouvre son espace, jamais à une adresse que vous avez enregistrée. L'e-mail nomme le nouveau compte (l'opérateur, les 4 derniers chiffres) et dit de ne jamais donner le code à personne, pas même à votre plateforme ni à quelqu'un qui dit travailler pour Wajub. Il part de Wajub, sous le nom d'espace validé (« votrenom via Wajub »), sans votre logo, votre couleur ni votre adresse de réponse |
| Le code ne confirme que ces coordonnées | Envoyé avec d'autres coordonnées, il est refusé et consommé : le vendeur en demande un nouveau. Demander un code pour d'autres coordonnées annule le précédent |
| Le compte change | Après la période de refroidissement habituelle. Le vendeur reçoit un e-mail de Wajub disant que son compte de versement a changé, dont le lien mène à son adresse Wajub, jamais à votre domaine |
Sur votre propre domaine, rien ne se confirme dans le cadre : vous tenez le
certificat de ce domaine. Le composant montre les comptes de versement en lecture seule, et son
bouton Changer de compte de versement ouvre l'adresse Wajub du vendeur,
https://votrenom.wajub.app/payout-account (le change_url du composant, null sur une adresse
Wajub), dans un nouvel onglet. Le vendeur s'y connecte avec son propre code et change le compte sur
place.
Le chargeur et le composant gèrent eux-mêmes ces réponses du cadre :
| Réponse | Quand |
|---|---|
409 change_on_wajub, avec url | Un code demandé, ou un changement envoyé, sur votre propre domaine : le changement se fait à url |
429 too_many_codes | 3 codes par heure ou 6 par jour ; ou un code pour d'autres coordonnées est en route et le délai entre deux codes n'est pas écoulé |
429 payout_account_locked | 5 codes faux en 24 heures : le changement est bloqué pendant 24 heures |
Fermer les sessions d'un vendeur
POST /accounts/{id}/embedded_sessions/revoke met fin d'un coup à toutes les sessions embarquées du
vendeur : les secrets clients pas encore échangés ne marchent plus, et les sessions ouvertes se
terminent. Leurs cadres répondent session_expired, et le chargeur redemande un secret à votre
fetchClientSecret. Appelez-la quand un vendeur quitte votre plateforme, ou quand un secret client a
pu fuiter ; si le vendeur ne doit plus rien voir, faites refuser ce secret suivant par votre serveur.
curl -X POST https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ/embedded_sessions/revoke -H "Authorization: sk.xxxxxxxxxxxxxxxx…"| Règle | |
|---|---|
revoked | Combien de sessions encore vivantes ont été fermées, secrets pas encore échangés compris ; 0 s'il n'y en avait aucune |
| Environnement | Celui du compte : une clé de test ferme les sessions de test |
| Clé | Votre clé secrète, sans X-Sync. Une clé restreinte est refusée (403), comme sur POST /accounts/{id}/embedded_sessions |
| Refus | 400 account_type_not_embeddable sur un compte direct ; 404 pour un compte d'une autre plateforme |
Ce qui le rend sûr
| Règle | Pourquoi |
|---|---|
| Aucun cookie tiers | La session passe par postMessage vers l'origine exacte du cadre, puis dans un en-tête Authorization. Ça marche dans les navigateurs qui bloquent les cookies tiers |
| Le jeton n'est jamais dans une URL | L'adresse du cadre ne porte que l'identifiant public de la session, qui dit quelles origines peuvent l'encadrer |
| Les messages sont vérifiés dans les deux sens | Le cadre n'écoute que son parent sur une origine déclarée ; le chargeur, que ses propres cadres |
| Encadré par vos seules origines | Les cadres envoient frame-ancestors avec les origines que vous avez déclarées |
Origin protège un navigateur, pas un secret | Le secret n'est échangé que depuis une page d'une origine déclarée. Un serveur qui détient un secret client peut envoyer n'importe quel Origin : gardez le secret sur votre serveur jusqu'à ce que votre page le demande, et fermez les sessions du vendeur s'il a pu fuiter |
| Votre clé secrète seulement | Créer et fermer des sessions demande votre clé secrète : une clé restreinte est refusée |
| Lecture seule, sauf une fonction | Seule edit_payout_account écrit, et seulement après un code à usage unique envoyé à l'adresse du propriétaire de l'espace du vendeur, jamais à une adresse que vous avez enregistrée, et valable pour le seul compte qu'il nomme. Le code sert une fois, pendant 10 minutes. Au plus 3 codes par heure et 6 par jour ; 5 codes faux en 24 heures bloquent le changement pendant 24 heures. Sur votre propre domaine, le changement se fait sur l'adresse Wajub du vendeur. Après tout changement, le vendeur reçoit un e-mail de Wajub disant que son compte de versement a changé |
| La session suit vos réglages | Elle se termine aussitôt (le chargeur redemande un secret à votre serveur) quand l'origine qui l'a ouverte n'est plus déclarée, que l'espace du vendeur est fermé, ou que Sync n'est plus dans votre forfait. Origines et forfait sont relus au moins toutes les 60 secondes |
Appeler les cadres vous-même
Le chargeur et ses cadres appellent quelques routes sur l'adresse de vos vendeurs
(/embed/v1/sessions, /embed/v1/payments…). Ce n'est pas une API à appeler à la main, et elles
peuvent changer dans la version 1 tant que le chargeur, lui, ne change pas.
Pages associées
- Votre propre domaineServez le portail et les composants sur un domaine à vous.
- Litiges sur les ventes de vos vendeursLaissez les vendeurs répondre depuis le composant `disputes`.
- Créer une session embarquéeLa spécification de l'endpoint.
- Fermer les sessionsMettre fin à toutes les sessions embarquées d'un vendeur.