Flow library reference
Last updated: July 10, 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.
1/**2* Initializes a FlowComponent instance.3*4* @param {string} name - a name for the FlowComponent instance.5* @param {object} options - the callback options for the FlowComponent,6* including:7* - @param {method} onReady8* - @param {method} onChange9* - @param {method} onSubmit10* - @param {method} onPaymentCompleted11* - @param {method} onError12* - @param {method} handleClick13* - @param {boolean} showPayButton (not available for digital wallets,14* including Apple Pay and Google Pay)15* @return {FlowComponent} The FlowComponent instance16*/17const flowComponent = checkout.create('flow', {18showPayButton: false,19});
1/**2* Submits a FlowComponent, if you require your own pay button.3* Not available for digital wallets, including Apple Pay and Google Pay.4*5* @return {FlowComponent} The FlowComponent instance.6*/7function submit() {8return FlowComponent;9}
1/**2* Checks if the FlowComponent has captured all details from the3* customer and can be submitted.4*5* @return {boolean} Validity of the FlowComponent for submission.6*/7function isValid() {8return boolean;9}
1/**2* Checks if the FlowComponent can be rendered.3* Call this before mounting the FlowComponent.4*5* @return {Promise<boolean>}6*/7function isAvailable() {8return Promise<boolean>;9}
1/**2* Mounts a FlowComponent to a page.3* You can provide either:4* - an Element Selector5* (https://developer.mozilla.org/en-US/docs/Web/API/Element)6* - a DOM Element Object7* (https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors)8*9* @param {string} - the Element Selector or DOM Element object to mount to10* @return {FlowComponent}11*/12function mount('#elem') {13return FlowComponent;14}
1/**2* Unmounts a FlowComponent from the page.3* This stops the component rendering, and removes all life-cycles4* from the browser.5*6* @return {FlowComponent}7*/8function unmount() {9return FlowComponent;10}
1/**2* Fired when a FlowComponent is initialized and ready3* for the customer to interact.4*5* FlowComponent is the instance that fired the event.6*/7const flowComponent = checkout.create('flow', {8onReady: (_self) => {9// Hide loading overlay10hideLoadingOverlay();11},12});13flowComponent.mount('#flow-container');
1/**2* Fired when a FlowComponent changes after a3* customer interaction.4*5* FlowComponent is the instance that fired the event.6*/7const flowComponent = checkout.create('flow', {8onChange: (self) => {9// Enable/disable custom pay button based on input validity10if (self.isValid()) {11submitButton.removeAttribute('disabled');12} else {13submitButton.setAttribute('disabled', true);14}15},16});17flowComponent.mount('#flow-container');
1/**2* Fired when you or the customer have triggered a3* FlowComponent submission.4*5* FlowComponent is the instance that fired the event.6*/7const flowComponent = checkout.create('flow', {8onSubmit: (_self) => {9// Show loading overlay to prevent further user interaction10showLoadingOverlay();11},12});13flowComponent.mount('#flow-container');
1/**2* Fired when the payment has been completed synchronously.3* This event will not be fired if the payment requires4* asynchronous action. For example, 3DS authentication.5*6* FlowComponent is the instance that fired the event.7*8* PaymentResponse contains information on the successful payment:9* - {string} id - a unique identifier for the payment10* - {string} status - the payment status – will always be 'Approved'11* - {string} type - the name of the payment method that was used for the payment12*/13const flowComponent = checkout.create('flow', {14onPaymentCompleted: async (_self, paymentResponse) => {15// Complete order in server side16await completeOrder(paymentResponse.id);17},18});19flowComponent.mount('#flow-container');
1/**2* Fired when an error occurs.3*4* FlowComponent is the instance that fired the event.5*6* See the CheckoutError reference for more information.7*/8const flowComponent = checkout.create('flow', {9onError: async (_self, error) => {10// Display payment request failure message11if (error.code === 'payment_request_failed') {12showErrorMessage('Payment could not be processed. Please try again.');13}14},15});16flowComponent.mount('#flow-container');
1/**2* Triggered when a wallet payment button is clicked.3* For example, Apple Pay, Google Pay, or PayPal.4*5* You can use this to perform checks before6* beginning the payment process.7*8* FlowComponent is the instance that triggered the callback.9*/10const flowComponent = checkout.create('flow', {11handleClick: (_self) => {12if (acceptedTermsAndConditions) {13return { continue: true };14}15return { continue: false };16},17});18flowComponent.mount('#flow-container');
The Flow CheckoutError
class extends the standard JavaScript Error
class and contains the following properties:
Property | Type | Description |
---|---|---|
|
| A human-readable description of the error. The description is subject to change. For example, to improve clarity. To ensure you catch errors correctly, you should reference the values returned by the |
|
| The error class name. This will always return |
|
| The type of error encountered, as one of the following values: |
|
| A code representing the error. To see how to resolve the errors, see the Error codes section. |
|
| Additional error properties. All error types provide the following properties in the
Errors of type |
Integration errors are caused by an invalid use of the Flow Components library.
Errors of type Integration
contain the following properties within the details
object:
Property | Type | Description |
---|---|---|
|
| The unique identifier of the browser session that created the |
|
| The unique identifier of the provided payment session response. |
|
| The name of the payment method used for the payment. |
|
| The Element selector or DOM object that caused the mounting error. This property is only returned for errors with an |
Request errors are caused by network request failures.
Errors of type Request
contain the following properties within the details
object:
Property | Type | Description |
---|---|---|
|
| The unique identifier of the browser session that created the |
|
| The unique identifier of the provided payment session response. |
|
| The name of the payment method used for the payment. |
|
| The unique identifier for the declined payment request. |
| Array of | Additional error codes returned from the network request. |
|
| The unique identifier for the network request. |
|
| The HTTP response status code for the network request. |
Payment method errors are caused by unexpected failures when integrating a payment method's client-side library.
Errors of type PaymentMethod
contain the following properties within the details
object:
Property | Type | Description |
---|---|---|
|
| The unique identifier of the browser session that created the |
|
| The unique identifier of the provided payment session response. |
|
| The name of the payment method used for the payment. |
Submit errors are caused by invalid attempts to submit a payment request. For example, if you call the submit()
method before the customer has completed all of the required input fields.
Errors of type Submit
contain the following properties within the details
object:
Property | Type | Description |
---|---|---|
|
| The unique identifier of the browser session that created the |
|
| The unique identifier of the provided payment session response. |
|
| The name of the payment method used for the payment. |
Flow was loaded in a non-browser environment.
You should only load and execute Flow client-side.
If your integration involves server-side rendering or you have automated testing, check for existence of the Window object before you load Flow.
The result returned in a callback execution was invalid.
If you provide a custom callback, ensure it returns a result.
Flow supports Promises
returned in callbacks, in addition to direct results.
1const flowComponent = checkout.create('flow', {2handleClick: async (_self) => {3const canProceedPayment = await checkIfPaymentCanProceed();4return {5continue: canProceedPayment,6};7},8});910flowComponent.mount('#flow-container');
Flow has already been mounted to DOM with mount()
and cannot be mounted again.
If you need to mount Flow again because the checkout page changed, use the unmount()
method first before you call mount()
again.
1const flowComponent = cko.create('flow');2flowComponent.mount('#flow-container');34// Changes to the checkout page56flowComponent.unmount();7flowComponent.mount('#flow-container-2');
The payment request was submitted with the submit()
method before the customer had provided all of the details required by the chosen payment method.
If you're rendering a custom pay button and passed showPayButton: false
when you created the FlowComponent
, check that the customer inputs are valid with the isValid()
method before you submit a payment request.
1const flowComponent = checkout.create('flow');2flowComponent.mount('#flow-container');34const submitButton = element.querySelector('#submit');5submit.addEventListener(() => {6if (isFormValid() && flowComponent.isValid()) {7flowComponent.submit();8}9});
The isAvailable()
method was not called before mounting the FlowComponent
with mount()
. The component may not be supported by the customer device.
After you create the FlowComponent
, call the isAvailable()
method to verify that the payment method is supported by the customer device. This does not apply to a FlowComponent
of type payments
.
1const applepayElement = document.querySelector('#applepay-container');2const applepayComponent = checkout.create('applepay');34if (await applepayComponent.isAvailable()) {5applepayComponent.mount(applepayElement);6}
The name specified when creating the FlowComponent
using the create()
method is not supported.
If you are providing enabled_payment_methods
or disabled_payment_methods
options when you create the payment session, ensure you also include the payment method that you want to offer.
You should also ensure that the currency
and billing.address.country
values provided to the payment session match the payment method's requirements.
The Element selector or DOM object you provided when calling the mount()
method could not be found.
Ensure the Element selector you provide to the mount()
method is already mounted to the DOM. Alternatively, you can query for the DOM object and provide the reference when you call mount()
.
1const applepayElement = document.querySelector('#applepay-container');2const applepayComponent = checkout.create('applepay');34if (await applepayComponent.isAvailable()) {5applepayComponent.mount(applepayElement);6}
The payment attempt for the payment method specified in details.type
failed due to an unexpected failure.
Unexpected failures may occur when Flow integrates with a payment method's client-side library, or makes network requests to the payment method's endpoints.
If you persistently encounter the error for a specific payment method, this could be caused by your account configuration. For example, incomplete onboarding to a payment method. Contact your Account Manager or [email protected].
The payment request was declined.
The payment's ID is provided in the details.paymentId
property. You can fetch the details of the payment by performing a Get payment details request or searching for the payment record in the Dashboard.
The details.requestErrorCodes
property will contain one of the following error codes:
not_enough_funds
: the customer does not have enough funds for the transactioninvalid_payment_session_data
: invalid details were provided when creating the payment session, see the API reference for additional field detailsinvalid_customer_data
: invalid details were provided by the customermerchant_misconfiguration
: your account has invalid configurationstry_again
: the payment request was declined due to technical issues, contact your Account Manager or [email protected].
Flow automatically displays error messages to the customer, with suggested next actions to improve retry success.
The payment request failed due to unexpected error or network issue.
Any additional error codes from the network requests will be provided in the details.requestErrorCodes
property. See the possible error codes for the Payment endpoint for more details.
Customers can typically complete their payment after a retry.
If you persistently encounter the error for a specific payment method, this could be caused by your account configuration. Contact your Account Manager or [email protected].
The payment session response provided when initializing CheckoutWebComponents
was invalid.
After you create a payment session in your server-side integration, ensure you return the entire payment session response object to the client-side and provide it to Flow.