Express Checkout Element Documentation

Overview

The Express Checkout element provides a simplified payment experience, integrating Apple Pay, Google Pay, and other wallet-based express payment methods. It allows customers to quickly complete purchases using pre-filled shipping and payment information.

Complete Flow Diagram

┌─────────────────────────────────────────────────────────────┐
│  1. Page Load - Initialize UseePay SDK                      │
│     UseePay(publicKey) → elements(options)                  │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  2. Create and Mount Express Checkout Element               │
│     elements.create('expressCheckout', options)             │
│     expressCheckoutElement.mount(domId)                     │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  3. ready Event Triggered                                    │
│     → Check available payment methods (Apple Pay/Google Pay)│
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  4. Customer Clicks Express Payment Button                  │
│     → click event triggered (complete within 1 second)      │
│     → Optional: Dynamically update lineItems/shippingRates/ │
│       applePay                                              │
└────────────────────────┬────────────────────────────────────┘
                         ↓
         ┌───────────────┴───────────────┐
         │  Shipping Required?            │
         └───────┬───────────────┬───────┘
                 │ Yes            │ No
                 ↓               ↓
    ┌──────────────────────┐    │
    │ 5a. Customer Selects/ │    │
    │     Changes Address   │    │
    │ shippingAddressChange│    │
    │ (complete within 20s) │    │
    │ → Return shipping    │    │
    │   rates              │    │
    └──────────┬───────────┘    │
               ↓                │
    ┌──────────────────────┐    │
    │ 5b. Customer Selects  │    │
    │     Shipping Rate     │    │
    │ shippingRateChange   │    │
    │ (complete within 20s) │    │
    └──────────┬───────────┘    │
               └────────┬────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│  6. Customer Confirms Payment - confirm event triggered      │
│     → Get billingDetails and shippingAddress                │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  7. Call Backend API to Create Payment Intent               │
│     POST /api/create-payment-intent                         │
│     → Return paymentIntentId and clientSecret               │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  8. Confirm Payment                                          │
│     useepay.confirmPayment({ elements, paymentIntentId,     │
│                              clientSecret })                │
└────────────────────────┬────────────────────────────────────┘
                         ↓
         ┌───────────────┴───────────────┐
         │  Payment Result                │
         └───────┬───────────────┬───────┘
                 │ Success        │ Failure
                 ↓               ↓
    ┌──────────────────┐  ┌──────────────────┐
    │ 9a. Redirect to   │  │ 9b. Display Error │
    │     Success Page  │  │     Let Customer  │
    │                   │  │     Retry         │
    └──────────────────┘  └──────────────────┘

Key Time Requirements

Event	Timeout	Description
`click`	1 second	Must respond quickly, avoid time-consuming operations
`shippingAddressChange`	20 seconds	Can call API to calculate shipping costs
`shippingRateChange`	20 seconds	Can call API to update order information
`confirm`	Unlimited	Need to create payment intent and confirm payment

Quick Start

Step 1: Include SDK

Include the UseePay SDK in your HTML page:

The sdk url for the production environment has not been launched yet. Below is the address for the sandbox environment

Step 2: Verify SDK Loading

Before using the SDK, verify that it has loaded successfully:

Best Practices:

Check if SDK is loaded in window.onload or DOMContentLoaded event

Display a friendly error message to users if SDK fails to load

Consider adding retry mechanism or fallback option

Step 3: Initialize SDK

Initialize UseePay with your public key generated from the MC merchant dashboard:

Public Key Format:

Production Environment: Starts with UseePay_PK_ (e.g., UseePay_PK_1234567890abcdef...)

Test Environment: Starts with UseePay_PK_TEST_ (e.g., UseePay_PK_TEST_1234567890abcdef...)

⚠️ Important: Please obtain the correct public key from the MC management dashboard. Never use test keys in production environment.

Step 4: Create Elements Instance

Initialize Elements to manage the payment interface:

Creating Express Checkout Element

Basic Setup

Configuration Options

Elements Instance Options

When creating an Elements instance, you can configure the following options:

Parameter	Type	Required	Description
`mode`	String	Yes	Payment mode, options: `'payment'` (one-time payment) or `'subscription'` (subscription payment)
`amount`	Number	Yes	Payment amount (actual amount)
`currency`	String	Yes	Currency code (e.g., `'USD'`, `'EUR'`, `'CNY'`)
`paymentMethodTypes`	Array	No	Array of available payment method strings. Options include: `'google_pay'` (Google Pay), `'apple_pay'` (Apple Pay),`'link'` (Link), etc. If not provided, all supported payment methods will be displayed

ExpressCheckout Options

Parameter	Type	Required	Description
`business`	Object	No	Business information displayed during checkout
`business.name`	String	No	Business name displayed to customer
`shippingAddressRequired`	Boolean	No	Whether customer must provide shipping address. If set to `true`, you must provide valid `shippingRates` options in `create`, `click`, or `shippingAddressChange` event
`allowedShippingCountries`	Array	No	Array of allowed shipping country codes (e.g., `['US', 'CA']`)
`shippingRates`	Array	No	Shipping options available for customer selection
`lineItems`	Array	No	Order line items to display
`applePay`	Object	No	Apple Pay specific configuration options

ShippingRate Object

Parameter	Type	Required	Description
`id`	String	Yes	Unique identifier for the shipping method
`displayName`	String	Yes	Shipping method name displayed to customer
`amount`	Number	Yes	Shipping cost (actual amount)

LineItem Object

Parameter	Type	Required	Description
`name`	String	Yes	Name/description of the line item
`amount`	Number	Yes	Price (actual amount)

ApplePay Object

Apple Pay specific configuration for advanced features like subscription payments.

📖 Detailed Parameter Documentation
For detailed parameters and configuration for Apple Pay recurring payments, refer to Apple's official documentation:
Apple Pay on the Web - Recurring Payments

Parameter	Type	Required	Description
`recurringPaymentRequest`	Object	No	Recurring payment request configuration for subscription-type payments

recurringPaymentRequest Object

Parameter	Type	Required	Description
`paymentDescription`	String	Yes	Payment description explaining the purpose of this recurring payment to customer
`managementURL`	String	Yes	Management URL where customer can manage their subscription
`regularBilling`	Object	Yes	Regular billing configuration
`billingAgreement`	String	No	Billing agreement text

regularBilling Object

Parameter	Type	Required	Description
`amount`	Number	Yes	Recurring payment amount (actual amount)
`label`	String	Yes	Billing label, billing item name displayed to customer
`recurringPaymentStartDate`	Date	Yes	Recurring payment start date
`recurringPaymentEndDate`	Date	Yes	Recurring payment end date
`recurringPaymentIntervalUnit`	String	Yes	Recurring payment interval unit, options: `'year'`, `'month'`, `'day'`, `'hour'`, `'minute'`
`recurringPaymentIntervalCount`	Number	Yes	Recurring payment interval count, e.g., every 2 months = 2

Configuration Examples

Basic Configuration Example

Apple Pay Subscription Payment Configuration Example

When using mode: 'subscription', you can configure Apple Pay's recurring payment feature:

Methods

mount(domId)

Mounts the express checkout element to a DOM element.

Parameters:

domId (String): The ID of the DOM element where the component should be mounted

unmount()

Removes the express checkout element from the DOM.

update(options)

Dynamically updates the configuration options of the express checkout element.

Parameters:

options (Object): Update options

allowedShippingCountries (Array, optional): Array of allowed shipping country codes

shippingAddressRequired (Boolean, optional): Whether customer must provide shipping address

Elements Methods and Events

elements.update(options)

Dynamically updates the Elements instance configuration.

Parameters:

options (Object): Update options

mode (String, optional): Payment mode ('payment' or 'subscription')

amount (Number, optional): Payment amount

currency (String, optional): Currency code

paymentMethodTypes (Array, optional): Array of available payment method strings, e.g., ['google_pay']

elements.on('update-end')

Triggered when Elements update is complete.

Use Cases:

Confirm update completion after dynamically updating amount or currency

Execute subsequent operations after update completes

Debugging and logging

Express Checkout Events

The Express Checkout element emits multiple events that you can listen to for handling customer interactions.

ready

Triggered when the express checkout element is fully loaded and ready for interaction. This event returns information about currently available payment methods.

Event Parameters:

event (Object): Event object

availablePaymentMethods (Object): Available payment methods object, keys are payment method names, values are booleans

apple_pay (Boolean): Whether Apple Pay is available

google_pay (Boolean): Whether Google Pay is available

Other supported express payment methods...

click

Triggered when the express checkout button is clicked. This event handler must complete within 1 second, otherwise the payment flow may timeout.

⚠️ Important:

This event handler must call resolve() within 1 second, otherwise the payment flow may timeout

Avoid time-consuming operations (such as network requests) in this event

Event Parameters:

event (Object): Event object

elementType (String): Element type, value is 'expressCheckout'

expressPaymentType (String): Express payment type, possible values:

'apple_pay': Apple Pay

'google_pay': Google Pay

'link': Link

resolve(options): Call to continue payment flow

resolve Method Parameters:

options (Boolean | Object): Confirmation options

Pass true: Simple confirmation, continue with current configuration

Pass object: Update configuration then continue

lineItems (Array, optional): Updated line items array

shippingRates (Array, optional): Updated shipping rates array

applePay (Object, optional): Apple Pay specific configuration update

recurringPaymentRequest: Recurring payment request configuration (see ApplePay Object)

cancel

Triggered when customer cancels the express checkout flow.

confirm

Triggered when customer confirms payment in the express checkout flow. In this event, you need to first call your backend API to create a payment intent, then use the returned paymentIntentId and clientSecret to call confirmPayment to complete the payment.

Event Parameters:

event (Object): Event object

elementType (String): Element type, value is 'expressCheckout'

expressPaymentType (String): Express payment type, possible values:

'apple_pay': Apple Pay

'google_pay': Google Pay

'link': Link

billingDetails (BillingAddressType, optional): Billing information

shippingAddress (ShippingAddressType, optional): Shipping address information

shippingRate (ShippingRateType，optional)：Shipping rate information

BillingAddressType Object:

Property	Type	Description
`name`	String	Billing holder name
`email`	String	Email address
`phone`	String	Phone number
`address`	AddressDetail	Billing address details

ShippingAddressType Object:

Property	Type	Description
`name`	String	Recipient name
`address`	AddressDetail	Shipping address details

AddressDetail Object:

Property	Type	Description
`line1`	String	Address line 1 (street address)
`line2`	String	Address line 2 (apartment, suite, etc.)
`city`	String	City
`state`	String	State/Province
`postal_code`	String	Postal code
`country`	String	Country code (e.g., 'US')

ShippingRateType Object：

Property	Type	Description
`id`	String	Unique identifier for the shipping method
`displayName`	String	Shipping method name displayed to customer
`amount`	Number	Shipping cost (actual amount)

shippingAddressChange

Triggered when customer changes shipping address. Use this event to update shipping rates and line items based on the new address. This event handler must complete within 20 seconds, otherwise the payment flow may timeout.

⚠️ Important:

This event handler must call resolve() or reject() within 20 seconds, otherwise the payment flow may timeout

If calling backend API to calculate shipping costs, ensure API response time is fast enough

Event Parameters:

event (Object): Event object

elementType (String): Element type, value is 'expressCheckout'

address (Address): Customer's selected shipping address

resolve(options): Call to accept address change and update shipping options

reject(): Call to reject the address (e.g., if cannot ship to location)

Address Object:

Property	Type	Description
`city`	String	City
`state`	String	State/Province
`postal_code`	String	Postal code
`country`	String	Country code (e.g., 'US')

resolve Method Parameters:

options (Object): Update options

lineItems (Array): Updated line items array

shippingRates (Array): Updated shipping rates array

applePay (Object, optional): Apple Pay specific configuration update

recurringPaymentRequest: Recurring payment request configuration (see ApplePay Object)

shippingRateChange

Triggered when customer selects a different shipping rate. This event handler must complete within 20 seconds, otherwise the payment flow may timeout.

⚠️ Important:

This event handler must call resolve() within 20 seconds, otherwise the payment flow may timeout

If calling backend API to update order information, ensure API response time is fast enough

Event Parameters:

event (Object): Event object

elementType (String): Element type, value is 'expressCheckout'

shippingRate (ShippingRate): Customer's selected shipping rate

resolve(options): Call to confirm shipping rate change

ShippingRate Object:

Property	Type	Description
`id`	String	Unique identifier for the shipping method
`amount`	Number	Shipping cost (actual amount)
`displayName`	String	Shipping method display name

resolve Method Parameters:

options (Object, optional): Update options

lineItems (Array): Updated line items array

applePay (Object): Apple Pay specific configuration update

recurringPaymentRequest: Recurring payment request configuration (see ApplePay Object)

Express Checkout Element

Express Checkout Element Documentation#

Overview#

Complete Flow Diagram#

Key Time Requirements#

Quick Start#

Step 1: Include SDK#

Step 2: Verify SDK Loading#

Step 3: Initialize SDK#

Step 4: Create Elements Instance#

Creating Express Checkout Element#

Basic Setup#

Configuration Options#

Elements Instance Options#

ExpressCheckout Options#

ShippingRate Object#

LineItem Object#

ApplePay Object#

recurringPaymentRequest Object#

regularBilling Object#

Configuration Examples#

Basic Configuration Example#

Apple Pay Subscription Payment Configuration Example#

Methods#

mount(domId)#

unmount()#

update(options)#

Elements Methods and Events#

elements.update(options)#

elements.on('update-end')#

Express Checkout Events#

ready#

click#

cancel#

confirm#

shippingAddressChange#

shippingRateChange#

Express Checkout Element Documentation

Overview

Complete Flow Diagram

Key Time Requirements

Quick Start

Step 1: Include SDK

Step 2: Verify SDK Loading

Step 3: Initialize SDK

Step 4: Create Elements Instance

Creating Express Checkout Element

Basic Setup

Configuration Options

Elements Instance Options

ExpressCheckout Options

ShippingRate Object

LineItem Object

ApplePay Object

recurringPaymentRequest Object

regularBilling Object

Configuration Examples

Basic Configuration Example

Apple Pay Subscription Payment Configuration Example

Methods

mount(domId)

unmount()

update(options)

Elements Methods and Events

elements.update(options)

elements.on('update-end')

Express Checkout Events

ready

click

cancel

confirm

shippingAddressChange

shippingRateChange