Skip to content
/
SDK reference

Last updated: 27 May 2026 | Change log

SDK reference

Namespaces and core methods

Our Components SDK exposes its functionality through a global namespace and a set of core methods.

ParameterTypeDescription
WorldpayObjectGlobal namespace attached to the window object.
componentsObjectComponents product namespace.
initFunctionInitialization method accepting a config object.

Usage example

Worldpay.components.init(config)

Triggers

Triggers allow you to programmatically interact with the Payment UI, such as submitting forms or selecting specific payment methods without direct user action, or displaying QR codes for supported payment methods.

ParameterTypeDescription
selectFunctionSelects a payment method using a method parameter.
submitFunctionSubmits the payment form programmatically.
continueFunctionAccepts method and data (generated via a server-side call to the APM service) and allows the SDK to display the next available step for the selected payment method. Note: Only applicable for QR code-specific payment methods.
resetProcessingFunctionResets the SDK's processing state (clears the overlay, and re-enables interactivity).

Usage example

const components = Worldpay.components.init(config)

components.select('swish')

components.submit()

// WeChat Pay QR code flow
components.continue('wechatpay', {
    qrCode: 'iVBORw0KGgoAAAANSUhEUgAABbQAAAW0AQ...'
})

// Pix flow with QR and transaction code
components.continue('pix', {
    qrCode: 'iVBORw0KGgoAAAANSUhEUgAABbQAAAW0AQ...',
    transactionCode: '00020101021226930014br.gov.bcb.pix2571qrcode-h.pix.celcoin.com.br/...',
})

// Swish QR code flow
components.continue('swish', {
    qrCode: 'iVBORw0KGgoAAAANSUhEUgAABbQAAAW0AQ...'
})

// Swish phone notification flow
components.continue('swish')

Lifecycle hooks

Lifecycle hooks enable you to respond to various stages of the payment UI, attach custom interactivity, and handle events such as loading, selection, success, or errors.

ParameterTypeDescription
onLoadFunctionCalled when the payment UI is loaded.
onSelectFunctionCalled when a payment method is selected (with method and selector parameters).
onSuccessFunctionCalled when the form is successfully submitted (with session and method parameters).
onErrorFunctionCalled when a submission fails (with error, method, selector parameters).

Usage example

Worldpay.components.init(config)
  .onLoad(() => { /* hide loading animation */ }),
  .onSelect((method, selector) => { /* handle selection */ }),
  .onSuccess((session, method) => { /* handle success by passing the session to own endpoint via server-side call */ }),
  .onError((error, method, selector) => { /* handle error */ })

config Object

The config object is crucial for initializing the SDK and customizing the payment experience.

ParameterTypeRequired?Description
idstringtickCheckout merchant ID.
baseUrl.stringtickThe URL to our try/live environment.
selectorstringtickDOM selector for payment UI container.
transactionObjecttickTransaction details.
themestringcrossTheme: default or dark.
stylesObjectcrossCustom styling configuration.
elementsArray ObjectcrossControls rendering of payment elements.
advancedConfigurationObjectcrossAdvanced options.
loadingSkeletonbooleancrossEnables loading animation.

Usage example:

const config = {
  id: "your-checkout-id",
  baseUrl: "https://try.access.worldpay-bsh.securedataplatform.com",
  selector: "#checkout-container",
  transaction: {
    amount: 2500,
    currency: "USD",
    countryCode: "US"
  },
  theme: "default",
  styles: {
    ':root': {
      '--base-font-size': '16px',
      '--font-family': 'Inter, Helvetica, Arial, sans-serif',
      '--color-primary': '#1b1b6f',
      '--color-background': '#ffffff',
      '--color-error': '#dd1308',
      '--color-content-primary': '#17171c',
      '--color-content-secondary': '#6a6e87'
    },
    '.Item': {
      'padding': '2rem 1rem',
      'border': '1px solid grey'
    }
  },
  elements: [
    {
      element: "accordion",
      methods: [
        { name: "paypal" },
      ]
    }
  ],
  advancedConfiguration: {
    additionalFields: ["name", "email", "shippingAddress", "billingAddress"]
  },
  loadingSkeleton: true
};

Worldpay.components.init(config)
  .onSuccess((session) => { /* handle success */ }),

elements Array

ParameterTypeRequired?Description
elementstringtickSpecifies the element type for this UI section. Supported values: accordion, tabs, or solitary.
methodsArray ObjecttickList of payment methods for this element. Each object should specify a supported method key.

Usage example

Worldpay.init({
  // ...other config
  elements: [
    {
      element: 'accordion'
      methods: [
        { name: 'paypal' },
        { name: 'sepa' },
        { name: 'klarna' }
      ]
    }
  ]
})

transaction Object

ParameterTypeRequired?Description
amountnumbertickTransaction amount.
currencystringtickISO 4217 currency code (e.g., "USD", "EUR").
countryCodestringtickISO 3166 country code (e.g., "US", "GB").

Usage example

Worldpay.init({
    // ...other config
    transaction: {
        amount: 10000,
        currency: 'GBP',
        countryCode: 'GB',
    },
})

styles Object

Customizes appearance of the payment UI. Accepts CSS-in-JS style properties.

ParameterTypeRequired?Description
:rootObjectcrossCSS variables for theming and global styles.
Any selectorObjectcrossAny valid CSS selector supported.

Usage example

Worldpay.init({
    // ...other config
    styles: {
        ':root': {
          '--base-font-size': '16px',
          '--font-family': 'Inter, Helvetica, Arial, sans-serif',
          '--color-primary': '#1b1b6f',
          '--color-background': '#ffffff',
          '--color-error': '#dd1308',
          '--color-content-primary': '#17171c',
          '--color-content-secondary': '#6a6e87'
        },
        '.Item': {
            padding: '2rem 1rem',
            border: '1px solid grey',
        },
    },
})

advancedConfiguration Object

ParameterTypeRequired?Description
hideSubmitButtonbooleancrossRenders the form without a submit button. Allows you to use submit trigger with your own custom Submit button.
additionalFieldsArray stringcrossRenders additional fields such as name, email, dob, phone, shippingAddress, billingAddress, identityDocuments

Usage Example

Worldpay.init({
    // ...other config
    advancedConfiguration: {
        hideSubmitButton: true,
        additionalFields: ['name', 'email'],
    },
})