Important
This documentation is for preview purposes only.

# SDK reference

## Namespaces and core methods

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

| Parameter | Type | Description |
|  --- | --- | --- |
| `Worldpay` | Object | Global namespace attached to the window object. |
| `components` | Object | Components product namespace. |
| `init` | Function | Initialization method accepting a `config` object. |


#### Usage example


```js
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.

| Parameter | Type | Description |
|  --- | --- | --- |
| `select` | Function | Selects a payment method using a `method` parameter. |
| `submit` | Function | Submits the payment form programmatically. |
| `showQRCode` | Function | Accepts `method` and QR code `data` (generated via a server-side call to the APM service) and displays it in the UI. **Note:** Only applicable for QR code-specific payment methods. |
| `resetProcessing` | Function | Resets the SDK's processing state (clears the overlay, and re-enables interactivity). |


#### Usage example


```js
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

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.

| Parameter | Type | Description |
|  --- | --- | --- |
| `onLoad` | Function | Called when the payment UI is loaded. |
| `onSelect` | Function | Called when a payment method is selected (with `method` and `selector` parameters). |
| `onSuccess` | Function | Called when the form is successfully submitted (with `session` and `method` parameters). |
| `onError` | Function | Called when a submission fails (with `error`, `method`, `selector` parameters). |


#### Usage example


```js
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.

| Parameter | Type | Required? | Description |
|  --- | --- | --- | --- |
| `id` | string | ![tick](/access/assets/check-green.5380696a3edf2560a9dfe5b5950684df132f75ed1806f53e162cd51b03cf0073.92a19ef5.svg) | Checkout merchant ID. |
| `baseUrl`. | string | ![tick](/access/assets/check-green.5380696a3edf2560a9dfe5b5950684df132f75ed1806f53e162cd51b03cf0073.92a19ef5.svg) | The URL to our try/live environment. |
| `selector` | string | ![tick](/access/assets/check-green.5380696a3edf2560a9dfe5b5950684df132f75ed1806f53e162cd51b03cf0073.92a19ef5.svg) | DOM selector for payment UI container. |
| `transaction` | Object | ![tick](/access/assets/check-green.5380696a3edf2560a9dfe5b5950684df132f75ed1806f53e162cd51b03cf0073.92a19ef5.svg) | Transaction details. |
| `theme` | string | ![cross](/access/assets/cross-red.d13e13301f04da36fc295c93f753fe887942259da230fdd6c0b06ace25541d2b.92a19ef5.svg) | Theme: `default` or `dark`. |
| `styles` | Object | ![cross](/access/assets/cross-red.d13e13301f04da36fc295c93f753fe887942259da230fdd6c0b06ace25541d2b.92a19ef5.svg) | Custom styling configuration. |
| `elements` | Array Object | ![cross](/access/assets/cross-red.d13e13301f04da36fc295c93f753fe887942259da230fdd6c0b06ace25541d2b.92a19ef5.svg) | Controls rendering of payment elements. |
| `advancedConfiguration` | Object | ![cross](/access/assets/cross-red.d13e13301f04da36fc295c93f753fe887942259da230fdd6c0b06ace25541d2b.92a19ef5.svg) | Advanced options. |
| `loadingSkeleton` | boolean | ![cross](/access/assets/cross-red.d13e13301f04da36fc295c93f753fe887942259da230fdd6c0b06ace25541d2b.92a19ef5.svg) | Enables loading animation. |


#### Usage example:


```js
const config = {
  id: "your-checkout-id",
  baseUrl: "https://try.access.worldpay.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

| Parameter | Type | Required? | Description |
|  --- | --- | --- | --- |
| `element` | string | ![tick](/access/assets/check-green.5380696a3edf2560a9dfe5b5950684df132f75ed1806f53e162cd51b03cf0073.92a19ef5.svg) | Specifies the element type for this UI section. Supported values: `accordion`, `tabs`, or `solitary`. |
| `methods` | Array Object | ![tick](/access/assets/check-green.5380696a3edf2560a9dfe5b5950684df132f75ed1806f53e162cd51b03cf0073.92a19ef5.svg) | List of payment methods for this element. Each object should specify a supported method key. |


#### Usage example


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

#### `transaction` Object

| Parameter | Type | Required? | Description |
|  --- | --- | --- | --- |
| `amount` | number | ![tick](/access/assets/check-green.5380696a3edf2560a9dfe5b5950684df132f75ed1806f53e162cd51b03cf0073.92a19ef5.svg) | Transaction amount. |
| `currency` | string | ![tick](/access/assets/check-green.5380696a3edf2560a9dfe5b5950684df132f75ed1806f53e162cd51b03cf0073.92a19ef5.svg) | ISO 4217 currency code (e.g., "USD", "EUR"). |
| `countryCode` | string | ![tick](/access/assets/check-green.5380696a3edf2560a9dfe5b5950684df132f75ed1806f53e162cd51b03cf0073.92a19ef5.svg) | ISO 3166 country code (e.g., "US", "GB"). |


#### Usage example


```js
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.

| Parameter | Type | Required? | Description |
|  --- | --- | --- | --- |
| `:root` | Object | ![cross](/access/assets/cross-red.d13e13301f04da36fc295c93f753fe887942259da230fdd6c0b06ace25541d2b.92a19ef5.svg) | CSS variables for theming and global styles. |
| `Any selector` | Object | ![cross](/access/assets/cross-red.d13e13301f04da36fc295c93f753fe887942259da230fdd6c0b06ace25541d2b.92a19ef5.svg) | Any valid CSS selector supported. |


#### Usage example


```js
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

| Parameter | Type | Required? | Description |
|  --- | --- | --- | --- |
| `hideSubmitButton` | boolean | ![cross](/access/assets/cross-red.d13e13301f04da36fc295c93f753fe887942259da230fdd6c0b06ace25541d2b.92a19ef5.svg) | Renders the form without a submit button. Allows you to use submit trigger with your own custom Submit button. |
| `additionalFields` | Array string | ![cross](/access/assets/cross-red.d13e13301f04da36fc295c93f753fe887942259da230fdd6c0b06ace25541d2b.92a19ef5.svg) | Renders additional fields such as `name`, `email`, `dob`, `phone`, `shippingAddress`, `billingAddress`, `identityDocuments` |


#### Usage Example


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