CheckoutWebComponents

Last updated: October 15, 2025

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. 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. 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.
`componentOptions.applepay.buttonType`	`string`	Customizes the Apple Pay wallet button type. This value must be supported by the Apple Pay JS SDK.
`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.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_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 used to pre-populate the email input field in `FlowComponent`.
`componentOptions.data.phoneCountryCode`	`string`	The phone country code used to pre-populate the phone input fields in `FlowComponent`.
`componentOptions.data.phoneNumber`	`string`	The phone number used to pre-populate the email input field in `FlowComponent`.
`componentOptions.data.shippingFirstName`	`string`	The customer's first name. Used when you collect payment details without an initial payment session.
`componentOptions.data.shippingLastName`	`string`	The customer's last name. Used when you collect payment details without an initial payment session.
`componentOptions.data.shippingPhoneCountryCode`	`string`	The shipping phone country code. Used when you collect payment details without an initial payment session.
`componentOptions.data.shippingPhoneNumber`	`string`	The shipping phone number. Used when you collect payment details without an initial payment session.
`componentOptions.data.shippingLine1`	`string`	The first line of the shipping address. Used when you collect payment details without an initial payment session.
`componentOptions.data.shippingLine2`	`string`	The second line of the shipping address. Used when you collect payment details without an initial payment session.
`componentOptions.data.shippingCity`	`string`	The shipping address city. Used when you collect payment details without an initial payment session.
`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.
`componentOptions.data.shippingZip`	`string`	The shipping address ZIP or postal code. Used when you collect payment details without an initial payment session.
`componentOptions.data.shippingCountry`	`string`	The shipping address country, as an ISO alpha-2 country code. Used when you collect payment details without an initial payment session.
`componentOptions.data.billingPhoneCountryCode`	`string`	The billing phone country code. Used when you collect payment details without an initial payment session.
`componentOptions.data.billingPhoneNumber`	`string`	The billing phone number. Used when you collect payment details without an initial payment session.
`componentOptions.data.billingLine1`	`string`	The first line of the billing address. Used when you collect payment details without an initial payment session.
`componentOptions.data.billingLine2`	`string`	The second line of the billing address. Used when you collect payment details without an initial payment session.
`componentOptions.data.billingCity`	`string`	The billing address city. Used when you collect payment details without an initial payment session.
`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.
`componentOptions.data.billingZip`	`string`	The billing address ZIP or postal code. Used when you collect payment details without an initial payment session.
`componentOptions.data.billingCountry`	`string`	The billing address country, as an ISO alpha-2 country code. Used when you collect payment details without an initial payment session.
`componentOptions.amount`	`number`	The payment amount, in the minor currency unit. Used when you collect payment details without an initial payment session. If you use Klarna, this field is required.
`componentOptions.currency`	`string`	The payment currency, as an ISO 4217 currency code. Used when you collect payment details without an initial payment session. 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. 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.
`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 should 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. 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.
`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. 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. 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.
`componentOptions.googlepay.buttonType`	`string`	Customizes the Google Pay wallet button type. This value must be accepted by the Google Pay API.
`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 should point and send requests to.
`locale`	`string`	Sets the customer's locale.
`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.


1const checkout = await CheckoutWebComponents({
2  appearance,
3  componentOptions: {
4    flow: {
5      expandFirstPaymentMethod: false,
6    },
7    card: {
8      displayCardholderName: 'bottom',
9      data: {
10        cardholderName: 'Jia Tsang',
11      },
12    },
13  },
14  environment: 'sandbox',
15  locale: 'en',
16  paymentSession,
17  publicKey: 'pk_01234',
18  translations,
19});

Initializes a FlowComponent instance.

Parameter Type Description

Parameter	Type	Description
`name`	`string`	The name of the `FlowComponent` instance. This can be one of: `alipay_cn` `alipay_hk` `alma` `applepay` `authentication` `bancontact` `benefit` `bizum` `card` `card_cvv` `dana` `eps` `gcash` `googlepay` `ideal` `kakaopay` `klarna` `knet` `mbway` `mobilepay` `multibanco` `p24` `paypal` `plaid` `qpay` `sepa` `shipping_address` `stcpay` `stored_card` `tabby` `tamara` `tng` `truemoney` `twint` `vipps`
`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.

name

string

The name of the FlowComponent instance. This can be one of:

alipay_cn
alipay_hk
alma
applepay
authentication
bancontact
benefit
bizum
card
card_cvv
dana
eps
gcash
googlepay
ideal
kakaopay
klarna
knet
mbway
mobilepay
multibanco
p24
paypal
plaid
qpay
sepa
shipping_address
stcpay
stored_card
tabby
tamara
tng
truemoney
twint
vipps

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.


1const flowComponent = checkout.create('flow', {
2  showPayButton: false,
3});

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.

Parameter Type Description

Parameter	Type	Description
`updateDetails`	`object`	An object containing the values to update.
`updateDetails.amount`	`number`	The new payment amount, in the minor currency unit. The value must be greater than zero.

updateDetails

object

An object containing the values to update.

updateDetails.amount

number

The new payment amount, in the minor currency unit.

The value must be greater than zero.


1const checkout = await CheckoutWebComponents({
2  handleSubmit: async (component, submitData) => {
3    // This callback is required to use the update method
4  }
5});
6
7await checkout.update({
8  amount: 2500
9});

CheckoutWebComponents

Initialization

Methods

create(name, options)

update(updateDetails)