调用说明 ¶

请求规范 ¶

请求发起要求 ¶

类型	描述
传输方式	采用`HTTP`/`HTTPS`传输
提交方式	`POST`
参数类型	`application/json`
响应类型	`application/json`
字符编码	`UTF-8`
签名算法	`MD5`/`HMAC_SHA256`/`SM3`

参数规范注意事项 ¶

如果未特殊说明，所有参数不要传输空字符串数据，否则有可能造成签名签名无法通过等一系列问题

参数	说明
交易金额	单位为元，保留两位小数。
时间参数	所有涉及时间参数均使用 `yyyy-MM-dd HH:mm:ss` 格式

公共请求参数 ¶

所有的接口如果未进行特殊说明，都需要携带公共参数，具体参数如下：

字段名	变量名	必填	类型	示例值	描述
商户号	appId	否	String	A5565221588	填写自己的商户号, 商户号不可超过32位
应用号	appId	否	String	A5565221588	填写自己的appId, 应用号不可超过32位
客户端ip	clientIp	否	String	127.0.0.1	支持V4和V6，部分支付方式要求必填，推荐所有情况都传输IP
请求时间	reqTime	是	String	2024-08-08 12:12:12	默认为当前时间，开启验证后需要保证与服务器时间误差在配置的范围内
签名值	sign	否	String	072695d112892e382a7093b81e6a52af	参数数据的签名值，开启验签选项后必传
随机数	nonceStr	否	String	d112892e382a7093	生产随机数用于签名

公共响应参数 ¶

WARNING

状态码返回0只代表受理业务成功，业务是否成功需要看具体业务的返回数据和对应通道官方文档流程说明，不为0表示受理失败，具体响应吗可以参考返回状态码

名称	字段	类型	示例值	描述
状态码	code	Integer	0	默认是0，非0表明请求失败，例如签名错误等
提示信息	msg	String		发生错误时会有数据返回
业务数据	data	Json对象		json格式数据，不同的接口返回结构不同，可以参考业务公共响应参数
签名	sign	String	sIV4zJVhZ4Uz	返回数据的签名值
响应时间	resTime	String	2024-08-08 12:12:12	数据响应的时间, 如果时间与请求时间相差5分钟以上，请排查网络和安全问题
追踪ID	traceId	String	sIV4zJVhZ4Uz	用于查询日志排查问题时进行快速定位

正常案例(业务成功) ¶

json

{
  "code" : 0,
  "msg" : "success",
  "data" : {
    "bizOrderNo" : "SDK_1744004534098",
    "orderNo" : "DEV_P2025040713421870000006",
    "status" : "progress",
    "payBody" : "weixin://wxpay/bizpayurl?pr=FwIhHn7z1"
  },
  "sign" : "0f5f56d8df0db335c21c5649028b6b91",
  "resTime" : "2025-04-07 13:42:18",
  "traceId" : "4sObqTTuNfQL"
}

请求失败 ¶

例如请求参数有问题等情况，通常不会有签名值

json

{
  "code": 10506,
  "msg": "验证参数错误\r\n网关支付类型不可为空\r\n",
  "traceId": "HdaNKw0yCPP2"
}

业务失败 ¶

json

{
  "msg": "未通过签名验证",
  "code": 20000,
  "sign": "12221593a23d64246f5b8bc75c13a1ce581fb764934e9a8ef3294eddda5ec6a2",
  "resTime": "2024-08-08 12:12:12",
  "traceId": "h12UXhTkPmt3"
}

回调和订阅消息接收 ¶

通知方式 ¶

参数	说明
请求方式	`POST`
请求类型	`application/json`
客户系统应答值	大写 `SUCCESS` 字符串为成功

通知规则 ¶

当满足下列通知时机时，系统会将支付订单状态变化通知到商户的接收地址上。商户需要接收处理该消息并返回应答。

如果收到客户系统的应答不符合规范或超时，支付网关会认为通知失败，并通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但不保证通知最终能成功。（通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h- 总计 24h4m）

公共参数格式 ¶

为公共响应参数的子类，具体参数如下：

名称	字段	类型	示例值	描述
通知类型	noticeType	String	0	只有订阅消息会有此值，回调类型的消息此值为空
商户号	appId	String	M5565221588
应用号	appId	String	A5565221588
提示信息	msg	String		发生错误时会有数据返回
业务数据	data	Json对象		json格式数据，不同的接口返回结构不同，可以参考业务公共响应参数
签名	sign	String	sIV4zJVhZ4Uz	返回数据的签名值
响应时间	resTime	String	2024-08-08 12:12:12	数据响应的时间, 如果时间与请求时间相差5分钟以上，请排查网络和安全问题
追踪ID	traceId	String	sIV4zJVhZ4Uz	用于查询日志排查问题时进行快速定位

示例 ¶

json

{
    "noticeType": "pay",
    "mchNo": "M1723635576766",
    "appId": "M8088873888246277",
    "code": 0,
    "msg": "success",
    "data": {
        "bizOrderNo": "20250221230917",
        "orderNo": "DEV_P2025022123091870000001",
        "title": "扫码支付",
        "allocation": false,
        "autoAllocation": false,
        "channel": "ali_pay",
        "method": "barcode",
        "amount": 0.01,
        "refundableBalance": 0.01,
        "status": "close",
        "refundStatus": "no_refund",
        "closeTime": "2025-02-21 23:40:00",
        "expiredTime": "2025-02-21 23:39:18",
        "errorMsg": "支付失败: 支付失败，获取顾客账户信息失败，请顾客刷新付款码后重新收款，如再次收款失败，请联系管理员处理。[SOUNDWAVE_PARSER_FAIL]"
    },
    "sign": "91ba428dc3a6ca17051d1835c8d24703cf2e10434acb337b0a43cc081f7fe45c",
    "resTime": "2025-04-10 23:45:42",
    "traceId": "BgSPIlOLsRBx"
}