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() {2return 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 – Onlycard
is supported.data
– The Card Tokenization responsecardMetadata
– An optional Card Metadata lookup response object included when a Card Metadata API response is received during customer input
1const cardComponent = checkout.create('card');23if (await cardComponent.isAvailable()) {4cardComponent.mount('#card-container');5}67const cardPayButton = document.getElementbyId('card-pay-button');89cardPayButton.addEventListener('click', async () => {10const { data } = await cardComponent.tokenize();1112await utilizeToken(data.token);13});+
Checks if the FlowComponent
has captured all details from the customer and can be submitted.
1function isValid() {2return boolean;3}
Checks if the FlowComponent
can be rendered. Call this before mounting the FlowComponent
.
1function isAvailable() {2return 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');23flowComponent.mount('#flow-container');45flowComponent.unselect();
Mounts a FlowComponent
to a page. You can provide one of the following:
Parameter | Type | Description |
---|---|---|
|
| The Element Selector or DOM Element object you want to mount to. |
1function mount('#element') {2return FlowComponent;3}
Unmounts a FlowComponent
from the page.
This stops rendering the component, and removes all life-cycles from the browser.
1function unmount() {2return FlowComponent;3}
Raised when a FlowComponent
is initialized and ready for the customer to interact.
1const flowComponent = checkout.create('flow', {2onReady: (_self) => {3// Hide loading overlay4hideLoadingOverlay();5},6});7flowComponent.mount('#flow-container');
Raised when a FlowComponent
changes after a customer interaction.
1const flowComponent = checkout.create('flow', {2onChange: (_self) => {3// Enable/disable custom pay button based on input validity4if (self.isValid()) {5submitButton.removeAttribute('disabled');6} else {7submitButton.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', {2onSubmit: (_self) => {3// Show loading overlay to prevent further user interaction4showLoadingOverlay();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 paymentstatus
– The payment status – This always returnsApproved
.type
– The name of the payment method used for the payment
1const flowComponent = checkout.create('flow', {2onPaymentCompleted: async (_self, paymentResponse) => {3// Complete order in server side4await 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', {2onError: async (_self, error) => {3// Display payment request failure message4if (error.code === 'payment_request_failed') {5showErrorMessage('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', {2onCardBinChanged: (_self, cardMetadata) => {3if (card_metadata.card_type === 'credit') {4return {5continue: false,6errorMessage: 'Credit cards are not accepted.',7};8}9return { continue: true };10}11});1213flowComponent.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 – Onlycard
is supported.data
– The Card Tokenization responsecardMetadata
– 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', {2onTokenized: (_self, tokenizeResult) => {3if (tokenizeResult.data.card_type === 'CREDIT') {4return {5continue: false,6errorMessage: 'Credit cards are not accepted.',7};8}9return { continue: true };10}11});1213flowComponent.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', {2onAuthorized: (_self, authorizeResult) => {3if (authorizeResult?.payment?.token?.paymentMethod?.type === 'credit') {4return {5continue: false,6errorMessage: 'Credit cards are not accepted.',7};8}910return { continue: true };1112},13});1415if (await applepayComponent.isAvailable()) {16applepayComponent.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', {2handleClick: (_self) => {3if (acceptedTermsAndConditions) {4return { continue: true };5}6return { 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;23const handlePaymentAdditionalContentMount = (_self, containerElement) => {4const identifier = `${component.type}-tnc`;56const checkbox = document.createElement('input');7checkbox.type = 'checkbox';8checkbox.name = identifier9checkbox.addEventListener('click', () => {10isCheckboxAccepted = checkbox.checked;11});1213const label = document.createElement('label');14label.innerHTML = 'By clicking the pay button, you authorize us to use your payment details to process the payment';1516element.appendChild(checkbox);17element.appendChild(label);1819return identifier;20};2122const handleClick = (_selef) => {23if (isCheckboxAccepted) {24return { continue: true };25}26return { continue: false };27};2829const checkout = await new CheckoutWebComponents({30paymentSession,31publicKey,32componentOptions: {33flow: {34handleClick,35handlePaymentAdditionalContentMount,36},37},38});3940const 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};45const handlePaymentAdditionalContentUnmount = (component, containerElement, mountIdentifier) => {6containerElement.innerHTML = '';7// Clean up the Terms and Conditions content.8};910const checkout = await new CheckoutWebComponents({11paymentSession,12publicKey,13componentOptions: {14flow: {15handlePaymentAdditionalContentMount,16handlePaymentAdditionalContentUnmount,17},18},19});2021const flowComponent = checkout.create('flow');22flowComponent.mount('#flow-container');