Skip to main content
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

OptionDescriptionExample
primaryColorMain brand color (accents, selected payment method border, default pay button chain)"#4F46E5"
primaryHoverColorPrimary hover"#4338CA"
secondaryColorSecondary accents where used"#64748B"
backgroundColorSets 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"
textColorDefault text"#111827"
borderColorBorders and some dividers"#D1D5DB"
buttonBackgroundColorPay button background (overrides primaryColor for the button)"#4F46E5"
buttonHoverColorPay button hover"#4338CA"
OptionDescriptionExample
logoUrlHTTPS URL to your logo"https://mystore.com/logo.png"
logoPositioninline (default) or top"inline"
logoMaxHeightPresent in the API model; not applied by the live page today (logo size follows logoPosition and viewport)."50px"
showMerchantNameIf 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)

OptionDescriptionExample
leftSideBackgroundOrder summary column (visually the right side of the card)"#F9FAFB"
rightSideBackgroundPayment form column (visually the left side of the card)"#FFFFFF"
formBackgroundForm container / panel fill"#FFFFFF"
mobileBackgroundMobile sections (summary, donation block, etc.)"#FFFFFF"
borderRadiusCorner 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"
  }
}

{
  "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 treated as colors by the checkout app. Use customCss for non-color styling (within security limits).

​
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).