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: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: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: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.| 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.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.options (Object): Update optionsapplePay (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 (Object): Event object
Elements Methods and Events#
elements.update(options)#
Dynamically updates the Elements instance configuration.options (Object): Update optionsmode (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.| 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 |
| 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.| 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 |
| 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#
1.
Subscription Payments: When mode is 'subscription', you must provide the applePay configuration when creating the Payment Element.
2.
Form Validation: Before creating a payment intent, always call elements.submit() for form validation.
3.
Error Handling: Always check the error object in the return values of submit() and confirmPayment().
4.
Never hardcode payment amounts on the client side
Always create payment intents on the server side
Use the correct public key for your environment
5.
Display loading status during payment process
Provide clear error messages
Redirect to confirmation page after successful payment
