FlowComponent

Last updated: October 15, 2025

Submits a FlowComponent, if you require your own pay button.

Information

This option is not available for digital wallets, including Apple Pay and Google Pay.


1function submit() {
2  return FlowComponent;
3}

This method must be used with your own pay button. It submits a FlowComponent element with card or card verification value (CVV) tokenization. This method only works with card payments.

Returns a JavaScript Promise that resolves with the TokenizeResult object, which includes the following fields:

type – The name of the payment method that initiated the tokenization – Only card is supported.
data – The Card Tokenization response
cardMetadata – An optional Card Metadata lookup response object included when a Card Metadata API response is received during customer input


1const cardComponent = checkout.create('card');
2
3if (await cardComponent.isAvailable()) {
4  cardComponent.mount('#card-container');
5}
6
7const cardPayButton = document.getElementbyId('card-pay-button');
8
9cardPayButton.addEventListener('click', async () => {
10  const { data } = await cardComponent.tokenize();
11
12  await utilizeToken(data.token);
13});+

Returns a JavaScript Promise that resolves with the CardCvvTokenizeResult object, which includes the following fields:

type – The name of the payment method that initiated the tokenization – Only card_cvv is supported.
data – The Card CVV Tokenization response


1const storedCardPayButton = document.getElementbyId('stored-card-pay-button');
2
3storedCardPayButton.addEventListener('click', async () => {
4  const { data } = await cardCvvComponent.tokenize();
5
6  await utilizeToken(data.token);
7});

Checks if the FlowComponent has captured all details from the customer and can be submitted.


1function isValid() {
2  return boolean;
3}

Checks if the FlowComponent can be rendered. Call this before mounting the FlowComponent.


1function isAvailable() {
2  return Promise<boolean>;
3}

Cancels the selection of the currently selected payment method in the FlowComponent instance.

The unselect() method only works with the flow component. Calling unselect() when no payment method is selected has no effect.

Additionally, after calling unselect(), subsequent calls to submit() or tokenize() also have no effect, because no payment method is active.


1const flowComponent = checkout.create('flow');
2
3flowComponent.mount('#flow-container');
4
5flowComponent.unselect();

Mounts a FlowComponent to a page. You can provide one of the following:

A DOM Element Object
An Element Selector

Parameter	Type	Description
`#elem`	`object`	The Element Selector or DOM Element object you want to mount to.


1function mount('#element') {
2  return FlowComponent;
3}

Unmounts a FlowComponent from the page.

This stops rendering the component, and removes all life-cycles from the browser.


1function unmount() {
2  return FlowComponent;
3}

Raised when a FlowComponent is initialized and ready for the customer to interact.


1const flowComponent = checkout.create('flow', {
2  onReady: (_self) => {
3    // Hide loading overlay
4    hideLoadingOverlay();
5  },
6});
7flowComponent.mount('#flow-container');

Raised when a FlowComponent changes after a customer interaction.


1const flowComponent = checkout.create('flow', {
2  onChange: (_self) => {
3    // Enable/disable custom pay button based on input validity
4    if (self.isValid()) {
5      submitButton.removeAttribute('disabled');
6    } else {
7      submitButton.setAttribute('disabled', true);
8    }
9  },
10});
11flowComponent.mount('#flow-container');

Raised when you or the customer initiates a FlowComponent submission.


1const flowComponent = checkout.create('flow', {
2  onSubmit: (_self) => {
3    // Show loading overlay to prevent further user interaction
4    showLoadingOverlay();
5  },
6});
7flowComponent.mount('#flow-container');

Raised when the payment is completed synchronously.

This event is not raised if the payment requires asynchronous action. For example, 3DS authentication.

The PaymentResponse object contains information on the successful payment:

id – A unique identifier for the payment
status – The payment status – This always returns Approved.
type – The name of the payment method used for the payment


1const flowComponent = checkout.create('flow', {
2  onPaymentCompleted: async (_self, paymentResponse) => {
3    // Complete order in server side
4    await completeOrder(paymentResponse.id);
5  },
6});
7flowComponent.mount('#flow-container');

Raised when an error occurs. For more information, see the CheckoutError reference.


1const flowComponent = checkout.create('flow', {
2  onError: async (_self, error) => {
3    // Display payment request failure message
4    if (error.code === 'payment_request_failed') {
5      showErrorMessage('Payment could not be processed. Please try again.');
6    }
7  },
8});
9flowComponent.mount('#flow-container');

Raised when the customer inputs or changes the first eight digits of a card.

You can use this event to perform checks on a card based on its metadata or to observe changes to the BIN.

The CardMetadataResponse object contains the Card Metadata lookup response.

Flow accepts the card if the callback you provide does not return a response. Additionally, depending on your preferred action, you can provide the corresponding object:

Accept the card – return .accepted
Reject the card – return .reject(message: "Error message")

If you reject the card, you can display a custom error message using the optional errorMessage object.


1const flowComponent = checkout.create('flow', {
2  onCardBinChanged: (_self, cardMetadata) => {
3    if (card_metadata.card_type === 'credit') {
4      return {
5        continue: false,
6        errorMessage: 'Credit cards are not accepted.',
7      };
8    }
9    return { continue: true };
10  }
11});
12
13flowComponent.mount('#flow-container');

Raised when the cardholder details provided by the customer are tokenized.

You can use this event to perform checks on a card based on its tokenization result and metadata.

The TokenizeResult object contains the following information:

type – The name of the payment method that triggered the tokenization – Only card is supported.
data – The Card Tokenization response
cardMetadata – An optional Card Metadata lookup response object included when a Card Metadata API response is received during customer input

Flow accepts the card if the callback you provide does not return a response. Additionally, depending on your preferred action, you can provide the corresponding object:

Accept the card: { continue: true }
Reject the card: { continue: false, errorMessage: "Message" }

If you choose to reject the card, you can display a custom error message using the optional errorMessage object.


1const flowComponent = checkout.create('flow', {
2  onTokenized: (_self, tokenizeResult) => {
3    if (tokenizeResult.data.card_type === 'CREDIT') {
4      return {
5        continue: false,
6        errorMessage: 'Credit cards are not accepted.',
7      };
8    }
9    return { continue: true };
10  }
11});
12
13flowComponent.mount('#flow-container');

When the customer initiates an Apple Pay or Google Pay payment submission, the onAuthorized(FlowComponent) event is raised.

You can use the returned object to inspect the payment details they provided and decide whether to continue with the payment. For example, if you do not want to accept American Express or credit card payments.

Depending on the payment method, AuthorizeResult contains different payloads:

For Apple Pay payments – It contains the payload from the onpaymentauthorized event provided by the Apple Pay Javascript SDK.
For Google Pay payments – It contains the payload from the loadPaymentData response provided by the Google Pay API.

Information

onAuthorize events raised by Google Pay payments do not return an AuthorizeResult object.

Flow accepts the card if the callback you provide does not return a response. Additionally, depending on your preferred action, you can provide the corresponding object:

Accept the card – { continue: true }
Reject the card – { continue: false, errorMessage: "Message" }

If you choose to reject the card, you can display a custom error message using the optional errorMessage object.


1const applepayComponent = checkout.create('applepay', {
2  onAuthorized: (_self, authorizeResult) => {
3    if (authorizeResult?.payment?.token?.paymentMethod?.type === 'credit') {
4      return {
5        continue: false,
6        errorMessage: 'Credit cards are not accepted.',
7      };
8    }
9
10    return { continue: true };
11
12  },
13});
14
15if (await applepayComponent.isAvailable()) {
16  applepayComponent.mount('#applepay-container');
17}

Raised when a wallet payment button is clicked. For example, Apple Pay, Google Pay, or PayPal.

You can use this to perform checks before beginning the payment process.

FlowComponent is the instance that initiated the callback.


1const flowComponent = checkout.create('flow', {
2  handleClick: (_self) => {
3    if (acceptedTermsAndConditions) {
4      return { continue: true };
5    }
6    return { continue: false };
7  },
8});
9flowComponent.mount('#flow-container');

Raised when you or the customer submit a FlowComponent element.

You can use this callback to submit a customized payment, by calling the Submit a Payment Session Payment endpoint.

The SubmitData object contains session_data. This is a unique token representing the additional customer data that Flow captured. You must provide this token when you submit the customized payment session request.

You must provide the unmodified response body returned by the endpoint.

Raised when a payment method is rendered in the Flow component. This callback is raised for each payment method rendered.

You can use this callback to render additional content in the provided containerElement reference. For example, your Terms & Conditions message. The additional content appears after the Pay or wallet payment button.

You can provide a unique identifier string for each payment method, which is included as mountIdentifier in the handlePaymentAdditionalContentUnmount callback when the Flow component is unmounted.


1let isCheckboxAccepted = false;
2
3const handlePaymentAdditionalContentMount = (_self, containerElement) => {
4  const identifier = `${component.type}-tnc`;
5
6  const checkbox = document.createElement('input');
7  checkbox.type = 'checkbox';
8  checkbox.name = identifier
9  checkbox.addEventListener('click', () => {
10    isCheckboxAccepted = checkbox.checked;
11  });
12
13  const label = document.createElement('label');
14  label.innerHTML = 'By clicking the pay button, you authorize us to use your payment details to process the payment';
15
16  element.appendChild(checkbox);
17  element.appendChild(label);
18
19  return identifier;
20};
21
22const handleClick = (_selef) => {
23  if (isCheckboxAccepted) {
24    return { continue: true };
25  }
26  return { continue: false };
27};
28
29const checkout = await new CheckoutWebComponents({
30  paymentSession,
31  publicKey,
32  componentOptions: {
33    flow: {
34      handleClick,
35      handlePaymentAdditionalContentMount,
36    },
37  },
38});
39
40const flowComponent = checkout.create('flow');
41flowComponent.mount('#flow-container');

Raised when a payment method is unmounted from the Flow component.

You can use this callback to clean up the rendered content, as well as any logic applied to your page. If you provide a unique identifier to the handlePaymentAdditionalContentMount callback during rendering, it is returned as mountIdentifier for your reference.


1const handlePaymentAdditionalContentMount = (component, containerElement) => {
2  // Render the Terms and Conditions content to `containerElement` reference.
3};
4
5const handlePaymentAdditionalContentUnmount = (component, containerElement, mountIdentifier) => {
6  containerElement.innerHTML = '';
7    // Clean up the Terms and Conditions content.
8};
9
10const checkout = await new CheckoutWebComponents({
11  paymentSession,
12  publicKey,
13  componentOptions: {
14    flow: {
15      handlePaymentAdditionalContentMount,
16      handlePaymentAdditionalContentUnmount,
17    },
18  },
19});
20
21const flowComponent = checkout.create('flow');
22flowComponent.mount('#flow-container');

FlowComponent

Methods

submit()

Information

tokenize(): Promise(TokenizeResult)

isValid()

isAvailable()

unselect()

mount('#element')

unmount()

Events

onReady(FlowComponent)

onChange(FlowComponent)

onSubmit(FlowComponent)

onPaymentCompleted(FlowComponent, PaymentResponse)

onError(FlowComponent, CheckoutError)

onCardBinChanged(FlowComponent, CardMetadataResponse)

onTokenized(FlowComponent, TokenizeResult)

onAuthorized(FlowComponent, AuthorizeResult)

Information

Callbacks

handleClick(FlowComponent)

handleSubmit(FlowComponent, SubmitData)

handlePaymentAdditionalContentMount(FlowComponent, containerElement)

handlePaymentAdditionalContentUnmount(FlowComponent, containerElement, mountIdentifier)