Branding & theming

Account wide defaults, the sites allowed to embed your checkout, and how they meet appearance.

Branding is what your checkout looks like before any code runs. It is set once on your account, and it applies to the hosted page, the overlay and every payment field component.

appearance is the other half, covered on Appearance. This page is the server side.

Where it is configured

In the Dashboard, under Settings then Branding. There is no API for it, and there is nothing to pass at mount time. Save it once and every session that follows carries it.

The checkout shows your branding from the first paint, then applies whatever appearance you passed on top.

Branding needs a paid plan

Settings → Branding is available from the Growth plan. On Pay as you go the checkout and the payment fields keep the default appearance, and appearance is the only way to style them. The list of sites allowed to embed your checkout is not part of Branding: it has its own page on every plan, described below.

Where the checkout may be embedded

Settings → Checkout embedding holds the sites allowed to embed your checkout: up to 20 origins, each written https://domain, with an optional port and no path. The page is on every plan, Pay as you go included, and the list applies in live and in sandbox. Once you fill it, the browser shows your checkout and your payment fields only inside a page served from one of those origins.

The owner, the members allowed to manage settings and the Developer role can change the list. Saving it asks you to confirm your identity, and the change appears in the team's audit log.

On any other origin the frame stays blank: the browser refuses it before the checkout runs, so onReady never fires and neither does onLoadError. Add every origin that mounts the checkout or a field, staging included, before you fill the list.

Declare your origins before you go live

Declare the sites allowed to embed your checkout in Settings → Checkout embedding before you take live payments. While the list is empty, the Dashboard shows a reminder on the Settings overview, on the Checkout embedding page and on the Branding page.

The theming object on POST /payments does nothing today

theming on POST /payments has no effect on what the payer sees. Use Dashboard branding for defaults and appearance per embed.

What you can set

Settings → Branding covers:

Setting	What it changes
Logo	The logo in the checkout header
Square logo	The logo where the layout is narrow
Icon	The icon of the checkout's browser tab
Colours	The accent, the background, the buttons, the fields, the text and the success and error states
Font	The font of the whole checkout, Inter by default
Corner radius	The roundness of fields and buttons, 8px by default
Page design	The design of the hosted page
Default language	The language the checkout opens in
Custom domain	Your own domain for the hosted page

Page design is not the SDK's layout

The page design picks the design of the hosted page. The SDK's layout option picks how payment methods are arranged, classic, compact, tabs or accordion. They are independent, and setting one never affects the other.

The Wajub mention

With no logo, no primary colour and no business name, the checkout shows the Wajub brand. Add any one of them and the checkout shows your brand, with a small Wajub mention. Removing that mention is not available today.

Who wins

Three layers, resolved in this order.

Later wins

Dashboard branding        your account's default, on every session
  ↓
appearance at mount       this one embed
  ↓
instance.update()         this one embed, after it is running

Client keys merge on top of your Dashboard branding rather than replacing it, so naming primaryColor changes the accent and leaves your logo, your font and your radius alone.

locale and layout passed at mount also override the session defaults, with one exception already noted on Appearance: update({ layout }) does not reach the hosted checkout after mount.

Choosing a layer

Goal	Layer
The same look on every checkout	Dashboard branding
A different brand per merchant, on Sync	Per account Dashboard branding
A dark mode toggle on your site	`appearance.colorScheme` plus `update()`
One campaign, one page	`appearance` on that mount
Field radius, padding, label weight	`appearance.variables`
Remove the Wajub mention	Not available today
A web font or a background image	Not available today