**Last updated**: 09 October 2026 | [**Change log**](/products/components/changelog)

# Components SDK

Enterprise

Take payments and still qualify for SAQ-A - the lowest PCI compliance level - with our Components SDK.  
Accept one-time debit/credit cards and Alternative Payment Methods (APMs) using a secure, hosted iframe solution. 
Integrate the SDK into your web application, ensuring a seamless and secure payment experience for your customers.

br
Prerequisite
Contact your Worldpay Implementation Manager for your checkout id (in UUId format) and your credentials.

br
### Basic integration example

Components initialization example screenshot
br
```html
<script type="module">
  Worldpay.components.init({
    // ...other config
    elements: [
      {
        element: "accordion",
        methods: [
          { name: "card" },
          { name: "ideal" },
          { name: "paypal" },
          { name: "sepa" },
          { name: "blik" },
        ]
      }
    ]
  })
</script>
```

## Integration steps

1. **SDK initialization** - load and configure the SDK in your web application.
2. **UI rendering** - the hosted component is embedded against a chosen selector on your checkout page.
3. **Payment data collection** - collect payment details securely via the iframe.
4. **Session creation** - receive a session from the SDK.
5. **Payment submission** - send the session to your backend for payment processing.
6. **Choose the payment path**
a. **Debit/credit cards** - authorize guest payment by sending the session to the [Payments API](/products/payments/).
b. **Redirect APMs** - use our [APMs API](/products/apms/) to redirect the customer to the provider authorization page, then check the payment status.
c. **[QR code APMs](/products/components/qr-code-apms)** - display the QR code (for example Pix, WeChat Pay, Swish), then check payment status.
d. **[Recurring transactions](/products/components/optional-config#processing-recurring-payments-with-apms)** - process recurring payments for SEPA, Klarna (recurring), and iDEAL.


## Payment flows

Redirect APM flow
```mermaid

sequenceDiagram
  autonumber
  participant C as Customer
  participant S as Components SDK
  participant M as Merchant
  participant A as APMs API

  M->>S: Configure and initialize Components SDK
  C->>S: Submit payment details for the selected method
  S-->>M: Return session href
  M->>A: Submit payment request with session href
  A-->>M: Return redirect URL
  M->>C: Redirect customer to APM provider
  C->>M: Authorize payment
  M->>A: Poll transaction status
  A-->>M: Return transaction status
  M->>C: Redirect customer to the status page
```

Card flow
```mermaid

sequenceDiagram
  autonumber
  participant C as Customer
  participant S as Components SDK
  participant M as Merchant
  participant A as Payments API

  M->>S: Configure and initialize Components SDK
  C->>S: Submit payment details for the selected method
  S-->>M: Return session href
  M->>A: Submit payment request with session href
  A-->>M: Return transaction status
  M->>C: Redirect customer to the status page
```

### Integration and initialization

Add the Components SDK script to your web application:

```js
<script type="module" src="https://js.worldpay.com/1.241.0/components.js"></script>
```

Adding `type="module"` is required when loading `components.js`. The Components SDK is delivered as an ES module, so the browser must load it in module mode for `Worldpay.components` to be available.

br
### Live integration example

Access Components SDK - Integration Example
You can initialize the SDK using a simple configuration.

```js
<script type="module">
  const config = {
    id: "your-checkout-id",
    baseUrl: "https://try.access.worldpay.com",
    selector: "#payment-wrapper",
    transaction: {
      amount: 100,
      currency: "GBP",
      countryCode: "GB"
    },
    elements: [
      {
        element: "accordion",
        methods: [ 
          {
            name: "card",
            options: { 
              acceptedCardBrands: ["amex", "visa", "mastercard", "diners", "discover", "jcb", "maestro"],
             },
          }, 
          { name: "alipay_cn" }, 
          { name: "paypal" }, 
          { name: "sepa" }, 
          { name: "blik" }, 
          { name: "swish" }
        ],
      },
    ],
    advancedConfiguration: {
      additionalFields: ["email"]
    }
  }

  Worldpay.components.init(config)
</script>
```

| Parameter | Description |
|  --- | --- |
| `id` | Checkout merchant ID. |
| `baseUrl` | The URL for our try/live environment. |
| `selector` | The DOM selector where the iframe is mounted. |
| `transaction` | An object containing payment details. |
| `amount` | The transaction amount in minor units (e.g., pence for GBP). |
| `currency` | The [ISO currency code](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `countryCode` | The [ISO country code](/products/reference/supported-countries-currencies#iso-country-codes). |
| `loadingSkeleton` | Enables a loading skeleton while the iframe is initializing. |
| `elements` and `methods` | Defines the elements and payment methods. |


### User data collection

Customers enter their payment details directly into the hosted iframe. The SDK handles validation and securely transmits the information to us. We process and store the data and send you an encrypted session.

### Handling session

Once your customer has entered payment details and we have validated them, the SDK returns a session representing the payment data.

```js
<script type="module">
  Worldpay.components.init(config)
    .onSuccess((session, method) => { 
      console.log(session) // "https://try.access.worldpay.com/sessions/eyJrIjoxLCJkIjoiWnRLYmErUUNkOTRnc2NUZ3Z5..."
      console.log(method) // e.g. "paypal"
  })
</script>
```

You can apply the session according to the selected payment path:

1. **Debit/credit cards** - send the session to the [Payments API](/products/payments/).
2. **Redirect and QR code APMs** - send the session to our [APMs API](/products/apms).
3. **Recurring APMs** - send the session to our [APMs API](/products/apms) using the recurring flow for the selected method.


For API requests:

1. Set `instruction.paymentInstrument.type` to `checkout`.
2. Set `instruction.paymentInstrument.sessionHref` to the returned session.


The data you collect with the SDK is encrypted into the session, so you do not need to re-supply it. The SDK field mapping is as follows:

| additionalFields | SDK display name | API service mapping |
|  --- | --- | --- |
| `billingAddress` | Billing Address | `instruction.paymentInstrument.billingAddress` |
| `shippingAddress` | Shipping Address | `instruction.shipping` |
| `email` | Email Address | `instruction.customer.email` |
| `name` | First Name | `instruction.customer.firstName` |
| `name` | Last Name | `instruction.customer.lastName` |
| `phone` | Telephone Number | `instruction.customer.phone` |
| `dateOfBirth` | Date of Birth | `instruction.customer.dateOfBirth` |
| `identityDocuments` | CPF/CNPJ | `instruction.customer.identityDocuments.reference` |
| `identityDocuments` | CPF/CNPJ | `instruction.customer.identityDocuments.type` |


### Supported payment methods

| Payment method | Initializing request payment name |
|  --- | --- |
| Debit and credit cards1 | `card` |
| ACH/eCheck | `ach` |
| Alipay China | `alipay_cn` |
| Alipay Hong Kong | `alipay_hk` |
| Alipay+ | `alipay_uni` |
| Bancontact | `bancontact` |
| BLIK | `blik` |
| Euteller | `euteller` |
| iDEAL | `ideal` |
| Klarna (recurring) | `klarna` |
| Konbini | `konbini` |
| Multibanco | `multibanco` |
| MyBank | `mybank` |
| Open Banking | `open_banking` |
| Przelewy24 | `przelewy` |
| PayPal | `paypal` |
| PaysafeCard | `paysafecard` |
| Pix | `pix` |
| SafetyPay | `safetypay` |
| SEPA Direct Debit | `sepa` |
| Swish | `swish` |
| Trustly | `trustly` |
| WeChat Pay | `wechatpay` |


1 **Supported cards:** American Express  / Discover / Diners / ELO / JCB / Maestro / MasterCard / MasterCard Debit / Visa / Visa Debit / Visa Electron (UK only)

### ACH configuration

For ACH to load, provide options.merchantName (string). This is displayed in the ACH compliance disclaimer and must match your legal merchant name.

#### Example

```js
Worldpay.components.init({
  // ...other config
    elements: [
      {
        element: "accordion",
        methods: [ 
          {
            name: "ach",
            "options": { "merchantName": "Global Payments" } 
          }
        ],
      },
    ]
  })
```

## Security and compliance considerations

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

## Browser support

Our components work with all recent versions of major browsers

* Chrome
* Edge
* Firefox
* Safari


**Next steps**

[Optional configuration](/products/components/optional-config)