Branding & theming

Account wide defaults, white label, custom CSS, and how they meet appearance.

Branding is what your checkout looks like before any code runs. It is set once on your account, it arrives with the session, 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 reads that configuration from the payment session, resolves it before the first paint, and only then applies whatever appearance you passed on top.

The theming object on POST /payments does nothing today

POST /payments accepts a theming array and stores it on the transaction, where GET /payments/{id} gives it back. Neither the session endpoint nor the checkout reads it, so it changes nothing the payer sees. Use Dashboard branding for defaults and appearance for per embed overrides.

What the session carries

These are the fields the checkout receives on every session.

Field	What it sets
`business_name`	The merchant name in the header
`logo_url`	The header logo
`logo_square_url`	The square variant, used where the layout is narrow
`icon_url`	The favicon of the checkout tab
`custom_domain`	Your own domain for the hosted page
`layout`	The design of the hosted page, `design1` to `design4`
`locale`	The default interface language
`font`	The font family name, `Inter` when unset
`border_radius`	The default corner radius, `8px` when unset
`primary_color`, `secondary_color`, `background_color`	The base palette
`button_text_color`, `success_color`, `error_color`	Buttons and state colours
`input_background_color`, `input_border_color`, `text_muted_color`	Form fields
`card.background_color`, `card.border_color`	The surface the form sits on
`shadow`, `overlay_intensity`	Elevation, and the backdrop of the overlay
`tab_active_bg`, `tab_active_text`, `tab_inactive_bg`, `tab_inactive_text`	Tab layout colours
`accordion_header_bg`, `accordion_body_bg`	Accordion layout colours
`step_active_bg`, `step_done_bg`, `step_inactive_bg`	The step indicator
`separator_color`	Dividers
`font_weight_heading`, `font_weight_body`	Typography weights
`custom_css`	A stylesheet injected into the checkout
`white_label`	Whether Wajub attribution is hidden

Two different things are called layout

branding.layout picks the design of the hosted page, design1 to design4. 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.

White label

The mode is not a setting you pick. The checkout derives it from what you have filled in.

Mode	When	Result
`wajub`	No logo, no primary colour, no business name	The Wajub brand is visible
`co_branded`	Any one of those is set	Your brand, with Wajub attribution
`full_white_label`	White label enabled on your account	Your brand alone

Uploading a logo is therefore enough to leave the default. Going all the way to full_white_label requires the account flag, because it removes Wajub from a payment page the payer is trusting.

In full_white_label, the overlay chrome receives showWajubBranding: false and the checkout drops the Wajub mark. The security badge becomes generic in that mode, and also in plain wajub mode. Only co_branded shows the Wajub name on it.

Custom CSS

custom_css is a raw stylesheet injected into the checkout document. It is the only way past the limits of appearance.rules, which reaches .Input and .Label and nothing else.

Use	Reach for
Field radius, padding, label weight	`appearance.rules`, it stays in your codebase
A web font, a background image, a layout change	`custom_css`

The trade is real. custom_css lives in the Dashboard, applies to every session, and targets internal class names that are not a public contract. Prefer appearance for anything it can do.

Who wins

Four layers, resolved in this order.

Later wins

Dashboard branding        the account default, every session
  ↓
Session branding          resolved and sent when the checkout loads
  ↓
appearance at mount       this one embed
  ↓
instance.update()         this one embed, after it is running

Client keys merge on top of session 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
Remove the Wajub mark	White label on your account
A web font	`custom_css`