OpenAPI 接口定义

本页由 docs/developer-portal/openapi/zhishoutong-open-api.json 自动生成，请勿手工编辑。重新生成：pnpm --filter @api-platform/developer-portal gen

智收通支付开放平台对客 API。所有 /open/v1 接口需 HMAC v2 签名（请求头 x-app-id / x-key-id / x-timestamp / x-nonce / x-signature），写操作必须携带 Idempotency-Key。金额一律为人民币分（整数）。平台为技术服务商：不持有资金、不开立支付账户、不从事清算。

创建支付会话

POST /open/v1/checkout-sessions

创建统一收银台会话。传 paymentProductCodes 时返回服务端筛选后的付款方式，由托管页选择后创建支付订单；兼容模式下直接返回按 scene 决定的 CheckoutAction。同一 Idempotency-Key 重复请求幂等返回首次结果；同 Key 不同报文将被拒绝。

参数

名称	位置	必填	说明
`Idempotency-Key`	header	是	幂等键：写操作必填。同 Key 同报文幂等返回；同 Key 不同报文返回 IDEMPOTENCY_CONFLICT。24 小时有效。
`x-app-id`	header	是	应用 ID。配套请求头：x-key-id（凭据）、x-timestamp（Unix 秒）、x-nonce（随机串）。
`x-signature`	header	是	HMAC v2 签名值（hex）。

请求体

字段	类型	必填	说明
`outTradeNo`	string	是	商户订单号，商户内唯一；重复创建幂等返回既有会话
`merchantId`	string	是	平台商户 ID
`storeId`	string	否	已归属当前商户的门店 ID
`scene`	枚举：`MINI_PROGRAM` / `APP` / `H5` / `PC` / `QRCODE`	是	收银台形态
`amountFen`	integer	是	金额（人民币分）
`currency`	枚举：`CNY`	是
`subject`	string	是	订单标题
`channelCode`	string	否	兼容模式的内部指定通道；新接入方应使用 paymentProductCodes，由 SmartPay 服务端完成路由
`paymentProductCodes`	array（枚举：`TENCENT_BUSINESS_PAY` / `JEEPAY_AGGREGATE` / `WECHAT_B2B_PAY`）	否	允许付款人选择的支付产品白名单；实际可用方式还会按商户绑定、场景、环境和适配器状态过滤
`returnUrl`	string	否	H5/PC 完成后的手动回跳地址；必须为 HTTPS，且其协议、域名和端口已在当前应用白名单中登记。回跳不代表支付成功
`allocationIntent`	object	否	分配意图快照；当前不代表已发布分账执行 API，只有签约产品明确支持时才使用
`allocationIntent.planCode`	string	是
`allocationIntent.receivers`	array（object）	是
`wechatPayer`	object	否	微信 JSAPI/小程序支付付款人标识。选择 WX_JSAPI 或 WX_LITE 时必传；只用于本次上游下单，不在收银台响应、Webhook 或业务 metadata 中返回。
`wechatPayer.openId`	string	是	付款人在当前直连商户或子商户 AppID 下的 openId，不得携带首尾空格。
`wechatPayer.scope`	枚举：`DIRECT` / `SUB_MERCHANT`	是	DIRECT 表示直连商户 openId；SUB_MERCHANT 表示服务商子商户 openId。
`metadata`	object（键值对）	否	业务透传字段，Webhook 原样带回

响应 200 — 会话创建成功

data 字段：

字段	类型	必填	说明
`sessionId`	string	是	平台会话号，cs_ 开头
`outTradeNo`	string	是
`merchantId`	string	是
`scene`	枚举：`MINI_PROGRAM` / `APP` / `H5` / `PC` / `QRCODE`	是
`amountFen`	integer	是
`currency`	枚举：`CNY`	是
`status`	枚举：`CREATED` / `PROCESSING` / `SUCCEEDED` / `CLOSED` / `EXPIRED`	是	会话状态机；SUCCEEDED/CLOSED/EXPIRED 为终态
`action`	object	否
`action.type`	枚举：`MINI_PROGRAM_LAUNCH` / `APP_H5` / `H5_URL` / `PC_H5` / `QRCODE_URL`	是	拉起动作类型，由 scene 决定
`action.payload`	object（键值对）	是	通道无关载荷（url / prepayId / qrcodeUrl 等）
`action.expiresAt`	string	是
`paymentMethods`	array（object）	否
`selectionRequired`	boolean	否	true 时付款人需先选择 paymentMethods 中的一项
`orderId`	string	否	平台订单号，po_ 开头
`orderStatus`	枚举：`CREATED` / `ACCEPTED` / `SUCCEEDED` / `FAILED` / `CLOSED` / `UNKNOWN`	否	订单状态机；UNKNOWN 表示通道结果待收敛，平台会主动反查
`paidAt`	string	否
`expiresAt`	string	是
`createdAt`	string	是

响应 400 — 业务错误

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

响应 401 — 认证失败（签名/时间戳/重放）

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

响应 429 — 配额或频率限制

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

查询支付会话

GET /open/v1/checkout-sessions/{sessionId}

查询会话与关联订单状态。终态以此接口或 Webhook 为准，前端回跳不可作为支付成功依据。

参数

名称	位置	必填	说明
`sessionId`	path	是	平台会话号，cs_ 开头
`x-app-id`	header	是	应用 ID。配套请求头：x-key-id（凭据）、x-timestamp（Unix 秒）、x-nonce（随机串）。
`x-signature`	header	是	HMAC v2 签名值（hex）。

响应 200 — 会话详情

data 字段：

字段	类型	必填	说明
`sessionId`	string	是	平台会话号，cs_ 开头
`outTradeNo`	string	是
`merchantId`	string	是
`scene`	枚举：`MINI_PROGRAM` / `APP` / `H5` / `PC` / `QRCODE`	是
`amountFen`	integer	是
`currency`	枚举：`CNY`	是
`status`	枚举：`CREATED` / `PROCESSING` / `SUCCEEDED` / `CLOSED` / `EXPIRED`	是	会话状态机；SUCCEEDED/CLOSED/EXPIRED 为终态
`action`	object	否
`action.type`	枚举：`MINI_PROGRAM_LAUNCH` / `APP_H5` / `H5_URL` / `PC_H5` / `QRCODE_URL`	是	拉起动作类型，由 scene 决定
`action.payload`	object（键值对）	是	通道无关载荷（url / prepayId / qrcodeUrl 等）
`action.expiresAt`	string	是
`paymentMethods`	array（object）	否
`selectionRequired`	boolean	否	true 时付款人需先选择 paymentMethods 中的一项
`orderId`	string	否	平台订单号，po_ 开头
`orderStatus`	枚举：`CREATED` / `ACCEPTED` / `SUCCEEDED` / `FAILED` / `CLOSED` / `UNKNOWN`	否	订单状态机；UNKNOWN 表示通道结果待收敛，平台会主动反查
`paidAt`	string	否
`expiresAt`	string	是
`createdAt`	string	是

响应 404 — 业务错误

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

发起微信付款码支付

POST /open/v1/terminal-payments

门店终端扫描付款人微信付款码后发起 WX_BAR 支付。调用应用必须获得 TERMINAL_PAYMENT_CREATE 权限，商户、门店、终端与 JeePay 聚合支付产品必须均已启用。authCode 是一次性敏感值，平台不存储、不记录、不回显。返回 UNKNOWN 时必须查询原订单，不得换单号重试。

参数

名称	位置	必填	说明
`Idempotency-Key`	header	是	幂等键：写操作必填。同 Key 同报文幂等返回；同 Key 不同报文返回 IDEMPOTENCY_CONFLICT。24 小时有效。
`x-app-id`	header	是	应用 ID。配套请求头：x-key-id（凭据）、x-timestamp（Unix 秒）、x-nonce（随机串）。
`x-signature`	header	是	HMAC v2 签名值（hex）。

请求体

字段	类型	必填	说明
`outTradeNo`	string	是	商户订单号，应用内唯一
`merchantId`	string	是	当前应用已绑定的平台商户 ID
`storeId`	string	是	归属当前商户的启用门店 ID
`terminalId`	string	是	归属当前门店的启用终端 ID
`amountFen`	integer	是	金额（人民币分）
`currency`	枚举：`CNY`	是
`subject`	string	是	订单标题
`authCode`	string	是	扫描获得的微信付款人一次性 18 位付款码；不得写入日志、数据库或重试队列

响应 200 — 付款码支付已受理

data 字段：

字段	类型	必填
`sessionId`	string	是
`orderId`	string	是
`outTradeNo`	string	是
`merchantId`	string	是
`storeId`	string	是
`terminalId`	string	是
`amountFen`	integer	是
`currency`	枚举：`CNY`	是
`status`	枚举：`PROCESSING`	是
`orderStatus`	枚举：`ACCEPTED` / `UNKNOWN`	是
`expiresAt`	string	是
`createdAt`	string	是

响应 400 — 业务错误

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

响应 401 — 认证失败（签名/时间戳/重放）

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

响应 429 — 配额或频率限制

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

创建退款

POST /open/v1/refunds

对 SUCCEEDED 订单发起退款。约束：订单支付后 180 天内；累计退款不超过订单金额；同一订单两次退款间隔不少于 1 分钟；最多 50 次。通道处理中返回 PROCESSING，终态经 Webhook 或查询接口获取。

参数

名称	位置	必填	说明
`Idempotency-Key`	header	是	幂等键：写操作必填。同 Key 同报文幂等返回；同 Key 不同报文返回 IDEMPOTENCY_CONFLICT。24 小时有效。
`x-app-id`	header	是	应用 ID。配套请求头：x-key-id（凭据）、x-timestamp（Unix 秒）、x-nonce（随机串）。
`x-signature`	header	是	HMAC v2 签名值（hex）。

请求体

字段	类型	必填	说明
`outRefundNo`	string	是	商户退款单号，商户内唯一；重复提交幂等返回
`orderId`	string	是	平台订单号，po_ 开头
`amountFen`	integer	是	退款金额（分），累计不得超过订单金额
`reason`	string	否

响应 200 — 退款受理

data 字段：

字段	类型	必填	说明
`refundId`	string	是	平台退款号，rf_ 开头
`outRefundNo`	string	是
`orderId`	string	是
`amountFen`	integer	是
`status`	枚举：`CREATED` / `PROCESSING` / `SUCCEEDED` / `FAILED`	是	SUCCEEDED/FAILED 为终态
`channelRefundId`	string	否
`failureCode`	string	否
`succeededAt`	string	否
`createdAt`	string	是

响应 400 — 业务错误

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

响应 429 — 配额或频率限制

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

查询退款

GET /open/v1/refunds/{refundId}

参数

名称	位置	必填	说明
`refundId`	path	是	平台退款号，rf_ 开头
`x-app-id`	header	是	应用 ID。配套请求头：x-key-id（凭据）、x-timestamp（Unix 秒）、x-nonce（随机串）。
`x-signature`	header	是	HMAC v2 签名值（hex）。

响应 200 — 退款详情

data 字段：

字段	类型	必填	说明
`refundId`	string	是	平台退款号，rf_ 开头
`outRefundNo`	string	是
`orderId`	string	是
`amountFen`	integer	是
`status`	枚举：`CREATED` / `PROCESSING` / `SUCCEEDED` / `FAILED`	是	SUCCEEDED/FAILED 为终态
`channelRefundId`	string	否
`failureCode`	string	否
`succeededAt`	string	否
`createdAt`	string	是

响应 404 — 业务错误

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

托管收银台页面

GET /checkout/{sessionId}

平台托管的付款人页面（免签名）：展示订单摘要、二维码/拉起入口，并轮询支付状态。不暴露商户与通道敏感信息。

参数

名称	位置	必填	说明
`sessionId`	path	是

响应 200 — HTML 页面

托管收银台状态轮询

GET /checkout/{sessionId}/status

付款人侧公开状态接口，仅返回脱敏状态字段。

参数

名称	位置	必填	说明
`sessionId`	path	是

响应 200 — 脱敏状态

字段	类型	必填	说明
`sessionId`	string	是
`subject`	string	是
`amountFen`	integer	是
`currency`	枚举：`CNY`	是
`scene`	枚举：`MINI_PROGRAM` / `APP` / `H5` / `PC` / `QRCODE`	是
`status`	枚举：`CREATED` / `PROCESSING` / `SUCCEEDED` / `CLOSED` / `EXPIRED`	是
`action`	object	否
`action.type`	枚举：`MINI_PROGRAM_LAUNCH` / `APP_H5` / `H5_URL` / `PC_H5` / `QRCODE_URL`	是	拉起动作类型，由 scene 决定
`action.payload`	object（键值对）	是	通道无关载荷（url / prepayId / qrcodeUrl 等）
`action.expiresAt`	string	是
`paymentMethods`	array（object）	否
`selectionRequired`	boolean	否
`returnUrl`	string	否
`expiresAt`	string	是
`qrDataUrl`	string	否	扫码场景下的 data URL；不含通道凭证

查询付款人可选支付方式

GET /checkout/{sessionId}/methods

只返回不含内部渠道号、渠道商户号和凭证的付款人安全字段。

参数

名称	位置	必填	说明
`sessionId`	path	是

响应 200 — 支付方式列表

字段	类型	必填	说明
`paymentMethods`	array（object）	是
`selectionRequired`	boolean	是

选择支付方式并创建支付订单

POST /checkout/{sessionId}/method-selection

以不透明 optionId 原子锁定服务端路由。同一方式重复提交幂等返回既有支付，不允许改选其他方式。

参数

名称	位置	必填	说明
`sessionId`	path	是

请求体

字段	类型	必填	说明
`optionId`	string	是

响应 200 — 刷新后的托管收银台状态

字段	类型	必填	说明
`sessionId`	string	是
`subject`	string	是
`amountFen`	integer	是
`currency`	枚举：`CNY`	是
`scene`	枚举：`MINI_PROGRAM` / `APP` / `H5` / `PC` / `QRCODE`	是
`status`	枚举：`CREATED` / `PROCESSING` / `SUCCEEDED` / `CLOSED` / `EXPIRED`	是
`action`	object	否
`action.type`	枚举：`MINI_PROGRAM_LAUNCH` / `APP_H5` / `H5_URL` / `PC_H5` / `QRCODE_URL`	是	拉起动作类型，由 scene 决定
`action.payload`	object（键值对）	是	通道无关载荷（url / prepayId / qrcodeUrl 等）
`action.expiresAt`	string	是
`paymentMethods`	array（object）	否
`selectionRequired`	boolean	否
`returnUrl`	string	否
`expiresAt`	string	是
`qrDataUrl`	string	否	扫码场景下的 data URL；不含通道凭证

响应 400 — 业务错误

字段	类型	必填	说明
`code`	string	是	机器可读错误码，如 REFUND_AMOUNT_EXCEEDED / IDEMPOTENCY_CONFLICT / QUOTA_EXCEEDED
`message`	string	是
`details`	array（object）	是
`traceId`	string	是

事件推送（平台 → 客户）

POST /{customer-webhook-url}

客户在控制台注册回调地址后，支付/退款终态事件将推送到该地址。请求头含 x-webhook-signature（HMAC-SHA256，密钥为注册时一次性展示的 secret）与 x-webhook-timestamp。客户应校验签名、以 eventId 去重、快速返回 2xx；失败将按指数退避重试 12 次/24 小时。

请求体

字段	类型	必填	说明
`eventId`	string	是	事件唯一 ID，客户端以此去重
`type`	枚举：`payment.succeeded` / `payment.failed` / `payment.closed` / `refund.succeeded` / `refund.failed`	是
`occurredAt`	string	是
`data`	object 或 object	是	payment.* 事件为 CheckoutSession；refund.* 事件为 Refund

响应 200 — 客户确认接收

OpenAPI 接口定义 ​

创建支付会话 ​

查询支付会话 ​

发起微信付款码支付 ​

创建退款 ​

查询退款 ​

托管收银台页面 ​

托管收银台状态轮询 ​

查询付款人可选支付方式 ​

选择支付方式并创建支付订单 ​

事件推送（平台 → 客户） ​

OpenAPI 接口定义

创建支付会话

查询支付会话

发起微信付款码支付

创建退款

查询退款

托管收银台页面

托管收银台状态轮询

查询付款人可选支付方式

选择支付方式并创建支付订单

事件推送（平台 → 客户）