Payment Element (Deferred Intent)

Overview

Payment Element is an integrated payment interface component that supports multiple payment methods (credit cards, debit cards, Apple Pay, Google Pay, etc.). It provides a unified interface to collect customer payment information, simplifying payment flow integration.

Payment Flow Diagram

┌─────────────────────────────────────────────────────────────┐
│  1. Page Load - Initialize UseePay SDK                      │
│     UseePay(publicKey) → elements(options)                  │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  2. Create and Mount Payment Element                        │
│     elements.create('payment', options)                     │
│     paymentElement.mount(domId)                             │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  3. ready Event Triggered                                   │
│     → Payment Element is Ready                              │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  4. Customer Fills Payment Information                      │
│     → Select payment method (card, Apple Pay, Google Pay)   │
│     → Fill required information                             │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  5. Customer Clicks Pay Button                              │
│     → Call elements.submit() to validate form               │
└────────────────────────┬────────────────────────────────────┘
                         ↓
         ┌───────────────┴───────────────┐
         │  Validation Passed?            │
         └───────┬───────────────┬───────┘
                 │ No             │ Yes
                 ↓               ↓
    ┌──────────────────┐  ┌──────────────────────┐
    │ Show validation  │  │ 6. Call backend API   │
    │ errors, let      │  │    Create payment     │
    │ customer correct │  │    intent, return     │
    └──────────────────┘  │    paymentIntentId    │
                          │    and clientSecret   │
                          └──────────┬───────────┘
                                     ↓
                          ┌──────────────────────┐
                          │ 7. Confirm Payment    │
                          │ useepay.confirmPayment│
                          └──────────┬───────────┘
                                     ↓
                  ┌──────────────────┴──────────────────┐
                  │  Payment Result                      │
                  └──────┬───────────────────┬──────────┘
                         │ Success            │ Failure
                         ↓                   ↓
              ┌──────────────────┐  ┌──────────────────┐
              │ 8a. Redirect to  │  │ 8b. Show error   │
              │     success page │  │     message, let │
              │                  │  │     customer retry│
              └──────────────────┘  └──────────────────┘

Quick Start

Step 1: Include SDK

Include the UseePay SDK in your HTML page:

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

If SDK fails to load, display a friendly error message to the user

Consider adding retry mechanism or fallback options

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 public keys in production environment.

Step 4: Create Elements Instance

Initialize Elements to manage the payment interface:

Creating Payment 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: `'card'` (credit/debit card), `'apple_pay'` (Apple Pay), `'google_pay'` (Google Pay), etc. If not provided, all supported payment methods will be displayed

paymentMethodTypes Examples:

Payment Element Options

Parameter	Type	Required	Description
`applePay`	Object	No	Apple Pay specific configuration options. Required when `mode` is `'subscription'`

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, please 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 the customer
`managementURL`	String	Yes	Management URL where customers 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, the billing item name displayed to the 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., 2 for every 2 months

Configuration Examples

Basic Configuration Example (One-time Payment)

Subscription Payment Configuration Example

When using mode: 'subscription', you must configure Apple Pay's recurring payment functionality:

Methods

mount(domId)

Mounts the payment element to a DOM element.

Parameters:

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

unmount()

Removes the payment element from the DOM.

update(options)

Dynamically updates the payment element's configuration options.

Parameters:

options (Object): Update options

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

Events

Payment Element emits events that you can listen to for handling user interactions.

ready

Triggered when the payment element is fully loaded and ready for interaction.

Event Parameters:

event (Object): Event object

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., ['card', 'google_pay']

elements.on('update-end')

Triggered when Elements update is complete.

elements.submit()

Submits and validates the payment form. This method must be called for validation before creating a payment intent.

Return Value:

Parameter	Type	Description
`selectedPaymentMethod`	String	The payment method selected by the customer (e.g., `'card'`, `'apple_pay'`, `'google_pay'`)
`error`	Object	Error information object, `null` if validation succeeds

error Object:

Parameter	Type	Description
`type`	String	Error type
`message`	String	Error message

Possible error.type Values:

Value	Description
`no_select_payment_method`	No payment method selected
`validation_error`	Form validation error (e.g., invalid card number, missing required fields)
`google_pay_cancel`	Google Pay payment was cancelled
`apple_pay_cancel`	Apple Pay payment was cancelled

useepay.confirmPayment()

Confirms the payment and completes the transaction.

Parameters:

Parameter	Type	Required	Description
`elements`	Elements	Yes	Elements instance
`paymentIntentId`	String	Yes	Payment intent ID returned from backend API
`clientSecret`	String	Yes	Client secret returned from backend API

Return Value:

Parameter	Type	Description
`paymentIntent`	Object	Payment intent object (when payment succeeds)
`error`	Object	Error information object (when payment fails)

Complete Payment Flow

Complete Payment Example

Complete Integration Example

Important Notes

Subscription Payments: When mode is 'subscription', you must provide the applePay configuration when creating the Payment Element.

Form Validation: Before creating a payment intent, always call elements.submit() for form validation.

Error Handling: Always check the error object in the return values of submit() and confirmPayment().

Security:

Never hardcode payment amounts on the client side

Always create payment intents on the server side

Use the correct public key for your environment

User Experience:

Display loading status during payment process

Provide clear error messages

Redirect to confirmation page after successful payment

Payment Element (Deferred Intent)

Overview#

Payment Flow Diagram#

Quick Start#

Step 1: Include SDK#

Step 2: Verify SDK Loading#

Step 3: Initialize SDK#

Step 4: Create Elements Instance#

Creating Payment Element#

Basic Setup#

Configuration Options#

Elements Instance Options#

Payment Element Options#

ApplePay Object#

recurringPaymentRequest Object#

regularBilling Object#

Configuration Examples#

Basic Configuration Example (One-time Payment)#

Subscription Payment Configuration Example#

Methods#

mount(domId)#

unmount()#

update(options)#

Events#

ready#

Elements Methods and Events#

elements.update(options)#

elements.on('update-end')#

elements.submit()#

useepay.confirmPayment()#

Complete Payment Flow#

Complete Payment Example#

Complete Integration Example#

Important Notes#

Overview

Payment Flow Diagram

Quick Start

Step 1: Include SDK

Step 2: Verify SDK Loading

Step 3: Initialize SDK

Step 4: Create Elements Instance

Creating Payment Element

Basic Setup

Configuration Options

Elements Instance Options

Payment Element Options

ApplePay Object

recurringPaymentRequest Object

regularBilling Object

Configuration Examples

Basic Configuration Example (One-time Payment)

Subscription Payment Configuration Example

Methods

mount(domId)

unmount()

update(options)

Events

ready

Elements Methods and Events

elements.update(options)

elements.on('update-end')

elements.submit()

useepay.confirmPayment()

Complete Payment Flow

Complete Payment Example

Complete Integration Example

Important Notes