集成工作流
Checkout 的集成是一个涉及 客户端（前端）、商户服务端（后端） 和 支付平台 三方交互的过程。
为了保证数据的一致性与安全性，我们推荐遵循以下标准时序进行开发。
交互时序图
详细步骤解析
1. 创建会话 (Server-side)
交互始于商户后端。当用户准备结账时，您的后端需要调用 API 创建一个 Checkout Session。
- 商品构建：您可以传入
productId（引用商品库）或直接定义productData（即时构建一次性商品）。 - 元数据 (metadata)：强烈建议您传入一组键值对形式的元数据。
- 示例：
{"order_id": "ORD-2025001", "user_id": "u_123456"}。 - 作用：这组数据不会展示给付款用户，但会原样包含在后续的 Webhook 回调中，帮助您将支付结果与内部订单进行关联。
- 示例：
- 跳转地址：设置
successUrl，即支付成功后用户将返回的商户页面地址。
2. 获取 URL 并重定向
平台 API 响应成功后，会返回一个包含 paymentUrl 字段的 JSON 对象。
- 这个 URL 指向我们为您生成的安全托管收银台页面。
- 操作：商户后端将此 URL 返回给前端，前端通过
window.location.href或 HTTP 303 重定向将用户引导至该页面。
3. 用户支付
用户在托管页面上查看订单详情，连接钱包并完成支付。
- 平台会自动处理汇率换算、跨链路由及链上交互。
- 在此期间，用户停留在我们的域（Domain）下。
4. 支付成功跳转
当监测到链上交易确认后：
- 如果商户配置了
successUrl，系统会自动将用户重定向回该地址。 - 商户可在该页面展示“支付成功”的提示。
不要依赖跳转做履约
用户在被重定向之前可能会关闭或刷新页面。请勿仅凭用户返回您的网站就假定付款成功或完成订单。
5. 异步通知与履约 (Webhook)
支付成功的权威信号来自 Webhook。平台会向商户配置的 Webhook URL 发送 session.paid、session.completed 或相关支付成功事件。完整的通知事件列表请参考 Webhook 事件列表 →
回调数据包中将包含：
- 完整的会话信息：包括您在第 1 步传入的 metadata（内部订单号）。
- 链上数据：包括交易哈希 (TxHash)、支付币种、实际支付金额、网络 Gas 费等详细信息。
商户收到 Webhook 后，应校验签名并更新本地订单状态，完成最终履约（发货）。
下一步
了解了完整流程后，现在让我们通过 API 创建您的第一个 Checkout Session。