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`	`'Ideal Sans', 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

Feedback & Validation

Variable	Default (Light)	Default (Dark)	Description
`colorError`	`#D32F2F`	`#FF6B6B`	Error text and icon color
`colorSuccess`	`#2E7D32`	`#4CAF50`	Success/approved state color
`inputBorderColorError`	`#D32F2F`	`#F87171`	Border color for invalid inputs
`inputBorderColorFocus`	`colorPrimary`	`colorPrimary`	Border color when a field is focused

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
`panelShadow`	`0 4px 12px rgba(0,0,0,0.1)`	Same	Panel drop shadow
`headerBackground`	`#003c66`	`#0f172a`	Header background
`headerColor`	`#242729`	`#f8fafc`	Header text color
`headerFontSize`	`18px`	Same	Header font size
`headerFontWeight`	`600`	Same	Header font weight
`headerPadding`	`16px`	Same	Header internal padding

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`	`transparent`	Same	Payment icon background
`paymentTitleColor`	`#25262d`	`#f8fafc`	Title color

Effects & Additional

Variable	Default	Description
`shadowFocus`	`0 0 0 2px white, 0 0 0 5px #4A98E9`	Focus ring shadow
`dividerColor`	`#E0E0E0`	Divider line color
`surchargeColor`	`#6E7087`	Surcharge text color
`securityTextColor`	`#6E7087`	Security message text color
`infoTextColor`	`#6E7087`	Information text color
`infoLinkColor`	`#0074C7`	Link color

Example Configuration

ui: {
    theme: "light",
    variables: {
        colorPrimary: "#FF4500",
        colorPrimaryHover: "#E13E00",
        colorPrimaryActive: "#CC3700",
        colorError: "#D32F2F",
        colorSuccess: "#2E7D32",
        inputBorderColorFocus: "#FF4500",
        fontFamily: "system-ui, -apple-system, \"Segoe UI\", Roboto, Arial, sans-serif",
        panelBorderRadius: "12px",
        paymentMethodBorderRadius: "12px"
    }
}