ExpressCheckout UI

Learn how to use the ExpressCheckout UI component on your site or in your app to securely accept digital wallet payments

Applies to:Developers

The ExpressCheckout component lets you embed an express checkout for digital wallets inside your website or application. This component provides seamless integration with Apple Pay and Google Pay.

an image of an ExpressCheckout component rendered on a site

Usage

This component lets you add a robust low-code way to accept payments from digital wallets to your pages or apps with automatic device compatibility detection. Follow the configuration walkthrough to set it up in your project.

See Library URLs for important information about embedded components library URLs.

Configuration walkthrough

The interactive walkthrough displays code examples alongside step-by-step explanations.

Select a tab to see the walkthrough for your desired use case.

Process a payment

Create a subscription

Tokenize a payment method

Process and tokenize

Loading walkthrough content

Loading walkthrough...

/// Include the Payabli script

First, add the Payabli embedded component script to your HTML. Make sure to include the data-test attribute for testing in the sandbox environment. Including <meta charset="UTF-8"> in the <head> element prevents problems with special characters such as ‘á’ or ‘ñ’. /// Create the container

Add a container element where the embedded component renders. The configuration references this element by its id attribute. This <div> element serves as the mounting point where the embedded component renders. /// Configure the component

Create the configuration object that defines how your embedded component behaves. This configuration includes authentication tokens, payment method settings, and callback functions. The rootContainer property connects the component to your HTML element by matching the id attribute value. The token value must be a public API token. See the Configuration Reference for more information. /// Add callback functions

Implement success, error, ready, and cancel callback functions to handle component responses and form validation states. These callback functions execute after the user interacts with the digital wallet buttons and the component receives a response from Payabli’s API. /// Initialize the component

The final step creates a working express checkout that can process transactions with digital wallets.

1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta charset="UTF-8">
5   <title>Payabli Integration</title>
6   <style>
7     .hidden { display: none; }
8     #response-display {
9       margin-top: 20px;
10       padding: 16px;
11       border-radius: 6px;
12       background: #f8fafc;
13       border: 1px solid #e2e8f0;
14     }
15     #pay-component-1 {
16       max-width: 400px;
17       margin: 20px 0;
18     }
19   </style>
20 </head>
21 <body>
22   <h1>Express Checkout</h1>
23   <p>Pay securely with your digital wallet:</p>
24   <div id="pay-component-1"></div>
25   <div id="response-display"></div>
26   
27   <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
28   <script>
29     const payabliConfig = {
30       type: "expressCheckout",
31       rootContainer: "pay-component-1",
32       token: "your-public-api-token",
33       entryPoint: "your-entry-point",
34       expressCheckout: {
35         amount: 100.00,
36         fee: 0.01,
37         currency: "USD",
38         supportedNetworks: ["visa", "masterCard", "amex", "discover"],
39         columns: 1,
40         applePay: {
41           enabled: true,
42           buttonStyle: "black-outline",
43           buttonType: "plain",
44           language: "en-US"
45         },
46         googlePay: {
47           enabled: true,
48           buttonStyle: "dark",
49           buttonType: "plain",
50           language: "en"
51         },
52         requiredShippingContactFields: true,
53         appearance: {
54           buttonHeight: 50,
55           buttonBorderRadius: 10,
56           padding: {
57             x: 10,
58             y: 10
59           }
60         }
61       },
62       customerData: {
63         customerNumber: "00001",
64         firstName: "John",
65         lastName: "Doe",
66         billingEmail: "john.doe@example.com"
67       },
68       functionCallBackReady: function(data) {
69         console.log('Express Checkout ready:', data);
70         const available = [];
71         if (data.applePay) available.push('Apple Pay');
72         if (data.googlePay) available.push('Google Pay');
73         
74         document.getElementById("response-display").innerHTML += `
75           <hr/>
76           <p><strong>Express Checkout Ready</strong></p>
77           <p>Available: ${available.join(', ')}</p>
78           <hr/>
79         `;
80       },
81       functionCallBackSuccess: function(data) {
82         console.log('Express Checkout Success:', data);
83         document.getElementById("response-display").innerHTML += `
84           <hr/>
85           <p><strong>Payment Successful!</strong></p>
86           <p>Reference ID: ${data.data.responseData.referenceId}</p>
87           <p>Payment Method: ${data.paymentMethod}</p>
88           <p>Customer: ${data.data.responseData.billingContact.givenName} ${data.data.responseData.billingContact.familyName}</p>
89           <hr/>
90         `;
91       },
92       functionCallBackError: function(data) {
93         console.log('Express Checkout Error:', data);
94         document.getElementById("response-display").innerHTML += `
95           <hr/>
96           <p><strong>Payment Failed</strong></p>
97           <p>Error: ${data.error.responseText}</p>
98           <hr/>
99         `;
100       },
101       functionCallBackCancel: function(data) {
102         console.log('Express Checkout Cancel:', data);
103         document.getElementById("response-display").innerHTML += `
104           <hr/>
105           <p><strong>Payment Cancelled</strong></p>
106           <p>The payment was cancelled by the user.</p>
107           <hr/>
108         `;
109       }
110     };
111 
112     // Initialize the ExpressCheckout component
113     const expressCheckout = new PayabliComponent(payabliConfig);
114   </script>
115 </body>
116 </html>

/// Include the Payabli script

Set mode to "autopay" inside the expressCheckout object to enable recurring transactions. Include the autopay object to define the billing schedule. The frequency and startDate fields are required. Set untilCancel to true to continue billing until the customer cancels the subscription, or set an endDate value to automatically stop billing after a certain date. /// Add callback functions

Implement success, error, ready, and cancel callback functions to handle component responses. When mode is "autopay", the success callback indicates that a recurring subscription has been created. The flow field in the response will be "autopay". /// Initialize the component

The final step creates a working express checkout that sets up recurring autopay subscriptions using digital wallets.

1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta charset="UTF-8">
5   <title>Payabli Integration</title>
6   <style>
7     .hidden { display: none; }
8     #response-display {
9       margin-top: 20px;
10       padding: 16px;
11       border-radius: 6px;
12       background: #f8fafc;
13       border: 1px solid #e2e8f0;
14     }
15     #pay-component-1 {
16       max-width: 400px;
17       margin: 20px 0;
18     }
19   </style>
20 </head>
21 <body>
22   <h1>Express Checkout</h1>
23   <p>Set up recurring payments with your digital wallet:</p>
24   <div id="pay-component-1"></div>
25   <div id="response-display"></div>
26   
27   <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
28   <script>
29     const payabliConfig = {
30       type: "expressCheckout",
31       rootContainer: "pay-component-1",
32       token: "your-public-api-token",
33       entryPoint: "your-entry-point",
34       expressCheckout: {
35         mode: "autopay",
36         amount: 100.00,
37         fee: 0.01,
38         currency: "USD",
39         supportedNetworks: ["visa", "masterCard", "amex", "discover"],
40         columns: 1,
41         autopay: {
42           frequency: "monthly",
43           startDate: "2026-06-20",
44           untilCancel: true
45         },
46         applePay: {
47           enabled: true,
48           buttonStyle: "black-outline",
49           buttonType: "plain",
50           language: "en-US"
51         },
52         googlePay: {
53           enabled: true,
54           buttonStyle: "dark",
55           buttonType: "plain",
56           language: "en"
57         },
58         requiredShippingContactFields: true,
59         appearance: {
60           buttonHeight: 50,
61           buttonBorderRadius: 10,
62           padding: {
63             x: 10,
64             y: 10
65           }
66         }
67       },
68       customerData: {
69         customerNumber: "00001",
70         firstName: "John",
71         lastName: "Doe",
72         billingEmail: "john.doe@example.com"
73       },
74       functionCallBackReady: function(data) {
75         console.log('Express Checkout ready:', data);
76         const available = [];
77         if (data.applePay) available.push('Apple Pay');
78         if (data.googlePay) available.push('Google Pay');
79         
80         document.getElementById("response-display").innerHTML += `
81           <hr/>
82           <p><strong>Express Checkout Ready</strong></p>
83           <p>Available: ${available.join(', ')}</p>
84           <hr/>
85         `;
86       },
87       functionCallBackSuccess: function(data) {
88         console.log('Express Checkout Autopay Success:', data);
89         document.getElementById("response-display").innerHTML += `
90           <hr/>
91           <p><strong>Autopay Subscription Created!</strong></p>
92           <p>Reference ID: ${data.data.responseData.referenceId}</p>
93           <p>Payment Method: ${data.paymentMethod}</p>
94           <p>Flow: ${data.flow}</p>
95           <hr/>
96         `;
97       },
98       functionCallBackError: function(data) {
99         console.log('Express Checkout Error:', data);
100         document.getElementById("response-display").innerHTML += `
101           <hr/>
102           <p><strong>Setup Failed</strong></p>
103           <p>Error: ${data.error.responseText}</p>
104           <hr/>
105         `;
106       },
107       functionCallBackCancel: function(data) {
108         console.log('Express Checkout Cancel:', data);
109         document.getElementById("response-display").innerHTML += `
110           <hr/>
111           <p><strong>Cancelled</strong></p>
112           <p>The autopay setup was cancelled by the user.</p>
113           <hr/>
114         `;
115       }
116     };
117 
118     // Initialize the ExpressCheckout component
119     const expressCheckout = new PayabliComponent(payabliConfig);
120   </script>
121 </body>
122 </html>

/// Include the Payabli script

Set mode to "tokenization" inside the expressCheckout object to save the customer’s payment method without charging it. Optionally, set fallbackAuthAmount to specify an authorization amount for validating the method, and methodDescription to save the payment method with a label. When mode is set to tokenization, the amount and fee fields are required but ignored by the component. /// Add callback functions

Implement success, error, ready, and cancel callback functions to handle component responses. When mode is "tokenization", no charge is made. The success callback indicates that the payment method has been saved. Use responseData.methodReferenceId to retrieve the stored method’s token for future use. The flow field in the response will be "tokenization". /// Initialize the component

The final step creates a working express checkout that tokenizes digital wallet payment methods for future use without charging the customer.

1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta charset="UTF-8">
5   <title>Payabli Integration</title>
6   <style>
7     .hidden { display: none; }
8     #response-display {
9       margin-top: 20px;
10       padding: 16px;
11       border-radius: 6px;
12       background: #f8fafc;
13       border: 1px solid #e2e8f0;
14     }
15     #pay-component-1 {
16       max-width: 400px;
17       margin: 20px 0;
18     }
19   </style>
20 </head>
21 <body>
22   <h1>Save Payment Method</h1>
23   <p>Save your digital wallet for future payments:</p>
24   <div id="pay-component-1"></div>
25   <div id="response-display"></div>
26   
27   <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
28   <script>
29     const payabliConfig = {
30       type: "expressCheckout",
31       rootContainer: "pay-component-1",
32       token: "your-public-api-token",
33       entryPoint: "your-entry-point",
34       expressCheckout: {
35         mode: "tokenization",
36         amount: 0,
37         fee: 0,
38         currency: "USD",
39         supportedNetworks: ["visa", "masterCard", "amex", "discover"],
40         columns: 1,
41         fallbackAuthAmount: 1.00,
42         methodDescription: "Digital Wallet on File",
43         applePay: {
44           enabled: true,
45           buttonStyle: "black-outline",
46           buttonType: "plain",
47           language: "en-US"
48         },
49         googlePay: {
50           enabled: true,
51           buttonStyle: "dark",
52           buttonType: "plain",
53           language: "en"
54         },
55         requiredShippingContactFields: true,
56         appearance: {
57           buttonHeight: 50,
58           buttonBorderRadius: 10,
59           padding: {
60             x: 10,
61             y: 10
62           }
63         }
64       },
65       customerData: {
66         customerNumber: "00001",
67         firstName: "John",
68         lastName: "Doe",
69         billingEmail: "john.doe@example.com"
70       },
71       functionCallBackReady: function(data) {
72         console.log('Express Checkout ready:', data);
73         const available = [];
74         if (data.applePay) available.push('Apple Pay');
75         if (data.googlePay) available.push('Google Pay');
76         
77         document.getElementById("response-display").innerHTML += `
78           <hr/>
79           <p><strong>Express Checkout Ready</strong></p>
80           <p>Available: ${available.join(', ')}</p>
81           <hr/>
82         `;
83       },
84       functionCallBackSuccess: function(data) {
85         console.log('Express Checkout Tokenization Success:', data);
86         document.getElementById("response-display").innerHTML += `
87           <hr/>
88           <p><strong>Payment Method Saved!</strong></p>
89           <p>Method Reference ID: ${data.data.responseData.methodReferenceId}</p>
90           <p>Payment Method: ${data.paymentMethod}</p>
91           <p>Flow: ${data.flow}</p>
92           <hr/>
93         `;
94       },
95       functionCallBackError: function(data) {
96         console.log('Express Checkout Error:', data);
97         document.getElementById("response-display").innerHTML += `
98           <hr/>
99           <p><strong>Save Failed</strong></p>
100           <p>Error: ${data.error.responseText}</p>
101           <hr/>
102         `;
103       },
104       functionCallBackCancel: function(data) {
105         console.log('Express Checkout Cancel:', data);
106         document.getElementById("response-display").innerHTML += `
107           <hr/>
108           <p><strong>Cancelled</strong></p>
109           <p>The payment method save was cancelled by the user.</p>
110           <hr/>
111         `;
112       }
113     };
114 
115     // Initialize the ExpressCheckout component
116     const expressCheckout = new PayabliComponent(payabliConfig);
117   </script>
118 </body>
119 </html>

/// Include the Payabli script

To enable payment method tokenization, add the saveIfSuccess field to your configuration and set its value to true. After a successful transaction, the component saves the payment method for future use. You can access the tokenized payment method in the response object’s data.methodReferenceId field. /// Add callback functions

The final step creates a working express checkout that can process transactions with digital wallets.

1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta charset="UTF-8">
5   <title>Payabli Integration</title>
6   <style>
7     .hidden { display: none; }
8     #response-display {
9       margin-top: 20px;
10       padding: 16px;
11       border-radius: 6px;
12       background: #f8fafc;
13       border: 1px solid #e2e8f0;
14     }
15     #pay-component-1 {
16       max-width: 400px;
17       margin: 20px 0;
18     }
19   </style>
20 </head>
21 <body>
22   <h1>Express Checkout</h1>
23   <p>Pay securely with your digital wallet:</p>
24   <div id="pay-component-1"></div>
25   <div id="response-display"></div>
26   
27   <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
28   <script>
29     const payabliConfig = {
30       type: "expressCheckout",
31       rootContainer: "pay-component-1",
32       token: "your-public-api-token",
33       entryPoint: "your-entry-point",
34       expressCheckout: {
35         amount: 100.00,
36         fee: 0.01,
37         saveIfSuccess: true,
38         currency: "USD",
39         supportedNetworks: ["visa", "masterCard", "amex", "discover"],
40         columns: 1,
41         applePay: {
42           enabled: true,
43           buttonStyle: "black-outline",
44           buttonType: "plain",
45           language: "en-US"
46         },
47         googlePay: {
48           enabled: true,
49           buttonStyle: "dark",
50           buttonType: "plain",
51           language: "en"
52         },
53         requiredShippingContactFields: true,
54         appearance: {
55           buttonHeight: 50,
56           buttonBorderRadius: 10,
57           padding: {
58             x: 10,
59             y: 10
60           }
61         }
62       },
63       customerData: {
64         customerNumber: "00001",
65         firstName: "John",
66         lastName: "Doe",
67         billingEmail: "john.doe@example.com"
68       },
69       functionCallBackReady: function(data) {
70         console.log('Express Checkout ready:', data);
71         const available = [];
72         if (data.applePay) available.push('Apple Pay');
73         if (data.googlePay) available.push('Google Pay');
74         
75         document.getElementById("response-display").innerHTML += `
76           <hr/>
77           <p><strong>Express Checkout Ready</strong></p>
78           <p>Available: ${available.join(', ')}</p>
79           <hr/>
80         `;
81       },
82       functionCallBackSuccess: function(data) {
83         console.log('Express Checkout Success:', data);
84         document.getElementById("response-display").innerHTML += `
85           <hr/>
86           <p><strong>Payment Successful!</strong></p>
87           <p>Reference ID: ${data.data.responseData.referenceId}</p>
88           <p>Payment Method: ${data.paymentMethod}</p>
89           <p>Customer: ${data.data.responseData.billingContact.givenName} ${data.data.responseData.billingContact.familyName}</p>
90           <hr/>
91         `;
92       },
93       functionCallBackError: function(data) {
94         console.log('Express Checkout Error:', data);
95         document.getElementById("response-display").innerHTML += `
96           <hr/>
97           <p><strong>Payment Failed</strong></p>
98           <p>Error: ${data.error.responseText}</p>
99           <hr/>
100         `;
101       },
102       functionCallBackCancel: function(data) {
103         console.log('Express Checkout Cancel:', data);
104         document.getElementById("response-display").innerHTML += `
105           <hr/>
106           <p><strong>Payment Cancelled</strong></p>
107           <p>The payment was cancelled by the user.</p>
108           <hr/>
109         `;
110       }
111     };
112 
113     // Initialize the ExpressCheckout component
114     const expressCheckout = new PayabliComponent(payabliConfig);
115   </script>
116 </body>
117 </html>

Use cases

The ExpressCheckout component has four use cases:

process a payment
create a subscription
tokenize a payment method
process a payment and tokenize the payment method

The use case of the component is determined by the value of the mode field in the expressCheckout configuration object. If the mode field isn’t defined, the component defaults to processing one-time payments.

Process a payment

In this use case, the ExpressCheckout component processes a one-time transaction for a specified amount. This is the most common use case for the ExpressCheckout component. To enable this use case, set the mode field to one_time or leave it empty.

Create a subscription

In this use case, the ExpressCheckout component sets up a recurring subscription with a billing schedule. The component then makes a $0.01 authorization to verify the customer’s payment method and then voids the authorization. The billing schedule is determined by the frequency, startDate, and endDate fields in the autopay configuration object. To enable this use case, set the mode field to autopay and define an autopay configuration object.

Tokenize a payment method

In this use case, the ExpressCheckout component tokenizes the customer’s payment method without processing a transaction. The component then makes a $0.01 authorization to verify the customer’s payment method and then voids the authorization. The tokenized payment method can be used for future transactions. To enable this use case, set the mode field to tokenization.

Process and tokenize

In this use case, the ExpressCheckout component processes a one-time transaction and also tokenizes the customer’s payment method for future use. To enable this use case, set the mode field to one_time and set the saveIfSuccess field to true.

Configuration reference

These are the configuration parameters available for the ExpressCheckout component.

type

stringRequired

This value determines the type of embedded component to render.
Accepted values are: methodEmbedded, methodLightbox, vterminal, or expressCheckout.
For the ExpressCheckout UI, this value is expressCheckout. See the Embedded Components Overview for more information on other component types.

rootContainer

stringRequired

Container ID used for the component.

includeDetails

booleanDefaults to false

When true, transactionDetails object is returned in the response. See a full example of the transactionDetails object in the Transaction integration guide. This field only applies when the mode field is set to one_time or not provided. If the mode field is set to tokenization or autopay, this field is ignored.

token

stringRequired

API token for authentication. This should be a public API token, as described here.

entryPoint

stringRequired

When the API token belongs to an organization, the entrypoint name identifies the target paypoint (merchant).

customCssUrl

string

Complete URL of a custom CSS stylesheet to use with the component.

expressCheckout

objectRequired

Configuration for the express checkout functionality.

properties

mode

stringDefaults to one_time

The use case that the component performs. Accepted values are:

one_time - The component processes a one-time transaction
autopay - The component sets up a recurring subscription with a billing schedule
tokenization - The component tokenizes the customer’s payment method

amount

numberRequired

The amount for the transaction. If the mode field is set to tokenization, this field is required but ignored by the component.

fee

numberRequired

The fee for the transaction. If the mode field is set to tokenization, this field is required but ignored by the component.

saveIfSuccess

boolean

When true, if the transaction is successful, the payment method is tokenized and returned in the response. Unlike mode: tokenization, which only tokenizes the payment method, this field processes the transaction and tokenizes the payment method. This field only applies when the mode field is set to one_time. If the mode field is set to tokenization or autopay, this field is ignored.

invoiceData

object

Invoice data to associate with the transaction. When the mode field is set to one_time or autopay, a successful transaction creates an invoice with the provided data. This field is ignored when mode is set to tokenization.

properties

invoiceNumber

stringRequired

Invoice number. Identifies the invoice under a paypoint.

invoiceDate

string

Invoice date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.

invoiceDueDate

string

Invoice due date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.

invoiceEndDate

string

End date for a scheduled invoice cycle when invoiceType is 1. Accepted formats: YYYY-MM-DD or MM/DD/YYYY.

invoiceType

number

Invoice type. Value 0 is for single/one-time invoices, 1 for scheduled invoices.

invoiceStatus

number

Invoice status code.

frequency

string

Frequency of scheduled invoice. Accepted values are:

onetime
weekly
every2weeks
monthly
every3months
every6months
annually

paymentTerms

string

Payment terms for the invoice. If no terms are defined, defaults to NET30. Accepted values are:

PIA, CIA, UR
NET10, NET20, NET30, NET45, NET60, NET90
EOM, MFI, 5MFI, 10MFI, 15MFI, 20MFI
2/10NET30
UF, 10UF, 20UF, 25UF, 50UF

termsConditions

string

Custom terms and conditions included in the invoice.

notes

string

Notes included in the invoice.

purchaseOrder

string

Purchase order number.

firstName

string

First name of the recipient of the invoice.

lastName

string

Last name of the recipient of the invoice.

company

string

Company name of the recipient of the invoice.

shippingAddress1

string

The shipping address.

shippingAddress2

string

Additional line for shipping address.

shippingCity

string

Shipping city.

shippingState

string

Shipping state or province.

shippingZip

string

Shipping ZIP code. Supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: 37615-1234 or 37615.

shippingCountry

string

Shipping address country.

shippingEmail

string

Shipping recipient’s contact email address.

shippingPhone

string

Recipient phone number.

shippingFromZip

string

Sender shipping ZIP code.

summaryCommodityCode

string

Commodity code.

invoiceAmount

number

The invoice amount.

tax

number

Tax rate in percent applied to the invoice.

discount

number

Discount applied to the invoice.

freightAmount

number

Freight/shipping amount.

dutyAmount

number

Duty amount.

items

object[]

Array of line items included in the invoice.

properties

itemProductCode

string

Item or product code. Max length of 250 characters.

itemProductName

string

Item or product name. Max length of 250 characters.

itemDescription

string

Item or product description. Max length of 250 characters.

itemCommodityCode

string

Item or product commodity code. Max length of 250 characters.

itemMode

number

Internal class of item or product. Value 0 is only for invoices, 1 for bills, and 2 is common for both. Required on invoice line items — invoice creation fails with Invalid item data if it’s omitted.

itemQty

number

Quantity of item or product.

itemCost

number

Item or product price per unit.

itemTotalAmount

number

Per-line total for this item (unit cost times quantity). Required on invoice line items.

itemTaxRate

number

Tax rate applied to item or product.

itemTaxAmount

number

Tax amount applied to item or product.

itemUnitOfMeasure

string

Unit of measurement. Max length of 100 characters.

itemCategories

string[]

Array of tags classifying item or product.

attachments

object[]

Array of file objects with attached documents. Max upload size is 30 MB.

properties

filename

string

The name of the attached file.

ftype

string

File type. Accepted values are: pdf, doc, docx, jpg, jpeg, png, gif, txt.

fContent

string

Content of file, Base64-encoded. Ignored if furl is specified. Max upload size is 30 MB.

furl

string

Optional URL to show or download the file remotely.

AdditionalData

object

Custom dictionary of key-value pairs. Use this field to store any data related to the object or for your system.

splitFunding

object[]

Split funding instructions for the transaction. The total amount of the splits must match the total amount of the transaction. See Split a Transaction for more.

properties

accountId

string

The accountId for the account the split should be sent to.

amount

numberRequired

Amount from the transaction to send to this recipient.

description

string

A description for the split.

recipientEntryPoint

stringRequired

The entrypoint the split should be sent to.

currency

stringRequired

The currency for the transaction.

columns

objectDefaults to 1

Define the number of columns to use for digital wallet display.

supportedNetworks

string[]Required

Card networks to accept payments from. Suggested options:

amex
visa
discover
masterCard
jcb

autopay

object

Configuration for recurring transactions. This object is required when the mode field is set to autopay.

properties

frequency

stringRequired

The frequency of the recurring transaction. Accepted values are:

onetime
weekly
every2weeks
monthly
every3months
every6months
annually

startDate

stringRequired

The start date for the recurring transaction in ISO 8601 format (example: "2026-06-20"). Must be a future date.

endDate

string

The end date for the recurring transaction in ISO 8601 format (example: "2027-12-20"). Must be later than the value of the startDate field. If not provided, the recurring transaction continues indefinitely until cancelled.

untilCancel

boolean

When true, the recurring transaction continues indefinitely until cancelled. If endDate is also provided, the recurring transaction continues until the end date is reached or the transaction is cancelled.

fallbackAuthAmount

number

Amount to use for authorization when the mode field is set to tokenization.

methodDescription

string

Partner-facing label for the payment method tokenized by the ExpressCheckout component when the mode field is set to tokenization.

applePay

objectRequired

properties

enabled

booleanRequired

When true, Apple Pay is enabled.

buttonStyle

enumDefaults to black

The Apple Pay button style. Supported options:

“black”: Default black button.
“white-outline”: White button with an outline.
“white”: Solid white button.

buttonType

enumDefaults to plain

The text on Apple Pay button. Supported options:

Button Type	Description	Text on Apple Pay Button
`"plain"`	An Apple Pay button with the Apple Pay logo only, useful when an additional call to action isn’t needed.	Apple Pay logo only (no text)
`"buy"`	Use this button for product purchases.	Buy with Apple Pay logo
`"donate"`	Used by approved nonprofits. Lets people make donations.	Donate with Apple Pay logo
`"check-out"`	Use this button for purchase experiences that include other payment buttons that start with “Check out”.	Check Out with Apple Pay logo
`"book"`	Use this button for booking appointments, flights, or other experiences.	Book with Apple Pay logo
`"continue"`	Use this button for general purchases.	Continue with Apple Pay logo
`"top-up"`	Use this button for adding money to an account, or payment system.	Top Up with Apple Pay logo
`"order"`	Use this button for placing orders for items.	Order with Apple Pay logo
`"rent"`	Use this button for renting items such as equipment or cars.	Rent with Apple Pay logo
`"support"`	Use this button for helping people give money to projects, causes, organizations, and other entities.	Support with Apple Pay logo
`"contribute"`	Use this button to help people give money to projects, causes, organizations, and other entities.	Contribute with Apple Pay logo
`"tip"`	Use this button to let people tip for goods or services.	Tip with Apple Pay logo
`"pay"`	Use this button for general purchases.	Pay with Apple Pay logo

language

enumDefaults to en-us

The Apple Pay button locale. Supported options:

en-US: English (US)
ar-AB: Arabic
ca-ES: Catalan
zh-CN: Chinese (China)
zh-HK: Chinese (Hong Kong)
zh-TW: Chinese (Taiwan)
hr-HR: Croatian
cs-CZ: Czech
da-DK: Danish
de-DE: German
nl-NL: Dutch
en-AU: English (Australia)
en-GB: English (UK)
fi-FI: Finnish
fr-CA: French (Canada)
fr-FR: French (France)
el-GR: Greek
he-IL: Hebrew
hi-IN: Hindi
hu-HU: Hungarian
id-ID: Indonesian
it-IT: Italian
ja-JP: Japanese
ko-KR: Korean
ms-MY: Malay
nb-NO: Norwegian
pl-PL: Polish
pt-BR: Portuguese (Brazil)
pt-PT: Portuguese (Portugal)
ro-RO: Romanian
ru-RU: Russian
sk-SK: Slovak
es-MX: Spanish (Mexico)
es-ES: Spanish (Spain)
sv-SE: Swedish
th-TH: Thai
tr-TR: Turkish
uk-UA: Ukrainian
vi-VN: Vietnamese

googlePay

objectRequired

properties

enabled

booleanRequired

When true, Google Pay is enabled.

buttonStyle

enumDefaults to black

The Google Pay button style. Supported options:

“dark”: Solid black button.
“light”: Solid white button.

buttonType

enumDefaults to plain

The text on Google Pay button. Supported options:

Button Type	Description	Text on Google Pay Button
`"plain"`	An Google Pay button with the Google Pay logo only, useful when an additional call to action isn’t needed.	Google Pay logo only (no text)
`"buy"`	Use this button for product purchases.	Buy with Google Pay logo
`"donate"`	Used by approved nonprofits. Lets people make donations.	Donate with Google Pay logo
`"checkout"`	Use this button for purchase experiences that include other payment buttons that start with “Check out”.	Check Out with Google Pay logo
`"book"`	Use this button for booking appointments, flights, or other experiences.	Book with Google Pay logo
`"order"`	Use this button for placing orders for items.	Order with Google Pay logo
`"pay"`	Use this button for general purchases.	Pay with Google Pay logo

language

enumDefaults to en

The Google Pay button locale. Supported options:

en: English
ar: Arabic
bg: Bulgarian
ca: Catalan
cs: Czech
da: Danish
de: German
el: Greek
es: Spanish
et: Estonian
fi: Finnish
fr: French
hr: Croatian
id: Indonesian
it: Italian
ja: Japanese
ko: Korean
ms: Malay
nl: Dutch
no: Norwegian
pl: Polish
pt: Portuguese
ru: Russian
sk: Slovak
sl: Slovenian
sr: Serbian
sv: Swedish
th: Thai
tr: Turkish
uk: Ukrainian
zh: Chinese

requiredShippingContactFields

boolean

When this field is true, the following fields ["postalAddress", "name", "phoneticName", "phone", "email"] are required. They are sent with the payment and can be read through the callbacks.

appearance

object

properties

buttonHeight

numberDefaults to 44

Height of the button.

buttonBorderRadius

numberDefaults to 4

Border radius of the button.

padding

object

properties

numberDefaults to 8

Horizontal padding.

numberDefaults to 11

Vertical padding.

customerData

objectRequired

properties

customerNumber

stringRequired

Customer’s identification number.

firstName

stringRequired

Customer’s first name.

lastName

stringRequired

Customer’s last name.

billingEmail

stringRequired

Customer’s billing email address.

functionCallBackReady

function

Triggered when the ExpressCheckout component is ready to use.

functionCallBackSuccess

function

Triggered upon successful completion of a digital wallet transaction.

functionCallBackError

function

Triggered if an error occurs during the digital wallet transaction.

functionCallBackCancel

function

Triggered if the user cancels the digital wallet transaction.

Response

The ExpressCheckout component uses callback functions to handle responses. The callback functions are triggered based on the component’s state. There are four callback functions you can define in the configuration:

functionCallBackReady: Triggered when the component is ready to use.
functionCallBackSuccess: Triggered when a transaction is successfully completed.
functionCallBackError: Triggered if an error occurs during the transaction.
functionCallBackCancel: Triggered if the user cancels the transaction.

Each callback function receives a different response object that contains information about the component’s state.

`functionCallbackReady` response

The functionCallbackReady response is triggered when the component is ready to use.

Ready response

1 {
2   applePay: true,
3   googlePay: false
4 }

applePay

boolean

When true, the component is ready to accept Apple Pay.

googlePay

boolean

When true, the component is ready to accept Google Pay.

`functionCallbackSuccess` response

The functionCallBackSuccess response is triggered when a use case is successfully completed with the ExpressCheckout component. The shape of the response object varies based on the use case selected by the mode field. The data sub-object of the response contains the response from an API endpoint called by the ExpressCheckout component. See the following table for which endpoint is called based on the mode field:

`mode` field value	API endpoint called
`one_time` or empty	/MoneyIn/getpaid
`autopay`	/Subscription/add
`tokenization`	/TokenStorage/add

For one-time payments, the referenceId field of the response object is the transaction ID. If the saveIfSuccess field is set to true, the methodReferenceId field contains the stored payment method’s ID. For tokenization, the referenceId field of the response object is the stored payment method’s ID. For autopay, the responseData field of the response object is the subscription ID.

1 {
2     data: {
3         isSuccess: true,
4         pageIdentifier: "t.XMzKRgtV6eJrI2Fsn45RLKuRujHi53qDnsizyJXNM7ChdejoRNOdb0Dm7VXQ3H/aBVMu+14IB9sOS1hbZF/kXMKgUY94nspVI+mRSphe8HeSwbr5OxLUSmu0Uuc6RmDzaLUYXn8eDr…",
5         responseData: {
6             methodReferenceId: null,
7             // `referenceID` = transaction ID
8             referenceId: "1148-2305e2cb80eb5969920f2cf9f2565455",
9             authCode: "",
10             avsResponseText: null,
11             billingContact: {
12                 addressLines: ["9425 SW 172nd Pl"],
13                 administrativeArea: "FL",
14                 country: "United States",
15                 countryCode: "US",
16                 familyName: "Martinez",
17                 givenName: "Fernando",
18                 locality: "Miami",
19                 phoneticFamilyName: "",
20                 phoneticGivenName: "",
21                 postalCode: "33197",
22                 subAdministrativeArea: "",
23                 subLocality: ""
24             },
25             customerId: 6886,
26             cvvResponseText: null,
27             resultCode: 1,
28             resultText: "Approved",
29             shippingContact: {
30                 addressLines: ["9425 SW 172nd Pl"],
31                 administrativeArea: "FL",
32                 country: "United States",
33                 countryCode: "US",
34                 emailAddress: "fernandotest@payabli.com",
35                 familyName: "Martinez",
36                 givenName: "Fernando",
37                 locality: "Miami",
38                 phoneNumber: "4089752020",
39                 phoneticFamilyName: "4192412942195",
40                 phoneticGivenName: "941924129412943",
41                 postalCode: "33197",
42                 subAdministrativeArea: "",
43                 subLocality: ""
44             }
45         },
46         responseText: "Success"
47     },
48     paymentMethod: "apple_pay",
49     flow: "one_time"
50 }

data

object

Container for response data. The shape of this object varies based on the use case of the component. This object contains the response from one of the following API endpoints based on the value of the mode field:

one_time or empty: /MoneyIn/getpaid
autopay: /Subscription/add
tokenization: /TokenStorage/add

See the API reference for each endpoint for more information about the shape of the response data.

paymentMethod

string

The payment method used. Possible values include "apple_pay" and "google_pay".

flow

string

The use case that the component performed. This field’s value is equal to the mode field in the component configuration. Possible values are:

one_time
autopay
tokenization

`functionCallBackError` response

This response is triggered if an error occurs during the transaction.

Error response

1 {
2   paymentMethod: "apple_pay", // apple_pay, google_pay
3   flow: "one_time", // one_time, autopay, tokenization
4   error: {
5     isSuccess: false,
6     pageIdentifier: null,
7     responseCode: 5005,
8     responseData: {
9       explanation: "",
10       todoAction: ""
11     },
12     responseText: "",
13     roomId: null
14   }
15 }

paymentMethod

string

The payment method used. Possible values include "apple_pay" or "google_pay".

flow

string

The use case that the component attempted to perform when the error occurred. This field’s value is equal to the mode field in the component configuration. Possible values are:

one_time
autopay
tokenization

error

object

Container for error details when an error occurs.

properties

isSuccess

boolean

Indicates whether the operation was successful. In error cases, this is false.

pageIdentifier

string

Auxiliary validation used by Payabli in payment pages and components.

responseCode

number

The error code. For example, 5005. See API responseCode and resultCode Reference for a full list of error codes.

responseData

object

Additional details about the error.

properties

explanation

string

A detailed explanation of the error.

todoAction

string

Suggested action to resolve the error.

responseText

string

A brief description of the error.

roomId

number

Internal field used by Payabli.

`functionCallBackCancel` response

This response is triggered if the user cancels the transaction while the modal is visible.

Cancel response

1 {
2   data: {
3     isTrusted: true
4   },
5   paymentMethod: "apple_pay"
6 }

data

object

Container for response data.

properties

isTrusted

boolean

In this field, true indicates that the event was triggered by a user action, such as a user manually canceling the payment process.

paymentMethod

string

The digital wallet method used.

Combine components

If you want to accept digital wallet payments along with card or ACH payments, you can load both the EmbeddedMethod UI and ExpressCheckout UI components on the same webpage. You can also use updateConfig to switch between component configurations on your page.

The code example renders the components in this image:

Combine components walkthrough

The interactive walkthrough displays code examples alongside step-by-step explanations.

Loading walkthrough content

Loading walkthrough...

/// Include the Payabli script

Add a container for the ExpressCheckout component, wrapped in a hidden div that the component reveals once it’s ready. Below that, add button-based tabs so you can switch between card and ACH, and a shared container for the EmbeddedMethod component. /// Add styles

Add CSS for the hidden class, the “or pay with” divider, the tab bar, and the payment button. /// Configure the card component

Create the configuration object for the EmbeddedMethod card component. The rootContainer value must match the id of the container div. The token value must be a public API token. Setting defaultOpen: "card" makes the card form the default view. /// Configure the ACH component

Create a second EmbeddedMethod configuration for ACH payments. Both card and ACH configs share the same rootContainer — updateConfig swaps between them when the user switches tabs. Setting defaultOpen: "ach" pre-selects the bank account form when this config is active. /// Configure the ExpressCheckout component

Create the configuration object for the ExpressCheckout component. The rootContainer value references the inner container div, not the outer hidden wrapper. The functionCallBackReady callback removes the hidden class from containerExpressCheckout once the component confirms that at least one digital wallet is available on the device. /// Initialize components and wire up tabs

Instantiate both components, then wire up the tab buttons. Clicking a tab updates the active style and calls updateConfig to swap the EmbeddedMethod component between card and ACH mode without reinitializing. The payment button calls payabliExec("pay") with the transaction details.

1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta charset="UTF-8">
5   <title>Payabli Integration</title>
6   <style>
7     .hidden { display: none; }
8     .divider {
9       display: flex;
10       gap: 0.5rem;
11       align-items: center;
12       margin: 16px 0;
13     }
14     .divider hr {
15       flex: 1;
16       border: none;
17       border-top: 1px solid #e5e5e5;
18     }
19     .divider small {
20       color: #6b7280;
21       white-space: nowrap;
22     }
23     .tabs {
24       display: flex;
25       border-bottom: 1px solid #e5e5e5;
26       margin-bottom: 20px;
27     }
28     .tab {
29       flex: 1;
30       padding: 12px 24px;
31       text-align: center;
32       cursor: pointer;
33       background: white;
34       border: none;
35       border-bottom: 2px solid transparent;
36       transition: all 0.2s ease;
37     }
38     .tab:hover {
39       color: #333;
40       background: #f8f9fa;
41     }
42     .tab.active {
43       color: #007bff;
44       border-bottom-color: #007bff;
45     }
46     #btn-pay {
47       background: #4f46e5;
48       color: white;
49       padding: 12px 24px;
50       border: none;
51       border-radius: 6px;
52       cursor: pointer;
53       margin-top: 16px;
54     }
55   </style>
56 </head>
57 <body>
58   <h4>Pay your order</h4>
59   <div id="containerExpressCheckout" class="hidden">
60     <div id="express-checkout-component"></div>
61     <div class="divider">
62       <hr />
63       <small>or pay with card or bank account</small>
64       <hr />
65     </div>
66   </div>
67   <div class="tabs">
68     <button class="tab active" data-method="card">Payment Card</button>
69     <button class="tab" data-method="ach">Bank Debit</button>
70   </div>
71   <div id="pay-component-card"></div>
72   <button id="btn-pay">Save Payment</button>
73 
74   <script src="https://embedded-component-sandbox.payabli.com/component.js" data-test></script>
75   <script>
76     const token = "API_TOKEN_HERE";
77     const entryPoint = "ENTRYPOINT_HERE";
78 
79     const payabliConfigCard = {
80       type: "methodEmbedded",
81       rootContainer: "pay-component-card",
82       defaultOpen: "card",
83       token: token,
84       entryPoint: entryPoint,
85       card: {
86         enabled: true,
87         amex: false,
88         discover: true,
89         visa: true,
90         mastercard: true,
91         inputs: {
92           cardHolderName: {
93             label: "NAME ON CARD",
94             placeholder: "",
95             floating: false,
96             size: 12,
97             row: 0,
98             order: 0
99           },
100           cardNumber: {
101             label: "CARD NUMBER",
102             placeholder: "1234 1234 1234 1234",
103             floating: false,
104             size: 6,
105             row: 1,
106             order: 0
107           },
108           cardExpirationDate: {
109             label: "EXPIRATION DATE",
110             placeholder: "MM/YY",
111             floating: false,
112             size: 6,
113             row: 1,
114             order: 1
115           },
116           cardCvv: {
117             label: "CVV/CVC",
118             placeholder: "CVV/CVC",
119             floating: false,
120             size: 6,
121             row: 2,
122             order: 0
123           },
124           cardZipcode: {
125             label: "ZIP/POSTAL CODE",
126             placeholder: "Zip/Postal Code",
127             floating: false,
128             size: 6,
129             row: 2,
130             order: 1,
131             country: ["us", "ca"]
132           }
133         }
134       },
135       ach: {
136         enabled: false
137       },
138       customerData: {
139         customerNumber: "00001",
140         firstName: "John",
141         lastName: "Doe",
142         billingEmail: "johndoe@email.com"
143       },
144       functionCallBackSuccess: function (response) {
145         alert("card success");
146         paycomponentCard.payabliExec("reinit");
147       },
148       functionCallBackReady: function (data) {},
149       functionCallBackError: function (errors) {
150         alert("Error!");
151         console.log(errors);
152       }
153     };
154 
155     const payabliConfigACH = {
156       type: "methodEmbedded",
157       entryPoint: entryPoint,
158       rootContainer: "pay-component-card",
159       defaultOpen: "ach",
160       token: token,
161       customerData: {
162         customerNumber: "00001",
163         firstName: "John",
164         lastName: "Doe",
165         billingEmail: "johndoe@email.com"
166       },
167       card: {
168         enabled: false
169       },
170       ach: {
171         enabled: true,
172         checking: true,
173         savings: true,
174         inputs: {
175           achAccountHolderName: {
176             label: "ACCOUNTHOLDER NAME",
177             floating: false,
178             size: 6,
179             row: 0,
180             order: 0
181           },
182           achAccountType: {
183             label: "ACCOUNT TYPE",
184             floating: false,
185             size: 6,
186             row: 0,
187             order: 1
188           },
189           achRouting: {
190             label: "ROUTING NUMBER",
191             floating: false,
192             size: 6,
193             row: 1,
194             order: 0,
195             confirm: true
196           },
197           achAccount: {
198             label: "ACCOUNT NUMBER",
199             floating: false,
200             size: 6,
201             row: 1,
202             order: 1,
203             confirm: true
204           }
205         }
206       },
207       functionCallBackSuccess: function (response) {
208         alert("ach");
209       },
210       functionCallBackError: function (errors) {
211         console.log(errors);
212       },
213       functionCallBackReady: function (data) {}
214     };
215 
216     const expressCheckoutConfig = {
217       token: token,
218       type: "expressCheckout",
219       entryPoint: entryPoint,
220       rootContainer: "express-checkout-component",
221       expressCheckout: {
222         amount: 100,
223         fee: 0.01,
224         currency: "USD",
225         supportedNetworks: ["visa"],
226         columns: 1,
227         applePay: {
228           enabled: true,
229           buttonStyle: "black-outline",
230           buttonType: "plain",
231           language: "en-US"
232         },
233         requiredShippingContactFields: true,
234         appearance: {
235           buttonHeight: 50,
236           buttonBorderRadius: 10,
237           padding: {
238             x: 10,
239             y: 10
240           }
241         }
242       },
243       customerData: {
244         customerNumber: "00001",
245         firstName: "John",
246         lastName: "Doe",
247         billingEmail: "johndoe@email.com"
248       },
249       functionCallBackReady: function (data) {
250         console.log("Express Checkout ready: ", data);
251         const container = document.querySelector("#containerExpressCheckout");
252         container.classList.remove("hidden");
253       },
254       functionCallBackSuccess: function (data) {
255         console.log("Express Checkout Success: ", data);
256       },
257       functionCallBackError: function (data) {
258         console.log("Express Checkout Error: ", data);
259       },
260       functionCallBackCancel: function (data) {
261         console.log("Express Checkout Cancel: ", data);
262       }
263     };
264 
265     const paycomponentCard = new PayabliComponent(payabliConfigCard);
266     new PayabliComponent(expressCheckoutConfig);
267 
268     document.querySelectorAll('.tab').forEach(tab => {
269       tab.addEventListener('click', function () {
270         document.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
271         this.classList.add('active');
272 
273         if (this.dataset.method === 'card') {
274           paycomponentCard.updateConfig(payabliConfigCard);
275         } else {
276           paycomponentCard.updateConfig(payabliConfigACH);
277         }
278       });
279     });
280 
281     document.getElementById("btn-pay").addEventListener("click", () => {
282       paycomponentCard.payabliExec("pay", {
283         paymentDetails: {
284           totalAmount: 100,
285           serviceFee: 0,
286           categories: [{
287             label: "payment",
288             amount: 100,
289             qty: 1
290           }]
291         }
292       });
293     });
294   </script>
295 </body>
296 </html>

See these related resources to help you get the most out of Payabli.

Prerequisites

Apple Pay overview - You must have at least one wallet service implemented before using Express Checkout
Google Pay™ overview - You must have at least one wallet service implemented before using Express Checkout

Usage

Configuration walkthrough

Process a payment

Create a subscription

Tokenize a payment method

Process and tokenize

Use cases

Process a payment

Create a subscription

Tokenize a payment method

Process and tokenize

Configuration reference

properties

properties

properties

properties

properties

properties

properties

properties

properties

properties

properties

Response

functionCallbackReady response

functionCallbackSuccess response

functionCallBackError response

properties

properties

functionCallBackCancel response

properties

Combine components

Combine components walkthrough

Related resources

Prerequisites

Related topics

`functionCallbackReady` response

`functionCallbackSuccess` response

`functionCallBackError` response

`functionCallBackCancel` response