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) | 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)
is still there. Components are the recommended way: you choose what to show, and where.
How it fits together
Step 1, Declare the origins of your pages
Under Settings, Sync, Platform, list up to 5
httpsorigins your pages are served from. The components are shown there and nowhere else.Step 2, Your server asks for a session
POST /accounts/{id}/embedded_sessionswith your secret key, naming the components to turn on. You get aclient_secret, valid once for 5 minutes, andloader_url.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.Step 4, The session ends, a new one starts
When the session runs out, the loader asks your
fetchClientSecretfor a new secret. If the seller is gone from your platform in the meantime, the component sendsexit.
Create a 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 } }
}
}'| 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) |
components.payments.features.refund_management | Reserved: true is refused with feature_not_available for now |
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_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.
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']];Your page loads the script from loader_url and mounts the components where you want them.
<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, 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.
curl -X POST https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ/embedded_sessions/revoke -H "Authorization: sk.xxxxxxxxxxxxxxxx…"| 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 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 |
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.