Optional configuration

Copy for LLM / MCP Connect

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Customization

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

Themes

• 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"
})
...

Elements

You can specify the desired payment methods and layout.

• Layout options:

  • accordion

  • tabs

  • solitary

Styling

You can apply custom CSS styles to the iframe for further visual customization.

Client hosted button

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

Example

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

Additional fields

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

Example

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

Field mapping (displayed to your customer)

Triggers and lifecycle hooks

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.

Example

Worldpay.components.select('paypal')

Worldpay.components.submit()

Worldpay.components.showQRCode('pix', {
    qrCode: 'iVBORw0KGgoAAAANSUhEUgAABbQAAAW0AQ...',
    ervCode: '00020101021226930014br.gov.bcb.pix2571qrcode-h.pix.celcoin.com.br/...',
})

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.

Multi-initialization

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

Handling QR code display and payment status for APMs (Pix, WeChat Pay)

Some Alternative Payment Methods (APMs), such as Pix and WeChat Pay, require your customer to complete the payment by scanning a QR code. The following outlines how to integrate this flow using the SDK:

1. Receive the QR code data: When initiating a payment with an APM that uses QR codes (e.g., Pix, WeChat Pay), the APMs API payment response will include a redirect field. This field contains the necessary data to generate and display the QR code.

2. Send the QR code to the SDK: Pass the redirect field value to the SDK using the designated method. The SDK will then render the QR code within the hosted iframe, making it visible to your customer.

3. Your customer scans the QR code: The shopper uses their mobile device to scan the QR code displayed in the iframe. The payment is then processed externally by the APM provider.

4. Monitor payment status: While your customer completes the payment, periodically check the status of the transaction using the appropriate API endpoint or webhook notification.

5. Redirect your customer upon completion: Once the payment status is confirmed as successful (or failed), redirect your customer to a final merchant-hosted page (e.g., order confirmation or error page).

Processing recurring payments with APMs

The Checkout SDK supports Alternative Payment Methods (APMs) that allow for recurring payments. This includes Klarna, 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

Security and compliance considerations

The hosted iframe ensures sensitive payment data never touches your servers. All communications between the SDK, iframe, and Worldpay are encrypted.

Browser support

Our components work with all recent versions of major browsers

• Chrome
• Edge
• Firefox
• Safari