FlowComponent

Last updated: May 14, 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 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 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 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});+

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}

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

Raised when the payment has been completed synchronously.

This event will not be 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 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');

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

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

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

Raised when you or the customer submit a FlowComponent element.

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

The SubmitData object contains the following information:

session_data – 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.

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)

handleSubmit(FlowComponent, SubmitData)