银联-批量代收(代收协议)受理
1.修订记录
| 修订 |
日期 |
说明 |
作者 |
| V0.1 |
2020/7/15 |
新接口参数定义 |
宁华雄 |
| V0.2 |
2021/12/27 |
支持国密 |
王晶 |
2.接口说明
（1）场景说明
1、银联代收协议签约后，需要进行批量操作的，调此接口
（2）接口说明
1、批量代收-代收协议受理-V3.0版本
3.请求地址
4.请求参数说明
4.1 公共请求参数
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| method |
String(1,128) |
Y |
接口名称 固定值 ysepay.ds.batch.normal.protocol.accept |
| partner_id |
String(1,20) |
Y |
在银盛支付开设的服务商商户号，请联系客户经理提供 |
| timestamp |
String(1,19) |
Y |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" 示例值：2014-07-24 03:07:50 |
| charset |
String(1,10) |
Y |
商户网站使用的编码格式，如UTF-8、GBK、GB2312等，默认值 GBK |
| sign_type |
String(1,10) |
Y |
报文签名算法，RSA/SM |
| sign |
String(1,256) |
Y |
签名字符串，再用Base64编码 |
| version |
String(1,3) |
Y |
接口版本3.0 当前版本：3.0 |
| notify_url |
String(190) |
Y |
银盛支付服务器主动通知商户网站里指定的页面http路径。 |
| biz_content |
String |
Y |
业务请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递 |
4.2 业务请求参数
参数名biz_content,值为一个json格式对象，下面列表描述json对象的值
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| out_batch_no |
String(16,16) |
Y |
商户批次号,格式：S+15位唯一流水，建议格式：S+YYYYMMDD+XXXXXXX,所填写的日期信息必须为当天在内的前后一天只能由大小写英文字母、数字、下划线及横杠组成 示例值：S201703081234567 |
| shopdate |
String(8,8) |
Y |
商户系统的交易发生日期格式yyyyMMdd 示例值：20180525 |
| total_num |
String(1,4) |
Y |
代收总笔数,最大交易笔数不能超过2000笔 |
| total_amount |
Number(12，2) |
Y |
代收总金额。单位为：RMB YUAN。取值范围为[0.01，9999999999.99]，精确到小数点后两位。 |
| business_code |
String(1,10) |
Y |
业务代码 ，请联系银盛客户经理获取。注意：业务代码非固定值，不同到账方式需要传不同的业务代码 |
| merchant_usercode |
String(0,20) |
N |
商户主体(收款方)用户号，空时默认为合作方商户的用户号 |
| detail_data |
list |
Y |
代收详细数据，最多支持2000笔。Json数组格式，暂包括out_trade_no、amount、subject、protocol_no 示例值：样例7.1 |
4.3 代收列表 detail_data
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| out_trade_no |
String(1,32) |
Y |
商户系统生成的订单号,批次内唯一,只能由大小写英文字母、数字、下划线及横杠组成 |
| amount |
Number(10，2) |
Y |
代收金额。单位为：RMB Yuan。取值范围为[0.01，99999999.99]，精确到小数点后两位。 |
| subject |
String(1,500) |
Y |
订单备注 |
| protocol_no |
String(1,32) |
Y |
银盛内部协议号 |
5.响应参数说明
银盛支付对商户的请求数据处理完成后，会将处理的结果数据同步回执给商户。
请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
5.1 公共响应参数
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| sign |
String |
Y |
签名字符串，Base64编码 |
| ysepay_ds_batch_normal_protocol_accept_response |
String |
Y |
业务响应参数的集合，最大长度不限 |
5.2 业务响应参数
银盛支付对商户的短信验证码授权完成之后就会开始进行协议签约的处理，该同步返回指的是授权完成之后，银盛支付继续处理签约流程，授权接口会返回业务处理状态，如果短信验证码授权失败，那么会抛出异常。
请注意:银盛后期对返回参数保留扩展的权利，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| code |
String |
Y |
响应代码 |
| msg |
String |
Y |
响应代码描述 |
| out_batch_no |
String(16,16) |
Y |
商户批次号,格式：S+15位唯一流水，建议格式：S+YYYYMMDD+XXXXXXX 示例值：S201703081234567 |
| trade_status |
String（1，32） |
Y |
交易目前所处的状态。批次受理成功状态的值： BATCH_ACCEPT_SUCCESS示例值：附录9.2 |
| trade_status_description |
String（256) |
N |
状态描述，当trade_status为BATCH_ACCEPT_SUCCESS描述为受理成功，描述中文字符不长于128个字 |
| total_amount |
Number(12，2) |
Y |
总金额 |
| total_num |
String(1,4) |
Y |
总笔数 |
| batch_no |
String(1,30) |
Y |
批次流水号 |
6.异步返回参数说明
银盛支付在受理商户的协议签约请求，获取授权码请求，授权请求成功完成之后，会将协议签约的最终状态通过异步通知发送回给商户。
请注意:银盛后期对返回参数保留扩展的权利，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
| 参数 |
类型(字节长度） |
必填 |
参数说明 |
| out_batch_no |
String(16,16) |
Y |
商户批次号,格式：S+15位唯一流水，建议格式：S+YYYYMMDD+XXXXXXX |
| batch_no |
String(1，30) |
Y |
批次流水号 |
| trade_status |
String（1，32） |
Y |
交易目前所处的状态。状态的值：BATCH_TRADE_SUCCESS｜BATCH_TRADE_FAILURE示例值：附录9.2 |
| trade_status_description |
String（256) |
N |
状态描述，当trade_status为BATCH_TRADE_SUCCESS｜BATCH_TRADE_FAILUR时，该字段是批次处理成功或者失败的原因描述。该参数最长为128个汉字。 |
| total_amount |
Number(10，2) |
Y |
总金额 |
| total_num |
String(1,4) |
Y |
总笔数 |
| success_total_amount |
Number(10，2) |
Y |
成功总金额 |
| success_total_num |
String(1,6) |
Y |
成功总笔数 |
| fee |
Number(10，2) |
N |
参考手续费,单位为：RMB Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。 |
| batch_account_date |
String(1，10) |
N |
批次会计日期：日账单格式为yyyyMMdd 示例值：20160413 |
| notify_type |
String |
Y |
通知类型 固定值：ysepay.ds.batch.notify |
| notify_time |
String(19) |
Y |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" 示例值：2014-07-24 03:07:50 |
| sign_type |
String |
Y |
报文签名算法，交易请求时的签名类型RSA/SM |
| sign |
String |
Y |
签名字符串，Base64编码 |
7.样例
7.1 代收列表 detail_data
[{
"out_trade_no": "201703080768835",
"amount": "1.5",
"subject": "订单说明",
"protocol_no": "123456789"
}, ..]
8.附录
8.1 业务错误码
| 错误码 |
错误描述 |
解决方案 |
| ACQ.SYSTEM_ERROR |
系统错误 |
请调用查询接口查询订单状态 |
| ACQ.BUSINESS_TIMEOUT_ERROR |
业务超时 |
请调用查询接口查询订单状态 |
| ACQ.INVALID_PARAMETER |
参数无效 |
检查请求参数，修改后重新发起请求 |
| ACQ.SHOPDATE_VALID_FAILD |
商户日期获取失败 |
检查参数 |
| PARAM_ERROR |
参数错误 |
检查请求参数，修改后重新发起请求 |
| REPEAT_ORDER |
订单重复 |
该笔订单已受理,请使用新订单号发起请求 |
| RISK_ERROR |
风控检查异常 |
请检查风控是否有异常，然后再重新发起 |
| ROUTE_ERROR |
路由失败 |
请联系客服或市场技术支持人员 |
| ACCOUNT_ERROR |
账户扣款失败 |
请联系客服或市场技术支持人员 |
| FEE_ERROR |
计费失败 |
请联系客服或市场技术支持人员 |
| DEAL_ERROR |
处理失败 |
请重新发起代收受理请求 |
| ACQ.PROXY_CHECK_FAILD |
代理关系检查失败 |
比如委托关系不存在 |
| ACQ.PROXY_CHECK_PARAM |
代理关系参数验证失败 |
比如代理密码解密失败，或者代理密码与委托商户号没有同时传或者同时不传 |
8.2 协议状态
| 枚举名称 |
枚举说明 |
| BATCH_ACCEPT_SUCCESS |
批次受理成功 |
| BATCH_TRADE_SUCCESS |
批次交易处理完成 |
| BATCH_TRADE_FAILURE |
批次交易处理失败 |
| TRADE_SUCCESS |
明细交易成功 |
| TRADE_FAILURE |
明细交易失败 |
| DISHONOUR_SUCCESS |
明细退票成功 |