快速开始

日期： 2026-09-18

状态： 已发布（字段与路径以自动生成 OpenAPI 契约为准）

本文说明如何创建应用凭证并调用已发布的支付会话接口。商户工作台内置的隔离沙箱不会调用真实渠道；生产调用需要完成产品签约、应用启用、凭证激活和渠道绑定。

1. 创建应用与凭证

登录部署环境提供的 SmartPay 商户工作台，在“应用与凭证”创建应用。
创建签名凭证，安全保存只展示一次的 App ID、Key ID 与 App Secret，再激活凭证。
沙箱与生产应用、凭证和路由相互隔离。生产应用只有在相关支付产品获批并完成渠道配置后才可用。

2. 请求签名

所有 /open/v1 服务端 API 使用 HMAC v2。写操作必须携带 Idempotency-Key。签名必须覆盖实际发送的原始请求字节，详见签名与幂等。

3. 创建支付会话

text

POST /open/v1/checkout-sessions

json

{
  "outTradeNo": "ORDER_202609180001",
  "merchantId": "mch_01J...",
  "scene": "H5",
  "amountFen": 1000000,
  "currency": "CNY",
  "subject": "采购货款",
  "returnUrl": "https://merchant.example.com/pay/return"
}

returnUrl 必须预先登记在当前应用的回跳白名单中。会话有效期由服务端固定为 30 分钟；当前请求不支持 expiresIn。

响应返回 sessionId、orderId、状态、过期时间和与场景对应的 action。字段定义见自动生成 OpenAPI。

4. 拉起付款页面

H5、PC、APP、小程序和扫码场景使用各自的 action.type 与 action.payload。如使用托管页面，访问部署域名下的 /checkout/{sessionId}。门店静态码由商户工作台生成受管入口 /pay/{entryId}；不要由业务系统自行伪造 entryId。

5. 确认支付结果

前端回跳、SDK 回调和二维码扫描都不代表支付成功。最终状态只能由以下方式确认：

GET /open/v1/checkout-sessions/{sessionId}；
已验签的 payment.succeeded、payment.failed 或 payment.closed Webhook。

收到 UNKNOWN 时查询原会话并等待状态收敛，不要更换商户单号或幂等键创建第二笔订单。

6. 隔离沙箱

商户工作台“开发文档与沙箱”支持支付会话、退款及查询类模拟操作。模拟请求由 SmartPay 服务端校验并审计，但不调用真实支付渠道、不创建真实资金订单，也不能作为到账证据。

快速开始 ​

1. 创建应用与凭证 ​

2. 请求签名 ​

3. 创建支付会话 ​

4. 拉起付款页面 ​

5. 确认支付结果 ​