UseePay Checkout Session 使用文档

产品图示

概述

Checkout Session 是 UseePay SDK 提供的一种简化的支付集成方式。通过预先在服务端创建 Checkout Session，前端只需使用 checkoutSessionId 和 clientSecret 即可快速集成支付功能，无需处理复杂的支付参数配置。

主要特点

简化集成：服务端创建 Session，前端只需传入 ID 和密钥

安全性高：敏感信息在服务端配置，前端只持有临时凭证

统一管理：支付配置、金额、货币等信息统一在服务端管理

快速开始

1. 引入 SDK

2. 初始化 UseePay

3. 初始化 Checkout

4. 创建支付元素并挂载

5. 加载操作并确认支付

完整流程图

流程说明

服务端创建 Session：商户服务端调用 UseePay API 创建 Checkout Session，获取 checkoutSessionId 和 clientSecret

前端初始化：前端使用可发布密钥初始化 SDK，并使用 Session 凭证初始化 Checkout

创建支付元素：调用 createPaymentElement() 创建支付表单组件

挂载到页面：将支付元素挂载到指定的 DOM 容器

加载操作对象：调用 loadActions() 获取支付操作方法

用户操作：用户在表单中填写支付信息（卡号、有效期等）

确认支付：调用 actions.confirm() 提交支付

3DS 验证（如需要）：SDK 自动处理 3D Secure 验证流程

返回结果：支付完成后返回结果，前端根据结果进行后续处理

API 参考

UseePay(apiKey, options?)

初始化 UseePay SDK 实例。

参数：

参数名	类型	必填	说明
`apiKey`	`string`	✅	可发布密钥，格式：`UseePay_PK_*` 或 `UseePay_PK_TEST_*`

返回值： UseePay 实例

示例：

useepay.initCheckout(options)

初始化 Checkout Session。

参数：

参数名	类型	必填	说明
`options`	`InitCheckoutOptions`	✅	Checkout 配置对象
`options.checkoutSessionId`	`string`	✅	Checkout Session ID，格式：`cs_xxxxxxxxxxxx`
`options.clientSecret`	`string`	✅	客户端密钥，格式：`cs_xxxxxxxxxxxx_xxxxxxxxxxxxxxx`

返回值： Checkout 实例

示例：

注意事项：

checkoutSessionId 和 clientSecret 必须从服务端获取

每个 Session 只能使用一次，支付完成后需重新创建

clientSecret 具有时效性，过期后需重新创建 Session

checkout.createPaymentElement()

返回值： PaymentElement 实例

示例：

注意事项：

每个 Checkout 实例只能创建一个 Payment Element

重复调用会抛出错误

创建后需要调用 mount() 方法才能显示

paymentElement.mount(domId)

将支付元素挂载到指定的 DOM 元素。

参数：

参数名	类型	必填	说明
`domId`	`string`	✅	DOM 元素的 ID（不含 `#` 前缀）

返回值： void

示例：

注意事项：

DOM 元素必须已存在于页面中

建议给容器设置合适的宽度（如 width: 60vw）

挂载后会自动加载支付表单

paymentElement.unmount()

卸载支付元素。

返回值： void

示例：

注意事项：

卸载后元素从 DOM 中移除

可以重新调用 mount() 再次挂载

checkout.loadActions()

加载支付操作对象。

返回值： Promise<LoadActionsResult>

LoadActionsResult 类型：

示例：

注意事项：

必须在创建支付元素后调用

返回的 actions 对象包含 confirm() 方法

建议在页面加载时就调用此方法

actions.confirm()

确认并提交支付。

返回值： Promise<{ session?: CheckoutSession; error?: Error }>

返回值说明：

字段	类型	说明
`session`	`object`	支付成功时返回的 Session 对象
`session.checkout_session_id`	`string`	Checkout Session ID
`session.payment_status`	`string`	支付状态：`'paid'`、`'un_paid'` 等
`session.payment_intent_id`	`string`	Payment Intent ID，用于追踪支付意图
`session.payment_intent_status`	`string`	Payment Intent 状态
`session.status`	`string`	Checkout Session 整体状态
`error`	`object`	支付失败时的错误信息
`error.message`	`string`	错误描述信息
`error.type`	`string`	错误类型（可选）

session 对象完整结构：

示例：

注意事项：

调用前确保用户已填写完整的支付信息

可能触发 3DS 验证，SDK 会自动处理

支付过程中不要重复调用此方法

使用注意事项

1. 安全性

✅ 必须使用 HTTPS：生产环境必须使用 HTTPS 协议

✅ 密钥管理：clientSecret 不要暴露在公开代码仓库中

✅ 服务端验证：支付完成后必须在服务端验证支付状态

2. 性能优化

提前加载 SDK 脚本，避免阻塞页面渲染

在页面加载时就调用 loadActions()，不要等到用户点击支付按钮

合理设置容器宽度，避免频繁重绘

3. 用户体验

在支付过程中显示加载状态，避免用户重复点击

提供清晰的错误提示信息

支付成功后及时跳转或显示成功页面

3DS 验证时不要关闭或刷新页面

4. 兼容性

Apple Pay：仅在 Safari 浏览器和支持的 iOS 设备上可用

Google Pay：需要用户登录 Google 账户

浏览器要求：建议使用现代浏览器（Chrome 90+, Safari 14+, Firefox 88+）

5. 调试建议

使用测试环境的 API Key（UseePay_PK_TEST_***）进行开发

在浏览器控制台查看 SDK 输出的日志信息

使用测试卡号进行测试（从 UseePay 文档获取）

6. 常见问题

Q: 每个 Checkout 实例可以创建多个 Payment Element 吗？
A: 不可以。每个 Checkout 实例只能创建一个 Payment Element。

Q: Session 可以重复使用吗？
A: 不可以。每个 Session 只能使用一次，支付完成后需要重新创建。

Q: 如何处理 3DS 验证？
A: SDK 会自动处理 3DS 验证流程，无需额外代码。

Q: 支付金额可以在前端修改吗？
A: 不可以。支付金额在服务端创建 Session 时确定，前端无法修改。

Checkout Session模式

UseePay Checkout Session 使用文档

产品图示

目录

概述

主要特点

快速开始

1. 引入 SDK

2. 初始化 UseePay

3. 初始化 Checkout

4. 创建支付元素并挂载

5. 加载操作并确认支付

完整流程图

流程说明

API 参考

UseePay(apiKey, options?)

useepay.initCheckout(options)

checkout.createPaymentElement()

paymentElement.mount(domId)

paymentElement.unmount()

checkout.loadActions()

actions.confirm()

使用注意事项

1. 安全性

2. 性能优化

3. 用户体验

4. 兼容性

5. 调试建议

6. 常见问题

Checkout Session模式

UseePay Checkout Session 使用文档#

产品图示#

目录#

概述#

主要特点#

快速开始#

1. 引入 SDK#

2. 初始化 UseePay#

3. 初始化 Checkout#

4. 创建支付元素并挂载#

5. 加载操作并确认支付#

完整流程图#

流程说明#

API 参考#

UseePay(apiKey, options?)#

useepay.initCheckout(options)#

checkout.createPaymentElement()#

paymentElement.mount(domId)#

paymentElement.unmount()#

checkout.loadActions()#

actions.confirm()#

使用注意事项#

1. 安全性#

2. 性能优化#

3. 用户体验#

4. 兼容性#

5. 调试建议#

6. 常见问题#

UseePay Checkout Session 使用文档

产品图示

目录

概述

主要特点

快速开始

1. 引入 SDK

2. 初始化 UseePay

3. 初始化 Checkout

4. 创建支付元素并挂载

5. 加载操作并确认支付

完整流程图

流程说明

API 参考

UseePay(apiKey, options?)

useepay.initCheckout(options)

checkout.createPaymentElement()

paymentElement.mount(domId)

paymentElement.unmount()

checkout.loadActions()

actions.confirm()

使用注意事项

1. 安全性

2. 性能优化

3. 用户体验

4. 兼容性

5. 调试建议

6. 常见问题