Flow library reference

Last updated: October 23, 2024

Use the Flow library reference to learn how to customize the Flow user experience with the available configuration options, and how to handle errors.

Initializes a CheckoutWebComponent instance.


1/**
2 * @param {object} appearance - customizes the visual appearance of the CheckoutWebComponent elements.
3 * @param {object} componentOptions - customizes the options for the individual Flow components.
4 * @param {string} componentOptions.card.data.cardholderName - the name to pre-populate the cardholder name input field for card payments with. 
5 * @param {string} componentOptions.card.displayCardholderName - the position of the cardholder name input field for card payments. Value can be either top, bottom, or hidden.
6 * @param {bool}   componentOptions.flow.expandFirstPaymentMethod - sets whether to automatically expand the first payment method, if there are multiple payment methods.
7 * @param {string} environment - sets the environment that the library should point and send requests to.
8 * @param {string} locale - sets the customer's locale.
9 * @param {object} paymentSession - the response from the PaymentSession.
10 * @param {string} publicKey - your public API key.
11 * @param {object} translations - customizes text translations for natively supported languages, or adds custom text for locales and languages not natively supported.
12 * 
13 * @return {CheckoutWebComponent} The CheckoutWebComponent instance.
14 */
15
16const checkout = await CheckoutWebComponents({
17  appearance,
18  componentOptions: {
19    flow: {
20      expandFirstPaymentMethod: false,
21    },
22    card: {
23      displayCardholderName: 'bottom',
24      data: {
25        cardholderName: 'Jia Tsang',
26      },
27    },
28  }
29  environment: 'sandbox',
30  locale: 'en',
31  paymentSession,
32  publicKey: 'pk_01234',
33  translations,
34});

Initializes a FlowComponent instance.


1/**
2 * @param {string} name - a name for the FlowComponent instance.
3 * @param {object} options - the event callbacks for the FlowComponent.
4 * 
5 * @return {FlowComponent} The FlowComponent instance.
6 */
7const flowComponent = checkout.create('flow', {
8  showPayButton: false,
9});

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.


1/** 
2 * @return {FlowComponent} The FlowComponent instance.
3 */
4function submit() {
5  return FlowComponent;
6}

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


1/**
2 * @return {boolean} Validity of the FlowComponent for submission.
3 */
4function isValid() {
5  return boolean;
6}

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


1/**
2 * @return {Promise<boolean>} 
3 */
4function isAvailable() {
5  return Promise<boolean>;
6}

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

a DOM Element Object
an Element Selector


1/**
2 * @param {string} - the Element Selector or DOM Element object to mount to
3 * 
4 * @return {FlowComponent} 
5 */
6function mount('#elem') {
7  return FlowComponent;
8}

Unmounts a FlowComponent from the page.

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


1/**
2 * @return {FlowComponent} 
3 */
4function unmount() {
5  return FlowComponent;
6}

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