# 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](https://docs.wajub.com/fr/sync/disputes))                    | 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`](https://docs.wajub.com/fr/sync/onboarding#the-portal-in-your-own-pages))
reste disponible. Les composants sont la voie recommandée : vous choisissez quoi montrer, et où.

## Comment les pièces s'assemblent

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

```bash title="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                                             |                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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](#changing-the-payout-account)) |
| `components.payments.features.refund_management`  | Réservée : `true` est refusé avec `feature_not_available` pour l'instant                                                                                                                                                                                                                                                                               |

```json title="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](https://docs.wajub.com/fr/sync/own-domain) 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`.

```js title="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 });
});
```

```php title="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.

```html title="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.

| 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](https://docs.wajub.com/fr/sync/own-domain), 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.

```bash title="Fermer les sessions d'un vendeur"
curl -X POST https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ/embedded_sessions/revoke   -H "Authorization: sk.xxxxxxxxxxxxxxxx…"
```

```json title="Réponse · 200 OK"
{
"code": 200,
"status": "OK",
"message": "Embedded sessions revoked",
"revoked": 2
}
```

| 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](#revoking-sessions) 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                                                                                                                                                                                                                                                                                                         |

> [!NOTE]
> **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.

- [Votre propre domaine](https://docs.wajub.com/fr/sync/own-domain): Servez le portail et les composants sur un domaine à vous.
- [Litiges sur les ventes de vos vendeurs](https://docs.wajub.com/fr/sync/disputes): Laissez les vendeurs répondre depuis le composant `disputes`.
- [Créer une session embarquée](https://docs.wajub.com/fr/api/subaccounts/create-embedded-session): La spécification de l'endpoint.
- [Fermer les sessions](https://docs.wajub.com/fr/api/subaccounts/revoke-embedded-sessions): Mettre fin à toutes les sessions embarquées d'un vendeur.
