PayUI Customisation

PayUI supports comprehensive visual customisation through CSS custom properties, allowing you to match the payment form to your brand identity.

Theme Options

PayUI supports two built-in themes:

ui: { theme: "light" }  // Light theme (default)
ui: { theme: "dark" }   // Dark theme

CSS Custom Properties

Customise the appearance using CSS variables in the ui.variables object. All variables support both light and dark themes automatically.

Layout note: PayUI uses an optimized, responsive layout for payment fields. Customisation is visual (colors, spacing, typography), not structural (field order or column layout).

Brand Colors

Variable	Default (Light)	Default (Dark)	Description
`colorPrimary`	`#0074C7`	`#4f96ff`	Primary brand color (buttons, links, focus)
`colorPrimaryHover`	`#005C9E`	`#3b82f6`	Primary hover state
`colorPrimaryActive`	`#004A80`	`#2563eb`	Primary active/pressed state
`colorSecondary`	`#6E7087`	`#64748b`	Secondary accent color
`colorBackground`	`#FFFFFF`	`#0f172a`	Main background
`colorText`	`#242729`	`#f8fafc`	Primary text
`colorTextSecondary`	`#6E7087`	`#94a3b8`	Secondary text

// Example: Orange brand theme
variables: {
    colorPrimary: '#FF4500',
    colorPrimaryHover: '#E13E00',
    colorPrimaryActive: '#CC3700'
}

Typography

Variable	Default	Description
`fontFamily`	`ui-sans-serif, system-ui, sans-serif`	Primary font family
`fontSizeBase`	`14.22px`	Base font size
`fontWeightMedium`	`500`	Medium weight for labels
`fontWeightNormal`	`400`	Normal font weight

Important: Only use system fonts for fontFamily. Loading external web fonts from CDNs is not supported to maintain PCI compliance and iframe security. You may specify brand fonts (for example, Inter) but they will only render if the font is already installed on the customer’s device.

Example system font stacks:

Inter, system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif

"Helvetica Neue", Helvetica, Arial, system-ui, sans-serif

Form Controls

Variable	Default (Light)	Default (Dark)	Description
`inputHeight`	`40px`	Same	Input field height
`inputPadding`	`8px`	Same	Input internal padding
`inputBackground`	`#FFFFFF`	`#1e293b`	Input background
`inputBorderColor`	`#707689`	`#475569`	Input border color
`inputBorderColorHover`	`#245B9C`	`#64748b`	Input border on hover
`inputPlaceholderColor`	`#717688`	`#94a3b8`	Placeholder text color
`borderRadius`	`2px`	Same	Corner radius
`borderWidth`	`1px`	Same	Border width
`borderColor`	`#D7DCE1`	`#334155`	General border color
`spacingUnit`	`8px`	Same	Base spacing unit (margins, gaps)
`buttonHeight`	`40px`	Same	Button height
`buttonPadding`	`8px 16px`	Same	Button padding

Labels

Variable	Default (Light)	Default (Dark)	Description
`labelColor`	`#707689`	`#e2e8f0`	Label text color
`labelFontSize`	`14.22px`	Same	Label font size
`labelFontWeight`	`500`	Same	Label font weight

Panel & Container

Variable	Default (Light)	Default (Dark)	Description
`panelBackground`	`#FFFFFF`	`#1e293b`	Panel background
`panelBorderRadius`	`8px`	Same	Panel corner radius
`panelPadding`	`24px`	Same	Panel internal padding
`panelGap`	`12px`	Same	Gap between panel sections
`panelShadow`	`0 4px 12px rgba(0,0,0,0.1)`	Same	Panel drop shadow

Payment Method Selector

Variable	Default (Light)	Default (Dark)	Description
`paymentMethodBackground`	`#fcfcfc`	`#15202b`	Card background
`paymentMethodBorder`	`#d7dce1`	`#475569`	Card border
`paymentMethodBorderHover`	`#0071ba`	`#64748b`	Card border on hover
`paymentMethodBorderRadius`	`8px`	Same	Card corner radius
`paymentMethodPadding`	`16px`	Same	Card padding
`paymentIconBackground`	`#eeeeee`	`#e2e8f0`	Payment icon background
`paymentIconSize`	`48px`	Same	Payment icon size
`paymentIconRadius`	`50px`	Same	Payment icon border radius
`paymentTitleColor`	`#25262d`	`#f8fafc`	Title color
`paymentTitleFontSize`	`18px`	Same	Title font size

Effects & Additional

Variable	Default (Light)	Default (Dark)	Description
`shadowFocus`	`0 0 0 2px white, 0 0 0 5px #4A98E9`	Same	Focus ring shadow
`dividerColor`	`#E0E0E0`	`#cbd5e0`	Divider line color
`infoTextColor`	`#394046`	`#cbd5e0`	Information text color
`infoTextFontSize`	`12.64px`	Same	Information text font size
`infoTextLineHeight`	`18.96px`	Same	Information text line height
`noticeTextColor`	`#6c757d`	`#cbd5e0`	Notice text color (e.g. surcharge notice)
`noticeTextFontSize`	`14px`	Same	Notice text font size
`noticeTextLineHeight`	`1.4`	Same	Notice text line height
`linkColor`	`#0074C7`	`#4f96ff`	Link color

Amount Display

The ui.amountDisplay property controls how the payment amount is shown inside the Pay Now button:

Value	Button label example
`"none"`	PAY NOW
`"amount"`	PAY $30.00
`"amountWithCurrencyCode"`	PAY $30.00 AUD (default)

Example Configuration

ui: {
    theme: "light",
    variables: {
        colorPrimary: "#FF4500",
        colorPrimaryHover: "#E13E00",
        colorPrimaryActive: "#CC3700",
        fontFamily: "system-ui, -apple-system, \"Segoe UI\", Roboto, Arial, sans-serif",
        panelBorderRadius: "12px",
        paymentMethodBorderRadius: "12px"
    },
    amountDisplay: "none"
}