Customize look and feel

Customize the visual appearance of the Onerway Web SDK checkout using built-in themes, CSS variables, custom stylesheets, and fine-grained style overrides.

Onerway Web SDK provides multiple ways to customize the checkout appearance to match your brand.

Method	Best for	Complexity
Built-in themes	Quickly switch between preset styles	Low
CSS variables	Adjust global design tokens like colors and fonts	Low–Medium
Custom stylesheet	Inject an external CSS file to override styles	Medium
Fine-grained style overrides	Precisely control specific UI elements	High

All style customizations take effect only at SDK initialization. Dynamic changes at runtime are not reflected in the checkout UI.

Built-in themes

The SDK ships with several preset themes. Use the checkoutTheme parameter to switch the overall style quickly.

const pacypay = new Pacypay(transactionId, {
  container: 'onerway_checkout',
  locale: 'en',
  environment: 'sandbox',
  mode: 'CARD',
  redirectUrl: redirectUrlFromServer,
  config: {
    checkoutTheme: 'dark'
  }
})

checkoutTheme is ignored in the following cases:

customCssURL is also provided
cssVariables is also provided

To use a built-in theme, make sure neither of those parameters is passed.

Supported theme values: default (light, default), dark.

CSS variables

Pass design tokens through the cssVariables parameter to override global visual properties without writing an external stylesheet.

const pacypay = new Pacypay(transactionId, {
  container: 'onerway_checkout',
  locale: 'en',
  environment: 'sandbox',
  mode: 'CARD',
  redirectUrl: redirectUrlFromServer,
  config: {
    cssVariables: {
      '--primary-color': '#6750A4',
      '--background-color': '#FFFBFE',
      '--text-color': '#1C1B1F',
      '--border-color': '#CAC4D0',
      '--border-radius': '12px',
      '--font-family': 'Roboto, sans-serif',
      '--font-size': '16px'
    }
  }
})

Available CSS variables

Variable	Description	Example value
`--primary-color`	Primary color (buttons, highlights, etc.)	`#6750A4`
`--background-color`	Checkout background color	`#FFFBFE`
`--text-color`	Primary text color	`#1C1B1F`
`--border-color`	Input field and divider border color	`#CAC4D0`
`--border-radius`	Global border radius	`12px`
`--font-family`	Font family	`Roboto, sans-serif`
`--font-size`	Base font size	`16px`

Custom stylesheet

Pass an external CSS file URL via customCssURL. The SDK injects the stylesheet when the checkout loads.

const pacypay = new Pacypay(transactionId, {
  container: 'onerway_checkout',
  locale: 'en',
  environment: 'sandbox',
  mode: 'CARD',
  redirectUrl: redirectUrlFromServer,
  config: {
    customCssURL: 'https://merchant.example.com/checkout-theme.css'
  }
})

When using customCssURL:

The stylesheet must be served over HTTPS, and the server must include the correct CORS headers to allow cross-origin loading from the SDK domain.
When customCssURL is provided, both checkoutTheme and cssVariables are ignored.
Prefer overriding CSS variables in your stylesheet rather than targeting internal selectors directly, to reduce compatibility risk across SDK upgrades.

Fine-grained style overrides

When CSS variables and custom stylesheets are not enough, use styleOverrides to pass precise style rules for specific UI elements.

const pacypay = new Pacypay(transactionId, {
  container: 'onerway_checkout',
  locale: 'en',
  environment: 'sandbox',
  mode: 'CARD',
  redirectUrl: redirectUrlFromServer,
  config: {
    styleOverrides: {
      '.checkout-submit-btn': {
        'background-color': '#6750A4',
        'border-radius': '8px',
        'font-weight': '600'
      },
      '.checkout-input-field': {
        'border-color': '#CAC4D0',
        'border-radius': '4px'
      }
    }
  }
})

CSS class names in styleOverrides are tied to the SDK's internal implementation and may change across SDK versions. Run regression tests before upgrading.

Available CSS classes

CSS class	Description
`.checkout-container`	Overall checkout container
`.checkout-header`	Top header area
`.checkout-logo`	Merchant logo area
`.checkout-form`	Payment form container
`.checkout-input-field`	Input fields (card number, expiry, etc.)
`.checkout-input-label`	Input field label text
`.checkout-input-error`	Input field error message text
`.checkout-select-field`	Dropdown select field
`.checkout-submit-btn`	Submit / pay button
`.checkout-submit-btn:hover`	Submit button hover state
`.checkout-submit-btn:disabled`	Submit button disabled state
`.checkout-cancel-btn`	Cancel button
`.checkout-amount-display`	Amount display area
`.checkout-currency-symbol`	Currency symbol
`.checkout-order-summary`	Order summary area
`.checkout-divider`	Divider line
`.checkout-footer`	Footer area (security badges, etc.)
`.checkout-loading-overlay`	Loading overlay
`.checkout-error-banner`	Global error notification banner

Combining options

You can combine multiple customization methods. Priority order: styleOverrides > customCssURL > cssVariables. When customCssURL is provided, checkoutTheme and cssVariables are ignored.

const pacypay = new Pacypay(transactionId, {
  container: 'onerway_checkout',
  locale: 'en',
  environment: 'sandbox',
  mode: 'CARD',
  redirectUrl: redirectUrlFromServer,
  config: {
    // Set global design tokens with CSS variables
    cssVariables: {
      '--primary-color': '#6750A4',
      '--border-radius': '12px',
      '--font-family': 'Roboto, sans-serif'
    },
    // Fine-tune specific elements with style overrides
    styleOverrides: {
      '.checkout-submit-btn': {
        'font-weight': '700',
        'letter-spacing': '0.5px'
      }
    }
  }
})

Build a subscription integration

Integrate subscription payments with the Onerway Web SDK (SUBSCRIBE), with support for both managed and self-managed renewal models.

Overview

Understand Onerway Direct API in a server-to-server integration model