Appearance Reference

Complete list of appearance fields for Ozura Checkout. The hosted page uses a centered card layout on desktop (form left, summary right inside the card; brand bar above). Field names match the Checkout API.

Naming note: leftSideBackground styles the order summary panel (the visually right column inside the card). rightSideBackground styles the payment form panel (the visually left column). The names are historical; use the descriptions below, not the word “left/right” alone.

Global Colors

Key	Type	Description
`primaryColor`	Hex	Main brand color (accents, active payment-method border, default pay button chain)
`primaryHoverColor`	Hex	Hover for primary-colored controls
`secondaryColor`	Hex	Secondary accent where used
`backgroundColor`	Hex	Sets global/custom fallbacks (inputs, many panels). Not the outer lavender canvas—use `cssVariables.page-background` (see Customize Appearance).
`textColor`	Hex	Default text
`borderColor`	Hex	Borders and some dividers

Layout (Desktop — inside the card)

Key	Type	Description
`leftSideBackground`	Hex	Order summary panel background (right portion of the card)
`rightSideBackground`	Hex	Payment form panel background (left portion of the card)
`formBackground`	Hex	Form container background
`dividerColor`	Hex	Divider color; on mobile, used with `showTopDivider` for a line under the top section
`showTopDivider`	Boolean	When `true` and `dividerColor` is set, draws a divider under the mobile header area

Layout (Mobile)

Key	Type	Description
`mobileBackground`	Hex	Mobile sections (summary, donation block, etc.)
`mobileTopBackground`	Hex	Top branding / header band
`mobileBottomBackground`	Hex	Lower sections where applied
`mobileFormBackgroundColor`	Hex	Form area background
`mobileStickyTop`	Boolean	If `true`, pins the mobile branding header and order summary to the top of the viewport as the customer scrolls down to fill in the form

Typography

Key	Type	Description
`fontFamily`	String	Font stack (sanitized); does not style the fixed “Powered by OzuraPay” footer
`fontSize`	String	`sm`, `base`, `lg`, `xl` (drives scaled sizing on the page)
`fontWeight`	String	In API/types; not applied by checkout today

Spacing & Borders

Key	Type	Description
`spacing`	String	`compact`, `normal`, `spacious`
`borderRadius`	String	`none`, `sm`, `base`, `lg`, `xl`, `full`

Text Colors

Key	Type	Description
`headingTextColor`	Hex	Titles and headings (including merchant name styling chain)
`bodyTextColor`	Hex	Body text where wired
`labelTextColor`	Hex	Form labels
`formLabelTextColor`	Hex	Labels inside card/ACH sections
`secondaryTextColor`	Hex	Secondary/helper text
`amountTextColor`	Hex	Amount displays
`emailTextColor`	Hex	Email field
`cardTextColor`	Hex	Card payment fields
`achTextColor`	Hex	ACH / bank fields

Input Fields

Key	Type	Description
`inputBackgroundColor`	Hex	Input background
`inputBorderColor`	Hex	Default border (the new layout often uses borderless inputs with a focus ring; variable still applies where used)
`inputFocusBorderColor`	Hex	Focus border where used
`inputErrorBorderColor`	Hex	Error state

Primary Button (Pay / Donate)

Key	Type	Description
`buttonBackgroundColor`	Hex	Pay button background
`buttonHoverColor`	Hex	Pay button hover
`buttonBorderColor`	Hex	Pay button border

The button label (e.g. Pay $10.00 + Tax, Donate $25.00) is not a single appearance field—it is computed from donation mode, tax estimate, country, and tax-exempt flags.

Payment Method Selector

Key	Type	Description
`paymentMethodBorderColor`	Hex	Border around the payment method container and related inputs
`paymentMethodButtonBackgroundColor`	Hex	Inactive method tab background
`paymentMethodButtonHoverBackgroundColor`	Hex	Hover background
`paymentMethodButtonActiveBackgroundColor`	Hex	Selected method tab background
`paymentMethodButtonTextColor`	Hex	Method tab text
`paymentMethodIconColor`	Hex	Icons on method tabs

Mobile Text & Input Overrides

Key	Type	Description
`mobileHeadingTextColor`	Hex	Headings on mobile
`mobileAmountTextColor`	Hex	Amount on mobile
`mobileSecondaryTextColor`	Hex	Secondary text on mobile
`mobileLabelTextColor`	Hex	Labels on mobile
`mobileInputTextColor`	Hex	Input text on mobile
`mobileInputBackgroundColor`	Hex	Input background on mobile
`mobileInputBorderColor`	Hex	Input border on mobile
`mobileButtonBackgroundColor`	Hex	Pay button on mobile
`mobileButtonHoverColor`	Hex	Pay button hover on mobile
`mobileFormBackgroundColor`	Hex	Form section on mobile

Cancel Button

Key	Type	Description
`cancelButtonText`	String	Label (default: `Cancel and Return`)
`cancelButtonBackgroundColor`	Hex	Background
`cancelButtonTextColor`	Hex	Text color
`cancelButtonHoverColor`	Hex	Text color on hover (not background)
`cancelButtonBorderColor`	Hex	Border (`1px solid …` when set)

Branding

Key	Type	Description
`logoUrl`	URL	Logo image (HTTPS)
`logoPosition`	String	`inline` or `top`
`logoMaxHeight`	String	In API; not read by live logo component
`showMerchantName`	Boolean	Show name with logo (see Customize Appearance)
`hideBranding`	Boolean	In API; not used by the checkout page today

The store name comes from the required merchantName field when you create the session (stored on the session for the UI).

Cart Display (Itemized Checkout)

When using an items array:

Key	Type	Description
`cartFontFamily`	String	Font for cart block (falls back to `fontFamily`)
`cartProductNameColor`	Hex	Product name
`cartBrandColor`	Hex	Brand line
`cartDescriptionColor`	Hex	Description
`cartVariantColor`	Hex	Variant line
`cartCategoryColor`	Hex	Category
`cartSkuColor`	Hex	SKU
`cartPriceColor`	Hex	Price
`cartOriginalPriceColor`	Hex	Strikethrough price
`cartQuantityColor`	Hex	Quantity
`cartDiscountBadgeColor`	Hex	Discount badge background
`cartDiscountBadgeTextColor`	Hex	Discount badge text
`cartTaxFreeColor`	Hex	Tax-free indicator
`cartSubtotalColor`	Hex	Subtotal
`cartTotalColor`	Hex	Total
`cartTaxNoteColor`	Hex	Tax note text

Line content (images, badges, links) is controlled by each cart item field, not appearance.

API Warnings

Session and payment-link creation may return warnings (not errors) when colors fail WCAG contrast checks or mobile/desktop combinations look mismatched. Surface these in your dashboard when present.

Pre-Made Themes

Minimal Light

{
  "appearance": {
    "primaryColor": "#6366F1",
    "primaryHoverColor": "#4F46E5",
    "backgroundColor": "#FAFAFA",
    "textColor": "#1F2937",
    "fontFamily": "Poppins, sans-serif",
    "borderRadius": "lg"
  }
}

Violet Dark Mode

{
  "appearance": {
    "primaryColor": "#8b5cf6",
    "buttonBackgroundColor": "#8b5cf6",
    "leftSideBackground": "#0f0a1a",
    "rightSideBackground": "#1a0f2e",
    "formBackground": "#1a0f2e",
    "headingTextColor": "#ffffff",
    "textColor": "#e5e7eb",
    "inputBackgroundColor": "#1a0f2e",
    "inputBorderColor": "#8b5cf6",
    "cssVariables": {
      "page-background": "#0c0518"
    }
  }
}

Emerald Clean

{
  "appearance": {
    "primaryColor": "#10b981",
    "buttonBackgroundColor": "#10b981",
    "buttonHoverColor": "#059669",
    "inputFocusBorderColor": "#10b981",
    "borderRadius": "base"
  }
}

Custom CSS

Key	Type	Description
`customCss`	String	Raw CSS injected in a `<style>` block (max 10,000 characters; blocked patterns below)
`cssVariables`	Object	Keys become `--custom-{key}` on the document root. Values are sanitized as colors or size/dimension values (`px`, `em`, `%`, etc.) — values that parse as neither are silently dropped. Max 100 entries; values max 200 characters.

Security Restrictions

These patterns cause customCss to be rejected (and may fail API validation):

url(
@import
javascript:
expression(
behavior:, binding:, -moz-binding, -webkit-binding
CSS hex escape sequences (e.g. \3c)

Available CSS Classes (non-exhaustive)

Class	What It Styles
`.checkout-container`	Root container
`.checkout-form-container`	Payment form wrapper
`.checkout-input`	Text inputs (legacy class; many fields use shared checkout styles)
`.checkout-submit-button`	Primary pay button
`.checkout-error`	Error messages

Example: Gradient Button

{
  "appearance": {
    "primaryColor": "#10b981",
    "customCss": ".checkout-submit-button { background: linear-gradient(135deg, #10b981, #059669); }"
  }
}

Getting Started

Vault

Payments

Appearance Reference

Global Colors

Layout (Desktop — inside the card)

Layout (Mobile)

Typography

Spacing & Borders

Text Colors

Input Fields

Primary Button (Pay / Donate)

Payment Method Selector

Mobile Text & Input Overrides

Cancel Button

Branding

Cart Display (Itemized Checkout)

API Warnings

Pre-Made Themes

Minimal Light

Violet Dark Mode

Emerald Clean

Custom CSS

Security Restrictions

Available CSS Classes (non-exhaustive)

Example: Gradient Button

​Global Colors

​Layout (Desktop — inside the card)

​Layout (Mobile)

​Typography

​Spacing & Borders

​Text Colors

​Input Fields

​Primary Button (Pay / Donate)

​Payment Method Selector

​Mobile Text & Input Overrides

​Cancel Button

​Branding

​Cart Display (Itemized Checkout)

​API Warnings

​Pre-Made Themes

​Minimal Light

​Violet Dark Mode

​Emerald Clean

​Custom CSS

​Security Restrictions

​Available CSS Classes (non-exhaustive)

​Example: Gradient Button

Global Colors

Layout (Desktop — inside the card)

Layout (Mobile)

Typography

Spacing & Borders

Text Colors

Input Fields

Primary Button (Pay / Donate)

Payment Method Selector

Mobile Text & Input Overrides

Cancel Button

Branding

Cart Display (Itemized Checkout)

API Warnings

Pre-Made Themes

Minimal Light

Violet Dark Mode

Emerald Clean

Custom CSS

Security Restrictions

Available CSS Classes (non-exhaustive)

Example: Gradient Button