Brand the payment page - Hosted checkout

Make the hosted payment page look like your store — colours, font, logo, merchant name, Pay button label, corner style, and light or dark mode. Save a look once as a branding profile, then adjust it for a single checkout when you need to.

Set up your branding

Ask support to create a branding profile

Contact support with the settings you want (see What you can change). Profiles belong to your merchant account, not to one outlet, and you can have as many as you need — one of them is your default. A self-serve merchant portal (Payment Gateway → Checkout → Branding, with the same settings) is planned.

Create a sandbox checkout session

Your default profile applies automatically — no extra field needed. To use a different profile, send its ID as branding_profile_id; support shares the IDs when they set up extra profiles.

Check it in light and dark mode

Open the session’s payment page, then add ?theme=light, ?theme=dark, or ?theme=auto to the URL to preview each mode. This overrides the profile’s color_scheme for that page load only. There’s no separate preview tool.

Repeat in production

Sandbox and production are separate: set up profiles in each environment. Profile IDs differ between them.

Override branding for one checkout

Send a branding object when you create a checkout session to change individual settings for that checkout only — for example a per-language Pay label, a campaign colour, or matching an embedded checkout to the surrounding page:

#!/usr/bin/env bash
# Overrides branding for this checkout only — the `branding` object replaces
# individual fields of the resolved profile (branding_profile_id, or your
# default profile); omitted fields keep the profile value. See the Branding
# guide in the RadiumOne docs.
set -euo pipefail

CHECKOUT_BASE="${RADIUMONE_CHECKOUT_BASE:-https://checkout-sandbox.radiumone.io}"
: "${RADIUMONE_SECRET_KEY:?set RADIUMONE_SECRET_KEY to your r1sk_* secret key}"

curl -sS -X POST "$CHECKOUT_BASE/api/v1/checkout/sessions" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $RADIUMONE_SECRET_KEY" \
  -d @request.json

#!/usr/bin/env node
// Overrides branding for this checkout only — the `branding` object replaces
// individual fields of the resolved profile (branding_profile_id, or your
// default profile); omitted fields keep the profile value. Node 18+ ESM
// fetch. Env: RADIUMONE_SECRET_KEY, RADIUMONE_CHECKOUT_BASE (optional).
import { readFileSync } from "node:fs";

const CHECKOUT_BASE = process.env.RADIUMONE_CHECKOUT_BASE || "https://checkout-sandbox.radiumone.io";
const secretKey = process.env.RADIUMONE_SECRET_KEY;
const body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url)));

async function createCheckoutSessionWithBrandingOverride() {
  const res = await fetch(`${CHECKOUT_BASE}/api/v1/checkout/sessions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": secretKey,
    },
    body: JSON.stringify(body),
  });
  const payload = await res.json();
  if (!res.ok) {
    throw new Error(`checkout session create failed: ${payload.code ?? payload.type} (${res.status})`);
  }
  return payload;
}

createCheckoutSessionWithBrandingOverride().then((r) => console.log(JSON.stringify(r, null, 2)));

#!/usr/bin/env python3
"""Overrides branding for this checkout only -- the ``branding`` object
replaces individual fields of the resolved profile (``branding_profile_id``,
or your default profile); omitted fields keep the profile value.
"""
import json
import os
from pathlib import Path

import requests

CHECKOUT_BASE = os.environ.get("RADIUMONE_CHECKOUT_BASE", "https://checkout-sandbox.radiumone.io")


def create_checkout_session_with_branding_override() -> dict:
    body = json.loads((Path(__file__).parent / "request.json").read_text())
    resp = requests.post(
        f"{CHECKOUT_BASE}/api/v1/checkout/sessions",
        json=body,
        headers={"X-Api-Key": os.environ.get("RADIUMONE_SECRET_KEY", "")},
        timeout=30,
    )
    payload = resp.json()
    if not resp.ok:
        code = payload.get("code") or payload.get("type")
        raise RuntimeError(f"checkout session create failed: {code} ({resp.status_code})")
    return payload


if __name__ == "__main__":
    print(json.dumps(create_checkout_session_with_branding_override(), indent=2))

branding accepts the same fields as a profile: display_name, logo_url, the nine colours, border_radius, font_family, color_scheme, and button_text.
Every field is optional. Fields you leave out keep the profile’s value; branding: {} is the same as leaving it out.
An unknown field or an invalid value returns 400 validation:invalid_input naming the field. That includes a blank display_name or button_text — leave the field out to keep the profile’s value.

How branding is chosen

For each setting, the first of these that has a value wins:

The session’s branding object.
The profile named by branding_profile_id — or your default profile when you leave it out.
The standard RadiumOne look.

An unknown, deleted, or another merchant’s branding_profile_id quietly uses your default profile, with no error. With no default profile, the standard RadiumOne look applies.
branding_profile_id is at most 64 characters (profile IDs are UUIDs); a longer value returns 400.
Branding is fixed when the session is created. A profile change, or a new default, applies to the next session; sessions already created keep their look until they end.
Embedded and redirect checkouts use the same branding. Embedded mode has no page header, so the logo and merchant name don’t appear.

Match your site

An embedded checkout runs in a RadiumOne iframe, so your page’s CSS can’t reach inside it — there’s no supported way to style it with your own stylesheet. To match your site, use the settings above instead: a branding profile, or a per-session branding object with, for example, background_color, font_family, border_radius, and color_scheme to blend with the surrounding page.

What you can change

Colours

Each colour is #RRGGBB, in either case. Marker numbers below match the Colours table’s # column.

#	Setting	Where it shows
1	`primary_color`	Main accent: borders and icons on the selected payment method and instalment bank, links, checkboxes, tabs, sliders, focus rings, and icons on the processing and success screens
2	`button_color`	Background of the Pay button and other primary buttons
3	`button_text_color`	Label on primary buttons, badges, checkbox ticks, and loading spinners
4	`focus_color`	Border and glow of the focused text or card field — defaults to `primary_color`
5	`background_color`	Page background in light mode; body text switches between black and white to stay readable
6	`accent_color`	Selection highlight: background of the option the shopper has selected — the selected payment method and the selected bank in instalment options (instalments are coming soon). Borders and icons on the selected option use `primary_color`. Choose a pale tint of your brand colour, since shopper-facing text sits on top of it
7	`success_color`	Success screen, completed-field ticks, redeemed rewards, and “interest-free” instalment labels
8	`warning_color`	Test-mode banner and interest-bearing instalment labels
9	`error_color`	Alerts, field errors, and the countdown when time is nearly up

Style

Setting	Values
`border_radius`	Corners of fields, card fields, and buttons: `square` (4px), `rounded` (12px), or `pill` (24px)
`font_family`	One of the allowed fonts
`color_scheme`	`light`, `dark`, or `auto` (follows the shopper’s device) — see Light and dark mode

Name, logo, and Pay button

Setting	What it does
`display_name`	Merchant name in the page header, the logo’s alternative text, the “Back to …” tooltip, and the success screen. Without it, your registered merchant name is used
`logo_url`	Logo in the page header — see Logo
`button_text`	Pay button label, shown before the amount (for example “Place order S$49.99”). Shown exactly as entered in every locale; leave it blank to use the page’s translated label (“Pay” in English, “支付” in Chinese)

For a Pay label in each shopper’s language, leave button_text blank on the profile and send button_text in the session’s branding object, based on the session’s locale.

Fonts

Use one of these values, exactly as written (case-sensitive):

System fonts — the shopper’s device fonts: system-ui, -apple-system, sans-serif, serif, monospace
Latin web fonts — served by RadiumOne, so shoppers don’t need them installed: Inter, Roboto, Open Sans, Lato, Montserrat, Poppins, Source Sans Pro, Noto Sans, Raleway, PT Sans
Asian-script web fonts — also served by RadiumOne: Noto Sans SC, Noto Sans TC, Noto Sans JP, Noto Sans KR, Noto Sans Thai

Fonts load only when a page uses them. Card number, expiry, and security code fields always use a monospace font.

Logo

Shown 40px tall and up to 180px wide, keeping its proportions.
For best results, use a horizontal SVG or transparent PNG, at least 80px tall for sharp screens, and keep the file small.
logo_url must be an absolute https:// URL with a hostname, with no spaces or control characters, up to 2048 characters.
RadiumOne doesn’t upload, host, cache, or proxy your logo — the shopper’s browser loads it from your URL, and there’s no format or file-size check.
With no logo, or if it fails to load, the header shows display_name (or your merchant name).

Light and dark mode

Your colours are used as-is in both modes, except accent_color: in dark mode the page shows a darker blend of it so a pale tint doesn’t glare. Dark mode also swaps the page background and surfaces to a fixed dark palette (#1a1a2e, surfaces #16213e) with white body text.

RadiumOne doesn’t check contrast. Body text is automatically black or white against the background, but other combinations — for example white text on a yellow button — show exactly as set. Pick primary, button, and status colours that read well on both white and dark navy, and preview both modes.

Standard RadiumOne look

Used when no profile applies, and for any setting your profile doesn’t set:

Setting	Default
`primary_color`, `button_color`, `focus_color`	`#0070f0`
`accent_color`	`#f0f4ff`
`background_color`, `button_text_color`	`#ffffff`
`success_color` / `warning_color` / `error_color`	`#22c55e` / `#f59e0b` / `#ef4444`
`border_radius`	`rounded` (12px)
`font_family`	`system-ui`
`color_scheme`	`light`
`button_text`	Translated label (“Pay” / “支付”)
`logo_url`, `display_name`	None — the header shows your merchant name

Rules and limits

The same rules apply to saved profiles and to the session’s branding object.

display_name — 1–100 Unicode code points after leading and trailing spaces are removed.
button_text — up to 30 Unicode code points after trimming (a profile can leave it blank).
Code points aren’t always visible characters — a plain 👍 counts as 1, 👍🏽 (with a skin-tone modifier) as 2, and a family emoji as up to 7.
Characters — display_name and button_text can’t contain control characters or invisible formatting characters (zero-width spaces, text-direction overrides) anywhere, including at the start or end. Zero-width joiners and non-joiners are allowed, since some emoji and scripts need them.
Invalid values are rejected when a profile is saved. If a profile still holds an older value the page can’t use (for example a font from before the allowed list), only that setting falls back — main colours, font, and colour scheme use the RadiumOne default, other settings are left unset — and the rest of the profile still applies.
Deleting profiles — a default profile can’t be deleted until another profile is set as the default. If a profile that open sessions use is deleted, those sessions keep their branding, and new sessions naming the deleted ID get your default profile.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Brand the payment page - Hosted checkout

Set up your branding

Override branding for one checkout

How branding is chosen

Match your site

What you can change

Colours

Style

Name, logo, and Pay button

Fonts

Logo

Light and dark mode

Standard RadiumOne look

Rules and limits

Next steps

Customize checkout

Embed hosted checkout

​Set up your branding

​Override branding for one checkout

​How branding is chosen

​Match your site

​What you can change

​Colours

​Style

​Name, logo, and Pay button

​Fonts

​Logo

​Light and dark mode

​Standard RadiumOne look

​Rules and limits

​Next steps

Customize checkout

Embed hosted checkout

Set up your branding

Override branding for one checkout

How branding is chosen

Match your site

What you can change

Colours

Style

Name, logo, and Pay button

Fonts

Logo

Light and dark mode

Standard RadiumOne look

Rules and limits

Next steps