# Embedded components

> Show a seller their sales, payouts, balance, account, disputes and pending actions inside your own pages, in your colours.

Your sellers already sign in to your product. Embedded components put pieces of their Wajub space
there, inside your pages and in your colours: their sales, their payouts, their balance, the actions
waiting for them. They never leave your site, and you never rebuild screens Wajub already keeps
up to date.

## The components

| Component       | Shows                                                                                                                                  | `lite` | `relay`                        |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------ |
| `notifications` | The actions waiting for the seller: identity check, missing payout account, identity document asked for, payouts held back             | Yes    | Yes                            |
| `payments`      | Their sales, page by page (amount, fee, your commission, refunded, net, status), and the detail of each sale with its refunds          | Yes    | No                             |
| `payouts`       | The payouts Wajub sent them, what each one settles line by line, the next payout, what holds payouts back, and their yearly statements | Yes    | Yes, the payouts of their dues |
| `balance`       | Lite: available, pending, kept in reserve, held until delivery. Relay: what is owed and payable, what is still held                    | Yes    | Yes                            |
| `account`       | The identity check left to complete, their payout accounts (last 4 characters), and optionally changing them                           | Yes    | No                             |
| `disputes`      | The disputes on their sales, and their answer when you let them give it ([Disputes on your sellers' sales](https://docs.wajub.com/sync/disputes))            | Yes    | No                             |

A `direct` merchant has their own Dashboard: an embedded session for one is refused with
`account_type_not_embeddable`. Everything works in sandbox, with a test key and a sandbox account.

The whole portal in an iframe ([`portal_sessions`](https://docs.wajub.com/sync/onboarding#the-portal-in-your-own-pages))
is still there. Components are the recommended way: you choose what to show, and where.

## How it fits together

1. **Declare the origins of your pages**

   Under **Settings, Sync, Platform**, list up to 5 `https` origins your pages are served from. The
   components are shown there and nowhere else.

2. **Your server asks for a session**

   `POST /accounts/{id}/embedded_sessions` with your secret key, naming the components to turn on.
   You get a `client_secret`, valid once for 5 minutes, and `loader_url`.

3. **Your page loads the script**

   `WajubConnect.init({ fetchClientSecret })` calls your server when it needs a secret, exchanges it
   for a session of 30 minutes, then mounts each component in its own frame.

4. **The session ends, a new one starts**

   When the session runs out, the loader asks your `fetchClientSecret` for a new secret. If the
   seller is gone from your platform in the meantime, the component sends `exit`.

## Create a session

```bash title="A session with four components"
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 } }
    }
  }'
```

| Field                                             |                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `components`                                      | Required. Keys among `notifications`, `payments`, `payouts`, `balance`, `account`, `disputes`; at least one with `enabled: true`                                                                                                                                                                            |
| `components.*.enabled`                            | `false` by default                                                                                                                                                                                                                                                                                          |
| `components.account.features.edit_payout_account` | Let the seller change their payout account from the component. **Always** after a code sent to the owner of their space, good for that new account only, never on your word alone, and the new account waits out the usual cooling-off period ([Changing the payout account](#changing-the-payout-account)) |
| `components.payments.features.refund_management`  | Reserved: `true` is refused with `feature_not_available` for now                                                                                                                                                                                                                                            |

```json title="Response · 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` always lists the six components, each with `enabled` and its features, whether you
turned it on or not.

The `client_secret` works **once**, before `expires_at`, and only from a page on one of your declared
origins. Wajub keeps only its hash. Hand it to the browser that asked for it and nothing else: never
log it, never put it in a URL.

`loader_url` is on your sellers' address: [your own domain](https://docs.wajub.com/sync/own-domain) when it is active,
`yourname.wajub.app` once Wajub validated the name, `lite.wajub.com` before that.

| `error_code`                           | Status | When                                                     |
| -------------------------------------- | ------ | -------------------------------------------------------- |
| `account_type_not_embeddable`          | `400`  | A `direct` account                                       |
| `component_not_available`              | `400`  | `payments`, `account` or `disputes` on a `relay` account |
| `feature_not_available`                | `400`  | `payments.refund_management: true`                       |
| `unknown_component`, `unknown_feature` | `400`  | A key Wajub does not know                                |
| `no_component_enabled`                 | `400`  | Nothing turned on                                        |
| `account_not_active`                   | `409`  | The connection is not active yet                         |
| `frame_origins_missing`                | `409`  | You have not declared any origin                         |

An account of another platform, or of the other environment, answers `404`.

## A complete integration

Your server holds the secret key and knows which seller is signed in. It creates the session and
hands the browser the `client_secret` alone.

```js title="Server · 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="Server · 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']];
```

Your page loads the script from `loader_url` and mounts the components where you want them.

```html title="Browser"
<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: 'en',
});

for (const name of ['notifications', 'balance', 'payments']) {
  wajub
    .create(name)
    .on('loaderror', (error) => console.error(name, error))
    .on('exit', () => console.info('Session ended'))
    .mount(`#wajub-${name}`);
}
</script>
```

Before you try it: declare `https://your-site.example` under **Settings, Sync, Platform**, and in
test use a test key and a sandbox account.

## The loader

`WajubConnect` is version `1`, and stays as it is: a later change ships under another address.

| Call                                                           | Does                                                                                                              |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `WajubConnect.init({ fetchClientSecret, appearance, locale })` | Starts one session. Every component created from it shares that session                                           |
| `wajub.create(name)`                                           | A component: `notifications`, `payments`, `payouts`, `balance`, `account` or `disputes`                           |
| `component.mount(target)`                                      | Draws it in a CSS selector or an element. It takes the container's full width, and its height follows its content |
| `component.unmount()`                                          | Removes it                                                                                                        |
| `component.on(event, handler)`                                 | Listens to `ready`, `loaderror` or `exit`; returns the component, so calls chain                                  |
| `wajub.destroy()`                                              | Removes every frame and the listener                                                                              |

`locale` is `en` or `fr`; without it, the browser's language, and French failing that.
`WajubConnect.version` is `'1'` and `WajubConnect.components` lists the names.

| Event       | When                                                                                                                                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ready`     | The component is drawn: `{ component }`                                                                                                                                                                                               |
| `loaderror` | It could not load: `{ type, message }`, with `type` such as `frame_timeout` (nothing answered within 15 seconds: check your declared origins), `invalid_client_secret`, `origin_not_allowed`, `component_not_enabled` or `load_error` |
| `exit`      | The session ended and cannot be renewed                                                                                                                                                                                               |

### Appearance

The appearance is checked by Wajub: there is no free CSS.

| Key                                                  | Values                                                                                                                                                                                                                           |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `colors.primary`, `colors.background`, `colors.text` | `#rgb` or `#rrggbb`                                                                                                                                                                                                              |
| `border_radius`                                      | `0px`, `4px`, `8px`, `12px` or `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 or IBM Plex Sans |
| `mode`                                               | `light`, `dark` or `system`                                                                                                                                                                                                      |

Any other value is ignored, named in a console warning, and replaced by your brand under
**Settings, Branding**. A colour that lacks contrast is adjusted to stay readable, as on the portal.

## Changing the payout account

With `edit_payout_account` on, the `account` component lets a Lite seller change where they are
paid. Neither your word nor your session is enough for it:

| Step                                    |                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The seller enters the new account       | The operator and the number, or the bank account, checked as in their portal before any code goes out                                                                                                                                                                                                                                                                         |
| A code goes to the owner of their space | To the e-mail address that opens their space, never one you registered. The e-mail names the new account (the operator, the last 4 digits) and says never to give the code to anyone, not even your platform or someone who says they work for Wajub. It comes from Wajub, under your validated space name ("yourname via Wajub"), without your logo, colour or reply address |
| The code confirms those details only    | Sent with other details, it is refused and spent: the seller asks for a new one. Asking for a code for other details cancels the previous one                                                                                                                                                                                                                                 |
| The account changes                     | After the usual cooling-off period. The seller gets an e-mail from Wajub saying their payout account changed, whose link leads to their Wajub address, never to your domain                                                                                                                                                                                                   |

On [your own domain](https://docs.wajub.com/sync/own-domain), nothing is confirmed inside the frame: you hold that domain's
certificate. The component shows the payout accounts read-only, and its **Change payout account**
button opens the seller's Wajub address, `https://yourname.wajub.app/payout-account` (the component's
`change_url`, `null` on a Wajub address), in a new tab. The seller signs in there with their own code
and changes the account on the spot.

The loader and the component handle these answers of the frame themselves:

| Answer                              | When                                                                                                                 |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `409` `change_on_wajub`, with `url` | A code asked for, or a change sent, on your own domain: the change is made at `url`                                  |
| `429` `too_many_codes`              | 3 codes an hour or 6 a day; or a code for other details is on its way and the delay between two codes has not passed |
| `429` `payout_account_locked`       | 5 wrong codes within 24 hours: the change is locked for 24 hours                                                     |

## Ending a seller's sessions

`POST /accounts/{id}/embedded_sessions/revoke` ends at once every embedded session of the seller: the
client secrets not claimed yet stop working, and the sessions already open end. Their frames answer
`session_expired`, and the loader asks your `fetchClientSecret` for a new secret. Call it when a
seller leaves your platform, or when a client secret may have leaked; if the seller should see
nothing more, have your server refuse that next secret.

```bash title="Revoke a seller's sessions"
curl -X POST https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ/embedded_sessions/revoke   -H "Authorization: sk.xxxxxxxxxxxxxxxx…"
```

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

| Rule        |                                                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `revoked`   | How many sessions still alive were ended, secrets not claimed yet included; `0` when none was                         |
| Environment | The account's own: a test key revokes the test sessions                                                               |
| Key         | Your secret key, without `X-Sync`. A restricted key is refused (`403`), as on `POST /accounts/{id}/embedded_sessions` |
| Refusals    | `400` `account_type_not_embeddable` on a `direct` account; `404` for an account of another platform                   |

## What keeps it safe

| Rule                                    | Why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No third-party cookie                   | The session travels by `postMessage` to the frame's exact origin, then in an `Authorization` header. It works in browsers that block third-party cookies                                                                                                                                                                                                                                                                                                                                                 |
| The token is never in a URL             | The frame's address carries only the session's public id, which says which origins may frame it                                                                                                                                                                                                                                                                                                                                                                                                          |
| Messages are checked both ways          | The frame only listens to its parent on a declared origin; the loader only to its own frames                                                                                                                                                                                                                                                                                                                                                                                                             |
| Framed by your origins only             | The frames send `frame-ancestors` with the origins you declared                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `Origin` guards a browser, not a secret | The secret is claimed only from a page on a declared origin. A server that holds a client secret can send any `Origin`: keep the secret on your server until your page asks for it, and [revoke the seller's sessions](#revoking-sessions) if it may have leaked                                                                                                                                                                                                                                         |
| Your secret key only                    | Creating and revoking sessions take your secret key: a restricted key is refused                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Read only, except one feature           | Only `edit_payout_account` writes, and only after a one-time code sent to the e-mail address of the owner of the seller's space, never one you registered, and good for the account it names only. The code works once, for 10 minutes. At most 3 codes an hour and 6 a day; 5 wrong codes within 24 hours lock the change for 24 hours. On your own domain the change is made on the seller's Wajub address. After any change, the seller gets an e-mail from Wajub saying their payout account changed |
| The session follows your settings       | It ends at once (the loader asks your server for a new secret) when the origin that opened it is no longer declared, the seller's space is closed, or Sync is no longer on your plan. Origins and plan are read again at least every 60 seconds                                                                                                                                                                                                                                                          |

> [!NOTE]
> **Calling the frames yourself**
>
> The loader and its frames call a few routes on your sellers' address (`/embed/v1/sessions`,
> `/embed/v1/payments`…). They are not an API to call by hand, and they may change within version
> `1` as long as the loader does not.

- [Your own domain](https://docs.wajub.com/sync/own-domain): Serve the portal and the components on a domain of yours.
- [Disputes on your sellers' sales](https://docs.wajub.com/sync/disputes): Let sellers answer from the `disputes` component.
- [Create an embedded session](https://docs.wajub.com/api/subaccounts/create-embedded-session): The endpoint specification.
- [Revoke the sessions](https://docs.wajub.com/api/subaccounts/revoke-embedded-sessions): End every embedded session of a seller.
