Branding & theming
Merchant branding at payment creation — logo, colors, layout, white-label, and how it interacts with client appearance.
Checkout look-and-feel comes from two layers:
- Server branding — set on your Wajub account or per payment when you call
POST /payments - Client
appearance— optional overrides passed tomount(),open(), or payment field components
This page covers server-side branding. For every client-side key, see Appearance.
Quick start — payment creation
When creating a payment with @wajub/node or the REST API, pass
theming for common overrides:
const payment = await wajub.payments.create({
amount: 15000,
currency: 'XAF',
email: 'buyer@example.com',
theming: {
primary_color: '#6366f1',
logo_url: 'https://cdn.example.com/logo.png',
},
});Full branding is configured in the Dashboard (Settings → Branding) and returned on the
payment session as branding when the checkout loads.
Session branding object
When the checkout iframe loads (GET /pay/session), the response includes a branding
object that drives the hosted UI:
| Field | Description |
|---|---|
primary_color | Primary accent |
secondary_color | Secondary accent |
background_color | Page background |
logo_url | Merchant logo (header) |
logo_square_url | Square logo variant |
icon_url | Favicon-style icon |
business_name | Display name in header |
layout | Default payment method layout (classic, compact, tabs, accordion) |
border_radius | Default corner radius |
font | Font family name |
locale | Default UI locale |
custom_css | Injected custom CSS (advanced) |
card.background_color | Card surface background |
card.border_color | Card border |
input_background_color | Input background |
input_border_color | Input border |
text_muted_color | Muted text |
button_text_color | Button label color |
success_color | Success color |
error_color | Error color |
shadow | Shadow intensity |
tab_active_bg / tab_active_text | Active tab colors |
tab_inactive_bg / tab_inactive_text | Inactive tab colors |
font_weight_heading / font_weight_body | Typography weights |
step_active_bg / step_done_bg / step_inactive_bg | Step indicator colors |
accordion_header_bg / accordion_body_bg | Accordion colors |
separator_color | Dividers |
These values are resolved before the iframe renders. Client appearance can still override
many visual tokens at runtime via checkout.update({ appearance }).
White-label modes
Your account's white-label configuration controls Wajub co-branding:
| Mode | Behavior |
|---|---|
wajub | Wajub branding visible (default) |
co_branded | Merchant logo + Wajub badge |
full_white_label | Merchant branding only — Wajub logo hidden in overlay chrome |
White-label is configured in the Dashboard. The checkout iframe receives
showWajubBranding: false when mode is full_white_label.
Overlay modals (wajub.open()) show a locale/currency bar and optional Wajub footer based
on this setting — not configurable via SDK mount options.
Precedence
Dashboard branding → POST /payments theming → session branding → client appearance
(base) (per-payment) (at load) (runtime override)- Layout: client
layoutonmount()overrides session default when supported; otherwise use dashboardcheckout_layoutorbranding.layout. - Locale: client
localeoverrides session default. - Colors: client
appearancekeys merge on top of session branding inside the iframe.
When to use which layer
| Goal | Approach |
|---|---|
| Same look on every checkout | Dashboard branding only |
| Different branding per merchant (Sync) | Per-account dashboard branding or theming per payment |
| Dark mode toggle on your site | Client appearance.colorScheme + checkout.update() |
| One-off campaign colors | Client appearance only |
| Hide Wajub logo | Dashboard white-label → full_white_label |
Custom CSS
branding.custom_css (dashboard) injects merchant CSS into the checkout iframe. Prefer
appearance.rules for SDK-driven integrations so styles stay in your codebase.
Related API
- Create payment: POST /payments — optional
theming - Session payload: payment session
brandingblock (internal checkout API) - Client overrides: Appearance