# CheckoutWebComponents
## Initialization
Initializes a `CheckoutWebComponent` instance.
| Parameter | Type | Description |
| --- | --- | --- |
| `appearance` | `object` | Customizes the visual appearance of the `CheckoutWebComponent` elements. |
| `componentOptions` | `object` | Customizes the options for the individual Flow components. |
| `componentOptions.applepay.acceptedCardSchemes` | `array` | The list of accepted card schemes in Apple Pay payments.
This value can be one of:
- `american_express`
- `cartes_bancaires`
- `china_union_pay`
- `discover`
- `jcb`
- `mada`
- `mastercard`
- `visa`
The values in this list are mapped into values supported by the [Apple Pay JS SDK](https://developer.apple.com/documentation/applepayontheweb/applepaypaymentrequest/supportednetworks).
This list overrides `componentOptions.flow.acceptedCardSchemes`. |
| `componentOptions.applepay.acceptedCardTypes` | `array` | The list of accepted card types in Apple Pay payments.
This value can be one of:
- `credit`
- `debit`
The values in this list are mapped into values supported by the [Apple Pay JS SDK](https://developer.apple.com/documentation/applepayontheweb/applepaymerchantcapability).
This list overrides `componentOptions.flow.acceptedCardTypes`. |
| `componentOptions.applepay.buttonColor` | `string` | Customizes the Apple Pay wallet button appearance.
This value must be supported by the [Apple Pay JS SDK](https://developer.apple.com/documentation/applepayontheweb/applepaybuttonstyle). |
| `componentOptions.applepay.buttonType` | `string` | Customizes the Apple Pay wallet button type.
This value must be supported by the [Apple Pay JS SDK](https://developer.apple.com/documentation/applepayontheweb/applepaybuttontype). |
| `componentOptions.captureBillingAddress` | `boolean` | Instructs the wallet whether to collect the customer's billing address during authorization.
Supported for
- `applepay`
- `googlepay`
Default value: `false`
To collect a billing address with the card component, use `componentOptions.card.capturedBillingAddressFields` and `componentOptions.card.requiredBillingAddressFields`. |
| `componentOptions.card.acceptedCardSchemes` | `array` | The list of accepted card schemes for card payments.
This value can be one of:
- `american_express`
- `cartes_bancaires`
- `china_union_pay`
- `diners_club_international`
- `discover`
- `jcb`
- `mada`
- `mastercard`
- `visa`
This list overrides `componentOptions.flow.acceptedCardSchemes`. |
| `componentOptions.card.acceptedCardTypes` | `array` | The list of accepted card types for card payments.
This value can be one of:
- `charge`
- `credit`
- `debit`
- `deferred_debit`
- `prepaid`
This list overrides `componentOptions.flow.acceptedCardTypes`. |
| `componentOptions.card.capturedBillingAddressFields` | `array` | The billing address fields the card component collects from the customer. Include `country` and `zip` to display a compact form, or include the full set of address fields to display the full address form.
For example configurations, see [Collect a billing address with the card component](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-flow-integration.md#Collect_a_billing_address_with_the_card_component).
To set which of these fields the customer must complete, use `componentOptions.card.requiredBillingAddressFields`. |
| `componentOptions.card.data.cardholderName` | `string` | The name to pre-populate the cardholder name input field for card payments. |
| `componentOptions.card.displayCardholderName` | `string` | The position of the cardholder name input field for card payments.
- `top` – The field is positioned above all other fields.
- `bottom` – The field is positioned below all other fields.
- `hidden` – The field is not displayed. |
| `componentOptions.card.displayCvv` | `string` | The visibility of the CVV input field for card payments.
- `mandatory` – The field is displayed and required.
- `hidden` – The field is not displayed. |
| `componentOptions.card.requiredBillingAddressFields` | `array` | The billing address fields the customer must complete in the card component. Each field must also be in `componentOptions.card.capturedBillingAddressFields`. Fields you capture but omit here are optional. |
| `componentOptions.card_cvv.cardCvvLength` | `number` | The required length of the card CVV. This value can be either `3` or `4`. |
| `componentOptions.data.email` | `string` | The email address to pre-populate the email input field for Remember Me in `FlowComponent`. This field doesn't affect the payment session's `customer.email` field. |
| `componentOptions.data.phoneCountryCode` | `string` | The [phone country code](https://www.checkout.com/docs/developer-resources/codes/country-codes.md) to pre-populate the phone input fields for Remember Me in `FlowComponent`. This field doesn't affect the payment session's `customer.phone.country_code` field. |
| `componentOptions.data.phoneNumber` | `string` | The phone number to pre-populate the phone input field for Remember Me in `FlowComponent`. This field doesn't affect the payment session's `customer.phone.number` field. |
| `componentOptions.data.shippingFirstName` | `string` | The customer's first name.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.shippingLastName` | `string` | The customer's last name.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.shippingPhoneCountryCode` | `string` | The shipping phone [country code](https://www.checkout.com/docs/developer-resources/codes/country-codes.md).
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.shippingPhoneNumber` | `string` | The shipping phone number.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.shippingLine1` | `string` | The first line of the shipping address.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.shippingLine2` | `string` | The second line of the shipping address.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.shippingCity` | `string` | The shipping address city.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.shippingState` | `string` | The shipping address state or province, as an ISO 3166-2 code. For example, `CA` for California, United States.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.shippingZip` | `string` | The shipping address ZIP or postal code.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.shippingCountry` | `string` | The shipping address country, as an [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes.md).
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.billingPhoneCountryCode` | `string` | The billing phone [country code](https://www.checkout.com/docs/developer-resources/codes/country-codes.md).
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.billingPhoneNumber` | `string` | The billing phone number.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.billingLine1` | `string` | The first line of the billing address.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.billingLine2` | `string` | The second line of the billing address.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.billingCity` | `string` | The billing address city.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.billingState` | `string` | The billing address state or province, as an ISO 3166-2 code. For example, `CA` for California, United States.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.billingZip` | `string` | The billing address ZIP or postal code.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.data.billingCountry` | `string` | The billing address country, as an [ISO alpha-2 country code](https://www.checkout.com/docs/developer-resources/testing/codes/country-codes.md).
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). |
| `componentOptions.amount` | `number` | The payment amount, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md).
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). If you use Klarna, this field is required. |
| `componentOptions.currency` | `string` | The payment currency, as an ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md).
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). If you use Klarna, this field is required. |
| `componentOptions.items` | `array` | The list of items.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). If you use Klarna, this field is required. |
| `componentOptions.items[n].name` | `string` | The descriptive name of the line item. |
| `componentOptions.items[n].quantity` | `number` | The number of line items. |
| `componentOptions.items[n].unitPrice` | `number` | The unit price of the item, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md). |
| `componentOptions.items[n].reference` | `string` | The item reference or product stock keeping unit (SKU). |
| `componentOptions.items[n].commodityCode` | `string` | A code identifying a commodity for value-added tax (VAT) purposes |
| `componentOptions.items[n].unitOfMeasure` | `string` | The unit in which the item is measured, as a Unit of Measure (UoM) code. |
| `componentOptions.items[n].totalAmount` | `number` | The total cost of the line item, in minor currency units.
The value must include any tax and discounts applied, using the formula: `value = (quantity x unit_price) - discount_amount`. |
| `componentOptions.items[n].discountAmount` | `number` | The discount applied to each invoice line item. |
| `componentOptions.items[n].url` | `string` | Link to the line item's product page. |
| `componentOptions.items[n].imageUrl` | `string` | Link to the line item's product image. |
| `componentOptions.processingChannelId` | `array` | The processing channel ID to process the payment with.
Used when you [collect payment details without an initial payment session](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/extend-your-flow-integration/collect-payment-details-without-an-initial-payment-session.md). If you have multiple entities, this field is required. |
| `componentOptions.flow.acceptedCardSchemes` | `array` | The list of card schemes accepted by Flow.
This value can be one of:
- `american_express`
- `cartes_bancaires`
- `china_union_pay`
- `diners_club_international`
- `discover`
- `jcb`
- `mada`
- `mastercard`
- `visa`
This list applies to the following payment methods:
- `applepay`
- `card`
- `googlepay`
- `rememberMe`
This value can be overridden by payment method-specific lists.
For example, the list `componentOptions.card.acceptedCardSchemes` overrides this list. |
| `componentOptions.flow.acceptedCardTypes` | `array` | The list of accepted card types by Flow.
This value can be one of:
- `charge`
- `credit`
- `debit`
- `deferred_debit`
- `prepaid`
This list applies to the following payment methods:
- `applepay`
- `card`
- `googlepay`
This value can be overridden by payment method-specific lists.
For example, the list `componentOptions.card.acceptedCardSchemes` overrides this list. |
| `componentOptions.flow.captureCardCvv` | `boolean` | Specifies whether to capture the card CVV when using a stored card for payment. Card CVV will always be captured for stored Mada cards. This value applies to the `remember_me` and `stored_card` payment methods, and can be overridden by the payment method-specific values. |
| `componentOptions.flow.expandFirstPaymentMethod` | `bool` | If there are multiple payment methods, sets whether to automatically expand the first payment method. |
| `componentOptions.flow.showPayButton` | `bool` | Specifies whether to display the payment button in the user interface (UI).
If you want to handle payment button rendering and interactions outside of Flow, set this to `false`.
This option configures Flow globally. To override this for a specific payment method, set this in the component's `options` when you call the `create()` [method](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference/checkoutwebcomponents.md#create(name,_options)). |
| `componentOptions.googlepay.acceptedCardSchemes` | `array` | The list of accepted card schemes for Google Pay payments.
This value can be one of:
- `american_express`
- `discover`
- `jcb`
- `mastercard`
- `Visa`
The values in this list are mapped into values supported by the [Google Pay API](https://developers.google.com/pay/api/web/reference/request-objects#CardParameters).
This list overrides `componentOptions.flow.acceptedCardSchemes`. |
| `componentOptions.googlepay.acceptedCardTypes` | `array` | The list of accepted card types for Google Pay.
This value can be one of:
- `credit`
- `debit`
- `prepaid`
The values in this list are mapped into values supported by the [Google Pay API](https://developers.google.com/pay/api/web/reference/request-objects#CardParameters).
This list overrides `componentOptions.flow.acceptedCardTypes`. |
| `componentOptions.googlepay.buttonColor` | `string` | Customizes the type of Google Pay wallet button.
This value must be accepted by the [Google Pay API](https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions). |
| `componentOptions.googlepay.buttonType` | `string` | Customizes the Google Pay wallet button type. This value must be accepted by the [Google Pay API](https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions). |
| `componentOptions.remember_me.acceptedCardSchemes` | `array` | The list of accepted card schemes in payments with Remember Me enabled.
This value can be one of:
- `american_express`
- `cartes_bancaires`
- `china_union_pay`
- `diners_club_international`
- `discover`
- `jcb`
- `mada`
- `mastercard`
- `visa`
This list overrides `componentOptions.flow.acceptedCardSchemes`. |
| `componentOptions.remember_me.captureCardCvv` | `boolean` | Specifies whether to capture the card CVV when using a stored card for payment. Card CVV will always be captured for stored Mada cards. This value overrides `componentOptions.flow.captureCardCvv` |
| `componentOptions.stored_card.acceptedCardSchemes` | `array` | The list of accepted card schemes in stored card payments.
This value can be one of:
- `american_express`
- `cartes_bancaires`
- `china_union_pay`
- `diners_club_international`
- `discover`
- `jcb`
- `mada`
- `mastercard`
- `visa`
This list overrides `componentOptions.flow.acceptedCardSchemes`. |
| `componentOptions.stored_card.acceptedCardTypes` | `array` | The list of accepted card types in stored card payments.
This value can be one of:
- `charge`
- `credit`
- `debit`
- `deferred_debit`
- `prepaid`
This list overrides `componentOptions.flow.acceptedCardTypes`. |
| `componentOptions.stored_card.captureCardCvv` | `boolean` | Specifies whether to capture the card CVV when using a stored card for payment. Card CVV will always be captured for stored Mada cards. This value overrides `componentOptions.flow.captureCardCvv` |
| `environment` | `string` | Sets the environment that the library sends requests to. |
| `locale` | `string` | Sets the customer's locale. |
| `nonce` | `string` | A Content Security Policy (CSP) nonce for the library's runtime styles.
Provide this field only if your page enforces a nonce-based `style-src` CSP without `unsafe-inline`. Otherwise, Flow's styles are blocked and Flow renders without any styling.
The value must match the `nonce` value in your page's `Content-Security-Policy` response header, and be unique for each response. Call `CheckoutWebComponents()` as early as possible, so the library doesn't create a style element before you apply the nonce.
You still need `unsafe-inline` for `style-src-attr`, because Checkout.com sets a `style` attribute on the iframes it creates. A nonce doesn't cover attribute styling. |
| `paymentSession` | `object` | The response from the `PaymentSession`. |
| `publicKey` | `string` | Your public API key. |
| `translations` | `object` | Customizes text translations for natively supported languages, or adds custom text for locales and languages that are not natively supported. |
```javascript
const checkout = await CheckoutWebComponents({
appearance,
componentOptions: {
flow: {
expandFirstPaymentMethod: false,
},
card: {
displayCardholderName: 'bottom',
data: {
cardholderName: 'Jia Tsang',
},
},
},
environment: 'sandbox',
locale: 'en',
nonce: 'the-nonce-from-your-csp-header',
paymentSession,
publicKey: 'pk_01234',
translations,
});
```
---
## Methods
### create(name, options)
Initializes a `FlowComponent` instance.
| Parameter | Type | Description |
| --- | --- | --- |
| `name` | `string` | The name of the `FlowComponent` instance. This can be one of:
- `alipay_cn`
- `alipay_hk`
- `alma`
- `applepay`
- `authentication`
- `bacs`
- `bancontact`
- `benefit`
- `bizum`
- `card`
- `card_cvv`
- `dana`
- `eps`
- `flow`
- `gcash`
- `googlepay`
- `ideal`
- `kakaopay`
- `klarna`
- `knet`
- `mbway`
- `mobilepay`
- `multibanco`
- `octopus`
- `p24`
- `paynow`
- `paypal`
- `plaid`
- `qpay`
- `sepa`
- `shipping_address`
- `stcpay`
- `stored_card`
- `swish`
- `tabby`
- `tamara`
- `tng`
- `truemoney`
- `twint`
- `vipps`
- `wechatpay` |
| `options` | `object` | The event callbacks for the `FlowComponent`. |
| `options.showPayButton` | `bool` | Specifies whether to display the payment button in the UI.
If you want to handle payment button rendering and interactions outside of Flow, set this to `false`.
This overrides the global `componentOptions.flow.showPayButton` option you specify in the `CheckoutWebComponent` [initialization](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference/checkoutwebcomponents.md#Initialization). |
```javascript
const flowComponent = checkout.create('flow', {
showPayButton: false,
});
```
### update(updateDetails)
Updates a `FlowComponent` instance.
Changes you apply using this method only affect the client-side Flow integration.
To update the server-side payment session with the changes you've made, use the `handleSubmit` [callback](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference/flowcomponent.md#handleSubmit(FlowComponent,_SubmitData)).
| Parameter | Type | Description |
| --- | --- | --- |
| `updateDetails` | `object` | An object containing the values to update. |
| `updateDetails.amount` | `number` | The new payment amount, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md).
The value must be greater than zero. |
| `updateDetails.currency` | `string` | The new payment currency, as a three-letter [ISO 4217 code](https://www.iso.org/iso-4217-currency-codes.html). |
```javascript
const checkout = await CheckoutWebComponents({
handleSubmit: async (component, submitData) => {
// This callback is required to use the update method
}
});
await checkout.update({
amount: 2500,
currency: 'USD'
});
```