Important
This documentation is for preview purposes only.

# Components SDK

Take 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.

Prerequisite
Contact your Implementation manager for your checkout id (in UUId format) and your credentials.

### 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. **QR code APMs** - handle QR code display and retrieve payment statuses for APMs (Pix, WeChat Pay).
7. **Recurring transactions** - process recurring payments for SEPA, Klarna and iDEAL.


### Redirect APM flow for the Components SDK


```mermaid

sequenceDiagram
    participant Customer
    participant Merchant site
    participant ComponentsSDK
    participant Session service
    participant Merchant backend
    participant APMs API
    participant External provider

    Customer->>Merchant site: Visits checkout page
    Merchant site->>ComponentsSDK: Injects SDK, invokes setup
    ComponentsSDK->>Merchant site: Renders payment form
    Customer->>ComponentsSDK: Enters payment details
    ComponentsSDK->>Session service: Calls to generate session
    Session service->>ComponentsSDK: Returns session response
    ComponentsSDK->>Merchant site: Passes session href
    Merchant site->>Merchant backend: Passes session href
    Merchant backend->>APMs API: Calls API to complete transaction
    APMs API->>Merchant backend: Returns response
    Merchant backend->>Merchant site: Passes redirect link
    Merchant site->>Customer: Initiates redirect
    Customer->>External provider: Completes payment
    External provider->>Customer: Redirects back to merchant
```

### QR code APM flow for the Components SDK


```mermaid

sequenceDiagram
    participant Customer
    participant Merchant site
    participant Components SDK
    participant Session service
    participant Merchant backend
    participant APMs API
    participant External provider

    Customer->>Merchant site: Visits checkout page
    Merchant site->>Components SDK: Injects SDK, invokes setup
    Components SDK->>Merchant site: Renders payment form
    Customer->>Components SDK: Enters payment details
    Components SDK->>Session service: Calls to generate session
    Session service->>Components SDK: Returns session response
    Components SDK->>Merchant site: Passes session href
    Merchant site->>Merchant backend: Passes session href
    Merchant backend->>APMs API: Calls API to complete transaction
    APMs API->>Merchant backend: Returns response
    Merchant backend->>Merchant site: Passes QR code
    Merchant site->>Components SDK: Passes QR code
    Components SDK->>Components SDK: Displays QR code to customer
    Customer->>External provider: Completes payment on second device or merchant app
    Merchant backend->>APMs API: Checks status of transaction
    APMs API->>Merchant backend: Returns response
    Merchant backend->>Merchant site: Returns payment status
    Merchant site->>Customer: Redirects customer to status page
```

### Integration and initialization

Add the Components SDK script to your web application:


```js
<script src="https://js.worldpay.com/1.209.0/components.js"></script>
```

br
You can initialize the SDK using a simple configuration


```js
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: "ideal"
        },
        {
          name: "paypal"
        }
      ]
    }
  ]
}

Worldpay.components.init(config)
```

| Parameter | Description |
|  --- | --- |
| `id` | The unique identifier for the transaction/session. |
| `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](/access/products/reference/supported-countries-currencies#iso-currency-codes). |
| `countryCode` | The [ISO country code](/access/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 payment details are entered and validated, the SDK returns a session representing the payment data.


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

You can then apply the session directly in our [APMs API](/access/products/apms).

1. Set `instruction.paymentInstrument.type": "checkout"`
2. Apply the session in the value for `instruction.paymentInstrument.sessionHref`


The data you can collect with the SDK is directly mapped to our APMs API. This is then passed in the encrypted session, meaning you don't need to re-supply it. The SDK maps the APMs API field as follows:

| additionalFields | SDK display name | APMs 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 |
|  --- | --- |
| ACH/eCheck | `ach` |
| Alipay China | `alipay_cn` |
| Alipay Hong Kong | `alipay_hk` |
| Alipay+ | `alipay_uni` |
| Bancontact | `bancontact` |
| Bizum | `bizum` |
| BLIK | `blik` |
| Euteller | `euteller` |
| iDEAL | `ideal` |
| Klarna | `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` |
| Trustly | `trustly` |
| WeChat Pay | `wechatpay` |


#### Example:


```js
Worldpay.components.init({
  // ...other config
  elements: [
    {
      element: "accordion",
      methods: [
        { name: "ideal" },
        { name: "paypal" },
        { name: "blik" }
      ]
    }
  ]
})
```