Customize Appearance

Brand the hosted checkout page with your colors, logo, and typography. Pass an appearance object when you create a session or payment link.

Current checkout layout: On desktop, the customer sees a soft outer page background (default lavender) with a single centered card (~960px): payment form on the left (~56%) and order summary on the right (~44%), plus a brand bar above the card. On mobile, branding and summary stack above the form. There is no API flag to switch to a different layout.

The full field list and edge cases (including fields accepted by the API but not yet used in the UI) are in the Appearance Reference.

Basic Customization

{
  "merchantId": "your_merchant_id",
  "merchantName": "My Store",
  "amount": "25.00",
  "successUrl": "https://mystore.com/success",
  "cancelUrl": "https://mystore.com/cancel",
  "errorUrl": "https://mystore.com/error",
  "appearance": {
    "primaryColor": "#4F46E5",
    "buttonBackgroundColor": "#4F46E5",
    "textColor": "#111827"
  }
}

merchantName is required when creating a session; it is stored on the session and drives the store title next to your logo (it is not set through appearance alone).

Appearance Options (common)

Colors

Option	Description	Example
`primaryColor`	Main brand color (accents, selected payment method border, default pay button chain)	`"#4F46E5"`
`primaryHoverColor`	Primary hover	`"#4338CA"`
`secondaryColor`	Secondary accents where used	`"#64748B"`
`backgroundColor`	Sets global/custom fallbacks (inputs, many panels). Not the outer lavender canvas behind the desktop card—use `cssVariables` with key `page-background` for that (see reference).	`"#FFFFFF"`
`textColor`	Default text	`"#111827"`
`borderColor`	Borders and some dividers	`"#D1D5DB"`
`buttonBackgroundColor`	Pay button background (overrides `primaryColor` for the button)	`"#4F46E5"`
`buttonHoverColor`	Pay button hover	`"#4338CA"`

Logo

Option	Description	Example
`logoUrl`	HTTPS URL to your logo	`"https://mystore.com/logo.png"`
`logoPosition`	`inline` (default) or `top`	`"inline"`
`logoMaxHeight`	Present in the API model; not applied by the live page today (logo size follows `logoPosition` and viewport).	`"50px"`
`showMerchantName`	If `true`, show name with logo. If omitted/false with a logo, logo only. Without `logoUrl`, the name always shows.	`true`

Layout (inside the desktop card)

Option	Description	Example
`leftSideBackground`	Order summary column (visually the right side of the card)	`"#F9FAFB"`
`rightSideBackground`	Payment form column (visually the left side of the card)	`"#FFFFFF"`
`formBackground`	Form container / panel fill	`"#FFFFFF"`
`mobileBackground`	Mobile sections (summary, donation block, etc.)	`"#FFFFFF"`
`borderRadius`	Corner scale for themed controls	`"lg"`

Valid borderRadius values: none, sm, base, lg, xl, full.

Example: Dark panels

{
  "appearance": {
    "primaryColor": "#8B5CF6",
    "buttonBackgroundColor": "#8B5CF6",
    "buttonHoverColor": "#7C3AED",
    "backgroundColor": "#1F2937",
    "textColor": "#F9FAFB",
    "borderColor": "#374151",
    "leftSideBackground": "#111827",
    "rightSideBackground": "#1F2937",
    "formBackground": "#374151"
  }
}

Example: Brand colors + logo

{
  "appearance": {
    "primaryColor": "#FF6B00",
    "primaryHoverColor": "#E55D00",
    "logoUrl": "https://mystore.com/logo.png",
    "showMerchantName": true
  }
}

Outer page background (desktop)

The area behind the centered card uses CSS variable --custom-page-background (default lavender). Set it via appearance.cssVariables:

{
  "appearance": {
    "primaryColor": "#4F46E5",
    "cssVariables": {
      "page-background": "#EEF2FF"
    }
  }
}

Values in cssVariables are sanitized as colors or size/dimension values (e.g. px, em, %). Values that don’t parse as either are silently dropped. Use customCss for arbitrary styling (within security limits).

As a shorthand, you can also set pageBackground directly in the appearance object instead of via cssVariables:

{
  "appearance": {
    "primaryColor": "#4F46E5",
    "pageBackground": "#EEF2FF"
  }
}

Both forms are equivalent. cssVariables.page-background takes precedence if both are set.

Full options

See the Appearance Reference for every key, mobile overrides, cart colors, customCss, accessibility warnings, and limitations (for example pay button label is derived from tax context—not a single appearance string).

Getting Started

Vault

Payments

Customize Appearance

Basic Customization

Appearance Options (common)

Colors

Logo

Layout (inside the desktop card)

Example: Dark panels

Example: Brand colors + logo

Outer page background (desktop)

Full options

​Basic Customization

​Appearance Options (common)

​Colors

​Logo

​Layout (inside the desktop card)

​Example: Dark panels

​Example: Brand colors + logo

​Outer page background (desktop)

​Full options

Basic Customization

Appearance Options (common)

Colors

Logo

Layout (inside the desktop card)

Example: Dark panels

Example: Brand colors + logo

Outer page background (desktop)

Full options