Aller au contenu

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

ComposantMontreliterelay
notificationsLes actions qui attendent le vendeur : vérification d'identité, compte de versement manquant, pièce d'identité demandée, versements retenusOuiOui
paymentsSes ventes, page par page (montant, frais, votre commission, remboursé, net, statut), et le détail de chaque vente avec ses remboursementsOuiNon
payoutsLes 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 annuelsOuiOui, les versements de ses dus
balanceLite : disponible, en attente, en réserve, bloqué jusqu'à la livraison. Relay : ce qui lui est dû et à verser, ce qui est encore retenuOuiOui
accountLa vérification d'identité à terminer, ses comptes de versement (4 derniers caractères), et en option leur changementOuiNon
disputesLes litiges sur ses ventes, et sa réponse quand vous le laissez la donner (Litiges sur les ventes de vos vendeurs)OuiNon

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

  1. Étape 1, Déclarez les origines de vos pages

    Sous Paramètres, Sync, Plateforme, listez jusqu'à 5 origines https d'où vos pages sont servies. Les composants s'affichent là, et nulle part ailleurs.

  2. Étape 2, Votre serveur demande une session

    POST /accounts/{id}/embedded_sessions avec votre clé secrète, en nommant les composants à activer. Vous recevez un client_secret, valable une fois pendant 5 minutes, et loader_url.

  3. É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.

  4. É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 envoie exit.

Créer une session

Une session avec quatre composants
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
componentsRequis. Des clés parmi notifications, payments, payouts, balance, account, disputes ; au moins une avec enabled: true
components.*.enabledfalse par défaut
components.account.features.edit_payout_accountLaisse 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_managementRéservée : true est refusé avec feature_not_available pour l'instant
Réponse · 201 Created
{
"code": 201,
"status": "Created",
"message": "Embedded session created",
"embedded_session": {
"id": "es_0193f3c2a1b47c9e8d2f5a6b7c8d9e0f",
"client_secret": "es_0193f3c2a1b47c9e8d2f5a6b7c8d9e0f_secret_…",
"expires_at": "2026-11-20T10:05:00+00:00",
"account_type": "lite",
"components": {
"notifications": {
"enabled": true,
"features": {
}
},
"payments": {
"enabled": true,
"features": {
"refund_management": false
}
},
"payouts": {
"enabled": true,
"features": {
}
},
"balance": {
"enabled": false,
"features": {
}
},
"account": {
"enabled": true,
"features": {
"edit_payout_account": true
}
},
"disputes": {
"enabled": false,
"features": {
}
}
},
"loader_url": "https://acme.wajub.app/embed/v1.js"
}
}

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_codeStatutQuand
account_type_not_embeddable400Un compte direct
component_not_available400payments, account ou disputes sur un compte relay
feature_not_available400payments.refund_management: true
unknown_component, unknown_feature400Une clé que Wajub ne connaît pas
no_component_enabled400Rien d'activé
account_not_active409La connexion n'est pas encore active
frame_origins_missing409Vous 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.

Serveur · Node.js (Express)
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 });
});
Serveur · PHP (Laravel)
$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.

Navigateur
<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.

AppelFait
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énementQuand
readyLe composant est dessiné : { component }
loaderrorIl 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
exitLa 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_radius0px, 4px, 8px, 12px ou 9999px
fontInstrument 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
modelight, 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 compteL'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éesEnvoyé 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 changeAprè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éponseQuand
409 change_on_wajub, avec urlUn code demandé, ou un changement envoyé, sur votre propre domaine : le changement se fait à url
429 too_many_codes3 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_locked5 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.

Fermer les sessions d'un vendeur
curl -X POST https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ/embedded_sessions/revoke   -H "Authorization: sk.xxxxxxxxxxxxxxxx…"
Réponse · 200 OK
{
"code": 200,
"status": "OK",
"message": "Embedded sessions revoked",
"revoked": 2
}
Règle
revokedCombien de sessions encore vivantes ont été fermées, secrets pas encore échangés compris ; 0 s'il n'y en avait aucune
EnvironnementCelui 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
Refus400 account_type_not_embeddable sur un compte direct ; 404 pour un compte d'une autre plateforme

Ce qui le rend sûr

RèglePourquoi
Aucun cookie tiersLa 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 URLL'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 sensLe cadre n'écoute que son parent sur une origine déclarée ; le chargeur, que ses propres cadres
Encadré par vos seules originesLes cadres envoient frame-ancestors avec les origines que vous avez déclarées
Origin protège un navigateur, pas un secretLe 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 seulementCréer et fermer des sessions demande votre clé secrète : une clé restreinte est refusée
Lecture seule, sauf une fonctionSeule 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églagesElle 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.

Que pensez-vous de ce contenu ?