Skip to content

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

ComponentShowsliterelay
notificationsThe actions waiting for the seller: identity check, missing payout account, identity document asked for, payouts held backYesYes
paymentsTheir sales, page by page (amount, fee, your commission, refunded, net, status), and the detail of each sale with its refundsYesNo
payoutsThe payouts Wajub sent them, what each one settles line by line, the next payout, what holds payouts back, and their yearly statementsYesYes, the payouts of their dues
balanceLite: available, pending, kept in reserve, held until delivery. Relay: what is owed and payable, what is still heldYesYes
accountThe identity check left to complete, their payout accounts (last 4 characters), and optionally changing themYesNo
disputesThe disputes on their sales, and their answer when you let them give it (Disputes on your sellers' sales)YesNo

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) is still there. Components are the recommended way: you choose what to show, and where.

How it fits together

  1. Step 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. Step 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. Step 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. Step 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

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
componentsRequired. Keys among notifications, payments, payouts, balance, account, disputes; at least one with enabled: true
components.*.enabledfalse by default
components.account.features.edit_payout_accountLet 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)
components.payments.features.refund_managementReserved: true is refused with feature_not_available for now
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 when it is active, yourname.wajub.app once Wajub validated the name, lite.wajub.com before that.

error_codeStatusWhen
account_type_not_embeddable400A direct account
component_not_available400payments, account or disputes on a relay account
feature_not_available400payments.refund_management: true
unknown_component, unknown_feature400A key Wajub does not know
no_component_enabled400Nothing turned on
account_not_active409The connection is not active yet
frame_origins_missing409You 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.

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 });
});
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.

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.

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

EventWhen
readyThe component is drawn: { component }
loaderrorIt 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
exitThe session ended and cannot be renewed

Appearance

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

KeyValues
colors.primary, colors.background, colors.text#rgb or #rrggbb
border_radius0px, 4px, 8px, 12px or 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 or IBM Plex Sans
modelight, 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 accountThe 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 spaceTo 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 onlySent 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 changesAfter 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, 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:

AnswerWhen
409 change_on_wajub, with urlA code asked for, or a change sent, on your own domain: the change is made at url
429 too_many_codes3 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_locked5 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.

Revoke a seller's sessions
curl -X POST https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ/embedded_sessions/revoke   -H "Authorization: sk.xxxxxxxxxxxxxxxx…"
Response · 200 OK
{
"code": 200,
"status": "OK",
"message": "Embedded sessions revoked",
"revoked": 2
}
Rule
revokedHow many sessions still alive were ended, secrets not claimed yet included; 0 when none was
EnvironmentThe account's own: a test key revokes the test sessions
KeyYour secret key, without X-Sync. A restricted key is refused (403), as on POST /accounts/{id}/embedded_sessions
Refusals400 account_type_not_embeddable on a direct account; 404 for an account of another platform

What keeps it safe

RuleWhy
No third-party cookieThe 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 URLThe frame's address carries only the session's public id, which says which origins may frame it
Messages are checked both waysThe frame only listens to its parent on a declared origin; the loader only to its own frames
Framed by your origins onlyThe frames send frame-ancestors with the origins you declared
Origin guards a browser, not a secretThe 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 if it may have leaked
Your secret key onlyCreating and revoking sessions take your secret key: a restricted key is refused
Read only, except one featureOnly 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 settingsIt 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

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.

What did you think of this content?