目录
1.1. 接口列表及请求地址
|
对应接口 |
接口代码（transCode） |
请求地址 |
|
【个人会员实名及绑卡（申请）】 |
1010 |
|
|
【个人会员实名及绑卡（确认）】 |
1011 |
|
|
消费申请 |
2085 |
测试：http://116.228.64.55:28082/yst-service-api/tx/handle 生产：https://ibsapi.allinpay.com/yst-service-api/tx/handle
|
|
退款申请 |
2294 |
|
|
订单关闭 |
2295 |
|
|
查询车牌服务开通信息 |
4007 |
|
|
创建停车入场 |
4008 |
|
|
4009 |
||
|
订单状态查询 |
3001 |
|
|
订单详情查询 |
3002 |
|
|
终端信息管理 |
4001 |
|
|
对账文件下载 |
4002 |
测试：http://116.228.64.55:28082/yst-service-api/file/download 生产：https://ibsapi.allinpay.com/yst-service-api/file/download |
1.2. 公共报文
1.2.1. 公共请求参数
|
字段 |
字段类型 |
必填 |
字段名称 |
说明 |
|
appId |
String |
是 |
云商通二代分配的应用ID |
如上送服务商应用ID，验证服务商证书 |
|
spAppId |
String |
否 |
云商通二代分配的服务商应用ID |
|
|
transCode |
String |
是 |
接口代码 |
|
|
format |
String |
否 |
仅支持JSON |
json |
|
charset |
String |
是 |
请求使用的编码格式，utf-8 |
UTF-8 |
|
signType |
String |
是 |
商户生成签名字符串所使用的签名 算法类型 |
比如：SM3withSM2 |
|
sign |
String |
是 |
商户请求参数的签名串 |
|
|
transDate |
String |
是 |
发送请求的日期，格式"yyyyMMdd" |
20240202 |
|
transTime |
String |
是 |
请求时间 |
141333 |
|
version |
String |
是 |
调用的接口版本 |
1.0 |
|
bizData |
String |
是 |
请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档 |
1.2.2. 公共响应参数
|
字段 |
字段类型 |
必填 |
字段名称 |
说明 |
|
code |
String |
是 |
调用结果返回码 |
00000-成功 |
|
msg |
String |
是 |
调用结果返回码描述 |
|
|
sign |
String |
是 |
商户请求参数的签名串 |
|
|
bizData |
String |
是 |
返回参数的集合，最大长度不限，除公共参数外所有返回参数都必须放在这个参数中传递，具体参照各产品快速接入文档 |
1.3. 回调通知说明
1.3.1. 异步通知公共参数
|
字段 |
字段类型 |
必填 |
参数名称 |
说明 |
|
notifyTime |
Date |
是 |
通知时间 |
格式为yyyy-MM-dd HH:mm:ss |
|
notifyId |
String |
是 |
通知校验ID |
|
|
charset |
String |
是 |
编码格式 |
编码格式， utf-8 |
|
version |
String |
是 |
接口版本 |
调用的接口版本1.0 |
|
signType |
String |
是 |
签名类型 |
签名算法类型，如：SM3WithSM2 |
|
sign |
String |
是 |
签名 |
签名串 |
|
appId |
String |
是 |
应用ID |
分配给开发者的应用ID |
|
spAppId |
String |
否 |
云商通二代分配的服务商应用ID |
|
|
transCode |
String |
是 |
接口代码 |
与原交易接口代码一致 |
|
bizData |
String |
是 |
业务参数的集 |
通知参数的集合，最大长度不限，除公共参数外所有通知参数都必须放在这个参数中传递，具体参照各产品快速接入文档 |
1.3.2. 异步通知机制
1、订单类结果通知规则
（1）当后台通知地址返回http的状态为success时，则认为通知成功，将停止通知。
（2）对于交易时效非常高的场景，建议商户建立主动查询机制【查询订单状态】。
（3）订单后台通知条件：
|
订单类 |
通知条件 |
说明 |
|
消费 |
订单成功、订单失败 |
|
|
退款 |
订单成功、订单失败 |
2、通知重发规则
（1）同样的通知可能会多次发送给接收方系统。接收方系统必须能够正确处理重复的通知。
（2）后台通知交互时，如果接收方反馈给通知方的应答不符合规范或超时（链接保持5s），通知方服务器会不断重发通知，直到收到接收方正确的反馈或超过6小时。一般情况下，6小时以内完成7次通知（通知的间隔频率一般是：5s/15s/1m/10m/30m/1h/6h）,但通知方不保证通知最终一定能成功。
（3）在订单状态不明或者没有收到支付结果通知的情况下，建议接收方主动调用【交易结果查询】确认订单状态。
1.4. 验签机制/敏感信息加密说明
1.4.1 请求签名机制
1. 筛选并排序
获取所有请求参数，不包括字节类型参数，如文件、字节流，剔除sign、signType字段，剔除值为空的参数，并按照第一个字符的键值ASCII码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值ASCII码递增排序，以此类推。
2. 拼接
将排序后的参数与其对应值，组合成“参数=参数值”的格式，并且把这些参数用&字符连接起来，此时生成的字符串为待签名字符串。
3. 调用签名函数：使用各自语言对应的Sm2签名函数，传入待签名字符串、服务商或者客户私钥进行签名，并将结果转换为 base64 字符串，设置为请求 json 对象的 sign 属性。
举例：
- 原始报文：{"appId":"21762000921804636162","bizData":"{\"signNum\":\"jack20240524002\",\"reqTraceNum\":\"202505191948332591\",\"memberType\":\"2\",\"memberRole\":\"二级商户\"}","charset":"UTF-8","format":"json","signType":"SM3withSM2","spAppId":"","transCode":"1001","transDate":"20250519","transTime":"194834","version":"1.0"}
- 待签名字符串：appId=21762000921804636162&bizData={"signNum":"jack20240524002","reqTraceNum":"202505191948332591","memberType":"2","memberRole":"二级商户"}&charset=UTF-8&format=json&transCode=1001&transDate=20250519&transTime=194834&version=1.0
- 最终发送报文：{"appId":"21762000921804636162","bizData":"{\"signNum\":\"jack20240524002\",\"reqTraceNum\":\"202505191948332591\",\"memberType\":\"2\",\"memberRole\":\"二级商户\"}","charset":"UTF-8","format":"json","sign":"MEQCIFhIoouBRfjaVHxX9V0mt1KnHNNkAY5tOKa+DY5he6a0AiBivhk18sL4j67rpE5CtJFehUDUc+TJNhyPkD6cJHHuZw==","signType":"SM3withSM2","spAppId":"","transCode":"1001","transDate":"20250519","transTime":"194834","version":"1.0"}
响应验签举例：
- 原始报文：{"msg":"调用成功","code":"00000","sign":"MEMCIFw+ucRQocdWiuTBwkVjViY3PjT1WMjA+sTrHJTcZAE4Ah8nBOSV0VbQlcOjlFHv6ROSgybX2clMis2BKpy8dlmi","bizData":"{\"respTraceNum\":\"20250519194834100100243522\",\"respCode\":\"20003\",\"respMsg\":\"应用没有权限使用此接口\"}"}
- 待签名字符串：bizData={"respTraceNum":"20250519195301100100243535","respCode":"20003","respMsg":"应用没有权限使用此接口"}&code=00000&msg=调用成功
- 响应签名：MEMCIFw+ucRQocdWiuTBwkVjViY3PjT1WMjA+sTrHJTcZAE4Ah8nBOSV0VbQlcOjlFHv6ROSgybX2clMis2BKpy8dlmi
使用各语言的算法+通联公钥来验证响应签名 和 待签名字符串
推送验签具体
- 原始报文：{"charset":"utf-8","notifyTime":"2024-12-16 19:33:14","appId":"21866056167393533954","sign":"MEUCIQD7DL2/qSbHQoDBIsk75ci5UjXpvMiVJ+J491QJnR1IJQIgGblgrXHMQs86WLayLkzttxlnCmM3qYpXwT6GhWpNFVU=","signType":"SM3withSM2","notifyId":"12fae97a-d8fb-4c50-8de4-59f364a96ede","bizData":"{\"result\":\"1\",\"finishTime\":\"2024-12-16 18:51:55\",\"orderAmount\":\"1\",\"respTraceNum\":\"20241216185131208501574482\",\"reqTraceNum\":\"P202412166533222\",\"channelParamInfo\":\"{\\\"b2bChannelParamInfo\\\":{\\\"signature\\\":\\\"dcee1ab7013cce768bdd3ea21a134c73c67cf5ee\\\"}}\"}","transCode":"2085","version":"1.0"}
- 待签名字符串：appId=21866056167393533954&bizData={"result":"1","finishTime":"2024-12-16 18:51:55","orderAmount":"1","respTraceNum":"20241216185131208501574482","reqTraceNum":"P202412166533222","channelParamInfo":"{\"b2bChannelParamInfo\":{\"signature\":\"dcee1ab7013cce768bdd3ea21a134c73c67cf5ee\"}}"}&charset=utf-8¬ifyId=12fae97a-d8fb-4c50-8de4-59f364a96ede¬ifyTime=2024-12-16 19:33:14&transCode=2085&version=1.0
- 推送签名：MEUCIQD7DL2/qSbHQoDBIsk75ci5UjXpvMiVJ+J491QJnR1IJQIgGblgrXHMQs86WLayLkzttxlnCmM3qYpXwT6GhWpNFVU=
使用各语言的算法+通联公钥来验证推送签名和待签名字符串
1.4.2. 敏感信息加解密
客户端与服务端之间传递敏感信息，请使用SM4 对称加密算法进行加密后传输。
SM4加密：将传入的密钥（secretKey）的字节数组作为因子通过SHA1PRNG生产一个64位的随机源，构造出原始密钥，通过ECB模式对明文数据进行加密，加密后的字节码转为16进制大写输出。
1.4.3. 签名验签API服务
独立部署一个api服务，加解密调用此服务，方法见附件：
【签名验签API_V2】https://kdocs.cn/l/cnO6tubee5wq