快速开始

读者：接入智付通开放支付接口的外部商户后端开发人员。

通用约定

响应包装（所有开放接口成功/失败统一）：

json

成功：{"code":"OK","message":"ok","data":{...}}
失败：{"code":"<错误码>","message":"<错误说明>","data":null}

金额：一律为分（int64）；币种仅 CNY；不允许小数。
时间：接口入参/出参均 RFC3339（如 2026-09-01T18:00:00+08:00）；X-Timestamp 为 Unix 秒。
编码：请求/响应 UTF-8；body 应用 application/json（签名用原始字节，勿美化重排）。
字符集：out_trade_no/out_refund_no 仅 [A-Za-z0-9._-]。

环境与域名：

环境	接口域名	收银台域名	说明
测试	`https://api.test.vipjhzf.cn`	`https://pay-test.h5.vipjhzf.cn`	测试商户 + 渠道小额实测
生产	`https://api.vipjhzf.cn`	`https://pay.h5.vipjhzf.cn`	商务开通后发放

（域名以商务交付为准，此处为占位示例。）

接入概览

你的后端 ──① 调创建接口（HMAC 签名）──▶ 智付通
你的后端 ◀──② 返回 payment_no + cashier_url ──┘
你的后端 ──▶ 你的 H5 前端：
   模式 A：跳转 cashier_url（智付通收银台页完成支付）
   模式 B：调 prepay 拿支付凭证，在你的页面内拉起（支付宝/微信 H5/扫码/微信内 JSAPI）
支付完成 ──▶ 智付通回调你的 notify_url（HMAC 签名）──▶ 你应答 2xx
不确定时 ──▶ 你主动查单兜底

两句话记住架构：

所有服务端接口都由你的后端调用（secret 不允许出现在浏览器）；
用户侧支付要么跳我们的收银台（模式 A），要么用凭证在你自己的页面拉起（模式 B）。

环境：https://<由商务提供>.vipjhzf.cn（接口域名与收银台域名 pay.h5.vipjhzf.cn 以商务交付为准）。金额单位一律为分（int64），币种仅 CNY。

总体接入时序

你的三步：①后端创建拿到单号与链接 → ②后端把链接/凭证交给你的页面 → ③后端收通知 + 查单兜底。渠道细节全部在平台侧，你只与平台交互。

接口总览

#	接口	方法	用途	幂等	主要错误
1	`/v1/open/payments`	POST	创建支付	同号同额原单	400/409/503
2	`/v1/open/payments/{out_trade_no}`	GET	查单(商户单号)	只读	404
3	`/v1/open/payments?payment_no=`	GET	查单(平台单号)	只读	404/400
4	`/v1/open/payments/{no}/prepay`	POST	凭证直出	资金安全；凭证以当次响应为准	400/409/503
5	`/v1/open/payments/{no}/refunds`	POST	退款(全额)	同号同额原单	400/409
—	`{notify_url}`	POST	回调外发	at-least-once	非2xx重试

最佳实践清单

out_trade_no 用业务订单号，永远不要复用；金额变化时换新号。
回调处理先验签 → 幂等去重 → 应答 2xx → 再做业务。
回调未达/超时的兜底是查单（不是等重试结束）。
每日终以自有单号集合逐笔查单对账（一期无批量接口，二期提供对账单）。
secret 泄露立即到管理后台重置（旧密钥 ≤1 分钟内失效——平台应用信息有 60s 缓存）。
微信内可用 wechat_jsapi 直出（sub_appid 模式）：先完成三项前置条件（服务商 AppID 绑定/支付授权目录/渠道应用ID 配置），openid 用你自有公众号 snsapi_base 网页授权获取。503 CHANNEL_SUB_APPID_MISSING = 渠道应用ID 未配置（找平台运营）；400 PARAM_INVALID 且 message 提示 openid 不属于该渠道应用ID = openid 与 appid 不同源（自查网页授权公众号）。
退款单号（out_refund_no）不要复用；退款结果以查单/payment.refunded 回调为准。

快速开始 ​

通用约定 ​

接入概览 ​

总体接入时序 ​