Payment Element 元素文档

概述

Payment Element 是一个集成的支付界面组件，支持多种支付方式（信用卡、借记卡、Apple Pay、Google Pay 等）。它提供了一个统一的界面来收集客户的支付信息，简化了支付流程的集成。

支付流程图

┌─────────────────────────────────────────────────────────────┐
│  1. 页面加载 - 初始化 UseePay SDK                            │
│     UseePay(publicKey) → elements(options)                  │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  2. 创建并挂载 Payment Element                               │
│     elements.create('payment', options)                     │
│     paymentElement.mount(domId)                             │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  3. ready 事件触发                                           │
│     → Payment Element 已准备就绪                             │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  4. 客户填写支付信息                                          │
│     → 选择支付方式（卡、Apple Pay、Google Pay 等）           │
│     → 填写必要信息                                           │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  5. 客户点击支付按钮                                          │
│     → 调用 elements.submit() 验证表单                        │
└────────────────────────┬────────────────────────────────────┘
                         ↓
         ┌───────────────┴───────────────┐
         │  验证是否通过？                 │
         └───────┬───────────────┬───────┘
                 │ 否             │ 是
                 ↓               ↓
    ┌──────────────────┐  ┌──────────────────────┐
    │ 显示验证错误      │  │ 6. 调用后端 API       │
    │ 让客户修正       │  │    创建支付意图        │
    └──────────────────┘  │    返回 paymentIntentId│
                          │    和 clientSecret    │
                          └──────────┬───────────┘
                                     ↓
                          ┌──────────────────────┐
                          │ 7. 确认支付           │
                          │ useepay.confirmPayment│
                          └──────────┬───────────┘
                                     ↓
                  ┌──────────────────┴──────────────────┐
                  │  支付结果                            │
                  └──────┬───────────────────┬──────────┘
                         │ 成功               │ 失败
                         ↓                   ↓
              ┌──────────────────┐  ┌──────────────────┐
              │ 8a. 重定向到      │  │ 8b. 显示错误信息  │
              │     成功页面      │  │     让客户重试    │
              └──────────────────┘  └──────────────────┘

快速开始

步骤 1：引入 SDK

在您的 HTML 页面中引入 UseePay SDK：

步骤 2：验证 SDK 加载

在使用 SDK 之前，验证 SDK 是否成功加载：

最佳实践：

在 window.onload 或 DOMContentLoaded 事件中检查 SDK 是否加载

如果 SDK 加载失败，向用户显示友好的错误提示

考虑添加重试机制或备用方案

步骤 3：初始化 SDK

使用您在 MC 商户后台生成的公钥初始化 UseePay：

公钥格式说明：

生产环境：UseePay_PK_ 开头（例如：UseePay_PK_1234567890abcdef...）

测试环境：UseePay_PK_TEST_ 开头（例如：UseePay_PK_TEST_1234567890abcdef...）

⚠️ 重要提示：请从 MC 管理后台获取正确的公钥，切勿在生产环境使用测试公钥。

步骤 4：创建 Elements 实例

初始化 Elements 来管理支付界面：

创建 Payment Element 元素

基础设置

配置选项

Elements 实例选项

在创建 Elements 实例时，可以配置以下选项：

参数	类型	必填	描述
`mode`	String	是	支付模式，可选值：`'payment'`（一次性支付）或 `'subscription'`（订阅支付）
`amount`	Number	是	支付金额（实际金额）
`currency`	String	是	货币代码（例如：`'USD'`、`'EUR'`、`'CNY'`）
`paymentMethodTypes`	Array	否	可用支付方式的字符串数组。可选值包括：`'card'`（信用卡/借记卡）、`'apple_pay'`（Apple Pay）、`'google_pay'`（Google Pay）等。如果不提供，将显示所有支持的支付方式

paymentMethodTypes 示例：

Payment Element 选项

参数	类型	必填	描述
`applePay`	Object	否	Apple Pay 特定配置选项。当 `mode` 为 `'subscription'` 时必须提供

ApplePay 对象

Apple Pay 特定配置，用于设置订阅支付等高级功能。

📖 详细参数说明
关于 Apple Pay 循环支付的详细参数和配置，请参考 Apple 官方文档：
Apple Pay on the Web - Recurring Payments

参数	类型	必填	描述
`recurringPaymentRequest`	Object	否	循环支付请求配置，用于订阅类型的支付

recurringPaymentRequest 对象

参数	类型	必填	描述
`paymentDescription`	String	是	支付描述，向客户说明此循环支付的用途
`managementURL`	String	是	管理 URL，客户可以在此 URL 管理其订阅
`regularBilling`	Object	是	常规账单配置
`billingAgreement`	String	否	账单协议文本

regularBilling 对象

参数	类型	必填	描述
`amount`	Number	是	循环支付金额（实际金额）
`label`	String	是	账单标签，向客户显示的账单项名称
`recurringPaymentStartDate`	Date	是	循环支付开始日期
`recurringPaymentEndDate`	Date	是	循环支付结束日期
`recurringPaymentIntervalUnit`	String	是	循环支付间隔单位，可选值：`'year'`、`'month'`、`'day'`、`'hour'`、`'minute'`
`recurringPaymentIntervalCount`	Number	是	循环支付间隔数量，例如：每 2 个月则为 2

配置示例

基础配置示例（一次性支付）

订阅支付配置示例

当使用 mode: 'subscription' 时，必须配置 Apple Pay 的循环支付功能：

方法

mount(domId)

将支付元素挂载到 DOM 元素。

参数：

domId (String)：组件应挂载到的 DOM 元素的 ID

unmount()

从 DOM 中移除支付元素。

update(options)

动态更新支付元素的配置选项。

参数：

options (Object)：更新选项

applePay (Object，可选)：Apple Pay 特定配置更新

事件

Payment Element 会发出事件，您可以监听这些事件来处理用户交互。

ready

当支付元素完全加载并准备好交互时触发。

事件参数：

event (Object)：事件对象

Elements 方法和事件

elements.update(options)

动态更新 Elements 实例的配置。

参数：

options (Object)：更新选项

mode (String，可选)：支付模式（'payment' 或 'subscription'）

amount (Number，可选)：支付金额

currency (String，可选)：货币代码

paymentMethodTypes (Array，可选)：可用支付方式的字符串数组，例如：['card', 'google_pay']

elements.on('update-end')

当 Elements 更新完成时触发。

elements.submit()

提交并验证支付表单。在创建支付意图之前，必须先调用此方法进行验证。

返回值：

参数	类型	描述
`selectedPaymentMethod`	String	客户选择的支付方式（例如：`'card'`、`'apple_pay'`、`'google_pay'`）
`error`	Object	错误信息对象，如果验证成功则为 `null`

error 对象：

参数	类型	描述
`type`	String	错误类型
`message`	String	错误消息

error.type 可能的值：

值	描述
`no_select_payment_method`	未选择支付方式
`validation_error`	表单验证错误（例如：卡号无效、必填字段缺失）
`google_pay_cancel`	Google Pay 支付被取消
`apple_pay_cancel`	Apple Pay 支付被取消

useepay.confirmPayment()

确认支付并完成交易。

参数：

参数	类型	必填	描述
`elements`	Elements	是	Elements 实例
`paymentIntentId`	String	是	从后端 API 返回的支付意图 ID
`clientSecret`	String	是	从后端 API 返回的客户端密钥

返回值：

参数	类型	描述
`paymentIntent`	Object	支付意图对象（支付成功时）
`error`	Object	错误信息对象（支付失败时）

完成支付流程

完整支付示例

完整集成示例

注意事项

订阅支付：当 mode 为 'subscription' 时，必须在创建 Payment Element 时提供 applePay 配置。

表单验证：在创建支付意图之前，务必先调用 elements.submit() 进行表单验证。

错误处理：始终检查 submit() 和 confirmPayment() 的返回值中的 error 对象。

安全性：

切勿在客户端硬编码支付金额

始终在服务器端创建支付意图

使用正确环境的公钥

用户体验：

在支付过程中显示加载状态

提供清晰的错误提示

支付成功后重定向到确认页面

内嵌订阅收银台（变更金额）测试中

Payment Element 元素文档#

概述#

支付流程图#

快速开始#

步骤 1：引入 SDK#

步骤 2：验证 SDK 加载#

步骤 3：初始化 SDK#

步骤 4：创建 Elements 实例#

创建 Payment Element 元素#

基础设置#

配置选项#

Elements 实例选项#

Payment Element 选项#

ApplePay 对象#

recurringPaymentRequest 对象#

regularBilling 对象#

配置示例#

基础配置示例（一次性支付）#

订阅支付配置示例#

方法#

mount(domId)#

unmount()#

update(options)#

事件#

ready#

Elements 方法和事件#

elements.update(options)#

elements.on('update-end')#

elements.submit()#

useepay.confirmPayment()#

完成支付流程#

完整支付示例#

完整集成示例#

注意事项#

Payment Element 元素文档

概述

支付流程图

快速开始

步骤 1：引入 SDK

步骤 2：验证 SDK 加载

步骤 3：初始化 SDK

步骤 4：创建 Elements 实例

创建 Payment Element 元素

基础设置

配置选项

Elements 实例选项

Payment Element 选项

ApplePay 对象

recurringPaymentRequest 对象

regularBilling 对象

配置示例

基础配置示例（一次性支付）

订阅支付配置示例

方法

mount(domId)

unmount()

update(options)

事件

ready

Elements 方法和事件

elements.update(options)

elements.on('update-end')

elements.submit()

useepay.confirmPayment()

完成支付流程

完整支付示例

完整集成示例

注意事项