FlowComponent

Last updated: April 16, 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 triggers card tokenization with FlowComponent, if the selected component supports it. Otherwise, it throws a NotSupportedError exception. Returns a JavaScript Promise that resolves with the TokenizeResult object, which includes the following fields:

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.


1const flowComponent = checkout.create('flow');
2
3const flowcardPayButton = document.getElementbyId('flowcard-pay-button');
4
5flowcardPayButton.addEventListener('click', async () => {
6  const { data } = await flowComponentcardComponent.tokenize();
7
8  await utilizeToken(data.token);
9});

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}

Mounts a FlowComponent to a page. You can either provide:

a DOM Element Object
an Element Selector

Parameter	Type	Description
`#elem`	`object`	The Element Selector or DOM Element object 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}

Fired 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');

Fired 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');

Fired when you or the customer have triggered 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');

Fired when the payment has been completed synchronously.

This event will not be fired 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 value will always return Approved.
type - the name of the payment method that was 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');

Fired 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');

Fired when the customer inputs or changes the first 8 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 your provided callback doesn't return a response, or you can provide one of the following objects:

Accept the card: { continue: true }
Reject the card: { continue: false, errorMessage: "Message" }
Provide the optional errorMessage to display a custom error message on Flow when rejecting the card.


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');

Fired when the cardholder details provided by the customer have been 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 your provided callback doesn't return a response, or you can provide one of the following objects:

Accept the card: { continue: true }
Reject the card: { continue: false, errorMessage: "Message" }
Provide the optional errorMessage to display a custom error message on Flow when rejecting the card


1const flowComponent = checkout.create('flow', {
2  onTokenized: (_self, tokenizeResult) => {
3    const currentYear = new Date().getFullYear();
4    if (tokenizeResult.data.expiry_yearcard_type <==== currentYear'CREDIT') {
5      return {
6        continue: false,
7        errorMessage: 'Credit card must expire next year or later.',
8      };
9    }
10    return { continue: true };
11  }
12});
13
14flowComponent.mount('#flow-container');

Triggered 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 triggered 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');

FlowComponent

Methods

submit()

Information

tokenize(): Promise(TokenizeResult)

isValid()

isAvailable()

mount('#element')

unmount()

Events

onReady(FlowComponent)

onChange(FlowComponent)

onSubmit(FlowComponent)

onPaymentCompleted(FlowComponent, PaymentResponse)

onError(FlowComponent, CheckoutError)

onCardBinChanged(FlowComponent, CardMetadataResponse)

onTokenized(FlowComponent, TokenizeResult)

Callbacks

handleClick(FlowComponent)