Last updated: 09 October 2026 | Change log

Customize the Components SDK's appearance, render payment methods and form fields used for data collection.

• two options: "default" (light mode) and "dark"
• assets such as payment method icons adjust according to mode setting

Worldpay.components.init({
  // ...other config
  theme: "dark"
})

You can specify the desired payment methods and layout.

• Layout options:

  • accordion

  • tabs

  • solitary

The styling system gives you full control over presentation: use CSS variables for global theming, and CSS classes to target specific DOM elements for fine-grained overrides. This lets you match our embedded checkout UI with your brand design system.

Common CSS variables:

--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;

Worldpay.components.init({
  // ...other config
  styles: {
    ":root": {
      "--color-primary": "blue";
    },
    ".Item__label": {
      "font-size": "24px"
    },
    ".Item__sepa .Item__formContainer": {
      "background": "orange"
    }
  }
})

You can disable the SDK-hosted button and use triggers and lifecycle hooks to understand your customer's actions.

Worldpay.components.init({
  // ...other config
  advancedConfiguration: {
    hideSubmitButton: true
  }
})

You can specify what information the SDK should collect from your customer. The SDK only displays the applicable fields for the selected APM, based on both your request and the APM's requirements

Worldpay.components.init({
  // ...other config
  advancedConfiguration: {
    additionalFields: [
      "name",
      "email",
      "phone",
      "shippingAddress",
      "billingAddress",
      "accountHolderName",
      "dateOfBirth",
      "identityDocuments"
    ]
  }
})

You can 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.

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 enable you to respond to various stages of the payment UI, attach custom interactivity, and handle events such as loading, selection, success, or errors.

You can initialize and embed the SDK multiple times on the same webpage.

Two optional configurations are available on the card element via options property:

• acceptedCardBrands: controls which card brand logos display during initialization.

• allowNonLuhnCompliantCards: allows acceptance of valid card brands that do not pass Luhn checks.

The Components SDK supports Alternative Payment Methods (APMs) that allow for recurring payments. This includes Klarna (recurring), iDEAL, and SEPA. The following steps outline how to use the SDK for both initial and subsequent recurring payment transactions:

1. Initial payment data collection: Use the SDK to collect your customer's payment details and initiate the first transaction as you would for a standard payment. The SDK will securely capture all required data for the APM.
2. Storing recurring payment data: After the initial transaction is processed, Worldpay generates and stores the necessary information (such as payment tokens or mandates) required for future use.
3. Retrieving data for subsequent payments: For any subsequent payment, you don't need to collect your customer's payment details again. Instead, retrieve the mandatory data for the recurring payment from our Events service.
   • use the Events API to listen for the token.created event
   • the event payload contains the payment token or other details that you can use to process future payments without further customer interaction
4. Processing subsequent payments: Use the retrieved data to initiate subsequent payments through our APMs API. You only use the SDK for the initial collection of payment details.