线上分账系统接口
1.修订记录
修订 |
日期 |
说明 |
作者 |
V0.1 |
2017/11/28 |
新接口参数定义 |
黄月巧 |
V0.2 |
2018/4/11 |
新加原始交易收款方商户号,删除机构号参数使从银盛获取 |
黄月巧 |
V0.3 |
2018/4/12 |
新加通知地址、查询接口与异步通知接口,删除代理商编号 |
黄月巧 |
V0.4 |
2018/9/3 |
修改明细返回字段division_mer_info->detailResults |
陈宋东 |
V0.5 |
2018/10/12 |
增加is_chargeFee参数说明 |
郭勇 |
V0.6 |
2019/05/30 |
将登记和查询返回码拆分开,去除无用分账登记返回码0001 |
陈宋东 |
V0.7 |
2021/12/27 |
支持国密 |
王晶 |
2.接口说明
(1)场景说明
1、对于需要把一个账户的钱分给其它对应的相关的商户,调用此接口
2、多于用一个订单里有多个收款方,或合作商户的场景
3、如景点,园区收款方和里面的具体项目为不同的收款方,卖出一张票时,可以分给两方
(2)接口说明
1、线上分账系统接口-V3.0版本
3.请求地址
4.参数说明
4.1公共请求参数
参数 |
类型(字节长度) |
必填 |
参数说明 |
method |
String(1,128) |
Y |
接口名称 固定值 分账登记:ysepay.single.division.online.accept 分账查询:ysepay.single.division.online.query 分账异步通知:无 |
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编码 |
notify_url |
String(190) |
Y |
银盛支付服务器主动通知商户网站里指定的页面http路径。 |
version |
String(1,3) |
Y |
接口版本3.0 当前版本:3.0 |
biz_content |
String |
Y |
业务请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递 |
4.2 公共响应参数
参数 |
类型(字节长度) |
必填 |
参数说明 |
sign |
String |
Y |
签名字符串,Base64编码 |
*_response |
String |
Y |
* 为占位值,字段名实际值是请求参数method替换所有点[.]为下划线后的值。son格式对象, 业务响应参数集合,最大长度不限。 示列值:开放接口调用规则 |
5.业务参数
5.1 分账登记请求
5.1.1 分账登记请求参数
参数名biz_content,值为一个json格式对象,下面列表描述json对象的值
参数 |
类型(字节长度) |
必填 |
参数说明 |
out_batch_no |
String(0,16) |
N |
商户批次号,格式:(S|F)+15位唯一流水,建议格式:S+YYYYMMDD+XXXXXXX.F表示代付,S表示代收。单笔交易可空,批量交易时必写 |
out_trade_no |
String(1,32) |
Y |
商户系统生成的订单号 |
payee_usercode |
String(1,20) |
Y |
主商户号(原交易收款方) |
total_amount |
Number(18, 2) |
Y |
原订单交易金额,20长度位,保留2位小数 |
sys_flag |
String(0,2) |
N |
系统标志 DD:订单交易,DS:代收交易,默认是DD,订单交易 |
is_divistion |
String(2,2) |
Y |
原订单是否参与分账01:是,02否 |
is_again_division |
String(1,1) |
Y |
是否重新分账Y:是,N:否 |
division_mode |
String(2,2) |
Y |
分账模式01 :比例,02:金额 |
div_list |
List |
Y |
分账明细,包含division_mer_usercode, div_amount, div_ratio, is_chargeFee等4个属性,参与分账时不可以空,明细中的是否必填按照分账来描述 |
5.1.2 分账明细 div_list
参数 |
类型(字节长度) |
必填 |
参数说明 |
division_mer_usercode |
String(1,20) |
Y |
分账商户号 |
div_amount |
number(18, 2) |
N |
分账金额 |
div_ratio |
number(1, 4) |
N |
分账比例,divMode=01时必填,小数格式,最小长度1位,最大4位小数位(例:0.2365), 分账比例之和必须为1 |
is_chargeFee |
String(2,2) |
Y |
是否收取手续费(01:是,02否)若配置手续费收支分离,该参数配置的手续费承担方不生效 |
5.1.3 分账登记响应参数
银盛支付对商户的请求数据处理完成后,会将处理的结果数据同步回执给商户。
请注意:银盛后期会对返回参数保留扩展的权力,扩展方式为新增参数但不会删除参数,请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
参数 |
类型(字节长度) |
必填 |
参数说明 |
returnCode |
String(1,5) |
Y |
返回码 DIVISION_ACCEPT |
retrunInfo |
String(1,5) |
Y |
返回说明 分账受理中 |
code |
String(1,5) |
Y |
返回码10000 |
msg |
String(1,10) |
Y |
返回说明 Success |
5.2 分账查询接口
5.2.1 分账查询请求参数
参数名biz_content,值为一个json格式对象,下面列表描述json对象的值
参数 |
类型(字节长度) |
必填 |
参数说明 |
src_usercode |
String(1,20) |
Y |
原交易发起方 |
out_trade_no |
String(1,32) |
Y |
商户系统生成的订单号(原交易订单号 |
out_batch_no |
String(0,16) |
N |
商户批次号,格式:(S\ |
F)+15位唯一流水,建议格式:S+YYYYMMDD+XXXXXXX.F表示代付,S表示代收。单笔交易可空,批量交易时必写 |
sys_flag |
String(0,2) |
N |
系统标志 DD:订单交易,DS:代收交易,默认是DD,订单交易 |
5.2.2 分账查询响应参数
银盛支付对商户的请求数据处理完成后,会将处理的结果数据同步回执给商户。
请注意:银盛后期会对返回参数保留扩展的权力,扩展方式为新增参数但不会删除参数,请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
参数 |
类型(字节长度) |
必填 |
参数说明 |
code |
String(1,5) |
Y |
返回码 10000 |
msg |
String(1,10) |
Y |
返回说明 Success |
src_usercode |
String(1,20) |
Y |
发起方商户号 |
trade_date |
String(8,8) |
Y |
交易日期 |
out_trade_no |
String(1,32) |
Y |
商户系统生成的订单号 |
out_batch_no |
String(0,16) |
Y |
原交易批次号 |
division_mode |
String(2,2) |
Y |
分账模式01 :比例,02:金额 |
total_amount |
Number(18, 2) |
Y |
原订单交易金额,20长度位,保留2位小数,登记状态或分账失败没有金额返回 |
fee |
Number(18, 2) |
N |
原订单手续费,登记状态或分账失败没有金额返回 |
fee_payer |
String(1,20) |
N |
手续费承担方 |
division_status |
String(1,20) |
Y |
分账状态 示例值:8.1.2 |
division_status_code |
String(1,20) |
Y |
分账状态码 |
updatetime |
String(0,8) |
Y |
更新时间 |
note |
String(1,200) |
Y |
备注 |
detailResults |
List |
Y |
分账信息,包括分账商户号,分账金额两个域 |
5.2.3 分账列表 detailResults
参数 |
类型(字节长度) |
必填 |
参数说明 |
division_mer_usercode |
String(1,20) |
Y |
分账商户号 |
division_amount |
Number(18, 2) |
Y |
分账金额,20长度位,保留2位小数 |
5.3 分账异步通知参数
银盛支付对商户的请求数据处理完成后,会将处理的结果数据通过服务器主动通知的方式通知给商户网站。这些处理结果数据就是服务器异步通知参数。
请注意:银盛后期会对返回参数保留扩展的权力,扩展方式为新增参数但不会删除参数,请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。
参数 |
类型(字节长度) |
必填 |
参数说明 |
trade_date |
String(8,8) |
Y |
交易日期 |
src_usercode |
String(1,20) |
Y |
发起方商户号 |
out_trade_no |
String(1,32) |
Y |
商户系统生成的订单号 |
out_batch_no |
String(0,16) |
Y |
原交易批次号 |
division_mode |
String(2,2) |
Y |
分账模式01 :比例,02:金额 |
total_amount |
Number(18, 2) |
N |
原订单交易金额,20长度位,保留2位小数,登记状态或分账失败没有金额返回 |
fee |
Number(18, 2) |
N |
原手续费,登记状态或分账失败没有手续费金额返回 |
fee_payer |
String(1,20) |
N |
手续费承担方 |
division_status |
String(1,20) |
Y |
分账状态 |
division_status_code |
String(1,20) |
Y |
分账状态码 |
update_time |
String(1,8) |
Y |
更新时间 |
note |
String(0,200) |
N |
备注 |
detailResults |
List |
Y |
分账信息, 是一个JSON格式的字符串 |
notify_type |
String |
Y |
通知类型 固定值: |
notify_time |
String(19) |
Y |
发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" 示例值:2014-07-24 03:07:50 |
sign_type |
String |
Y |
报文签名算法 默认值 RSA |
sign |
String |
Y |
签名字符串,Base64编码 |
5.3.1 分账明细 detailResults
参数 |
类型(字节长度) |
必填 |
参数说明 |
division_mer_usercode |
String(1,20) |
Y |
分账商户号 |
division_amount |
Number(18, 2) |
Y |
分账金额,20长度位,保留2位小数 |
6.样例
6.1sdk调用示例
- 银盛将与服务端交互的接口封装在开发工具包(SDK)中,开发者无需自行实现同服务端交互的复杂逻辑,直接将SDK导入自己的工程后,通过sdk示例代码实现同银盛服务端的交互
线上分账登记
OnlineReqDataVo req = new OnlineReqDataVo();
String reqUrl = "https://commonapi.ysepay.com/gateway.do";
String privateKeyFilePath = "D:\\opensdk\\hyfz_test2.pfx";
String publicKeyFilePath = "D:\\opensdk\\businessgate.cer";
String privateKeyPassworde = "123456";
String notifyUrl = "http://api.test.ysepay.net/atinterface/receive_return.htm";
req.setNotifyUrl(notifyUrl);
req.setPartnerId("hyfz_test2");
req.setReqUrl(reqUrl);
req.setPrivateKeyFilePath(privateKeyFilePath);
req.setPrivateKeyPassword(privateKeyPassworde);
req.setYsPublicKeyFilePath(publicKeyFilePath);
Map<String, Object> bizContent = new HashMap<>();
bizContent.put("out_trade_no", "20211012175144035102000788376200");
bizContent.put("payee_usercode", "hyfz_test2");
bizContent.put("total_amount", "0.10");
bizContent.put("sys_flag", "DD");
bizContent.put("is_divistion", "01");
bizContent.put("is_again_division", "N");
bizContent.put("division_mode", "01");
JSONArray divList = new JSONArray();
JSONObject divObject = new JSONObject();
divObject.put("division_mer_usercode","hyfz_test2");
divObject.put("div_ratio","0.90");
divObject.put("is_chargeFee","02");
divList.add(divObject);
divObject = new JSONObject();
divObject.put("division_mer_usercode","y2110091506590197537");
divObject.put("div_ratio","0.10");
divObject.put("is_chargeFee","01");
divList.add(divObject);
bizContent.put("div_list", divList);
req.setParamData(bizContent);
String result = null;
try{
logger.info("线上分账登记调用sdk接口addScanMerc请求入参为:"+ JSONObject.toJSONString(req));
result = MercFundApi.divisionOnlineAccept(req);
}catch (Exception e){
logger.info("线上分账登记接口失败:"+ e.getMessage());
}
线上分账查询
OnlineReqDataVo req = new OnlineReqDataVo();
String reqUrl = "https://commonapi.ysepay.com/gateway.do";
String privateKeyFilePath = "D:\\opensdk\\hyfz_test2.pfx";
String publicKeyFilePath = "D:\\opensdk\\businessgate.cer";
String privateKeyPassworde = "123456";
String notifyUrl = "http://api.test.ysepay.net/atinterface/receive_return.htm";
req.setNotifyUrl(notifyUrl);
req.setPartnerId("hyfz_test2");
req.setReqUrl(reqUrl);
req.setPrivateKeyFilePath(privateKeyFilePath);
req.setPrivateKeyPassword(privateKeyPassworde);
req.setYsPublicKeyFilePath(publicKeyFilePath);
Map<String, Object> bizContent = new HashMap<>();
bizContent.put("src_usercode", "hyfz_test2");
bizContent.put("out_trade_no", "20211012175144035102000788376200");
bizContent.put("sys_flag", "DD");
req.setParamData(bizContent);
String result = null;
try{
logger.info("线上分账查询调用sdk接口addScanMerc请求入参为:"+ JSONObject.toJSONString(req));
result = MercFundApi.divisionOnlineQuery(req);
}catch (Exception e){
logger.info("线上分账查询接口失败:"+ e.getMessage());
}
6.2 API接口代码示例
- 需要开发者自己封装调用逻辑,实现调用银盛api接口同银盛服务端交互,该示例没有加签验签及发送http请求代码,需自行下载demo查看。
线上分账登记
public static void main(String[] args) {
Map<String, String> mapData = new HashMap<>();
mapData.put("partner_id", "hyfz_test2");
mapData.put("method", "ysepay.single.division.online.accept");
mapData.put("timestamp", DateUtil.getDateNow());
mapData.put("sign_type", "RSA");
mapData.put("charset", "utf-8");
mapData.put("version", "3.0");
mapData.put("notify_url","http://127.0.0.1");
JSONObject json = new JSONObject();
json.put("out_trade_no", "20210722174831981103602311553304");
json.put("payee_usercode","hyfz_test2");
json.put("total_amount","0.01");
json.put("refund_reason","分账登记测试");
json.put("is_divistion", "02");
json.put("is_again_division","N");
json.put("division_mode","01");
JSONArray divList = new JSONArray();
JSONObject divObject = new JSONObject();
divObject.put("division_mer_usercode","hyfz_test2");
divObject.put("div_ratio","0.90");
divObject.put("is_chargeFee","02");
divList.add(divObject);
divObject = new JSONObject();
divObject.put("division_mer_usercode","y2110091506590197537");
divObject.put("div_ratio","0.10");
divObject.put("is_chargeFee","01");
divList.add(divObject);
json.put("div_list", divList);
mapData.put("biz_content",json.toString());
try{
String sign = YsPaySignUtils.sign(mapData);
mapData.put("sign",sign);
} catch (Exception e){
log.info("签名异常:"+e);
}
log.info("请求报文:"+ CommonUtil.mapToString(mapData));
String result = HttpRequest.sendPost("https://commonapi.ysepay.com/gateway.do",CommonUtil.mapToString(mapData));
log.info("接口回执:"+result);
boolean resultVerify = false;
try{
resultVerify = YsPaySignUtils.resultVerify(result,"ysepay_single_division_online_accept_response");
} catch (Exception e){
log.info("验签异常:"+e);
}
if(!resultVerify){
log.info("验签失败");
}
}
线上分账查询
public static void main(String[] args) {
Map<String, String> mapData = new HashMap<>();
mapData.put("partner_id", "hyfz_test2");
mapData.put("method","ysepay.single.division.online.query");
mapData.put("timestamp", DateUtil.getDateNow());
mapData.put("sign_type", "RSA");
mapData.put("charset", "utf-8");
mapData.put("version", "3.0");
mapData.put("notify_url","http://127.0.0.1");
JSONObject json = new JSONObject();
json.put("out_trade_no", "20210722174831981103602311553304");
json.put("src_usercode","hyfz_test2");
mapData.put("biz_content",json.toString());
try{
String sign = YsPaySignUtils.sign(mapData);
mapData.put("sign",sign);
} catch (Exception e){
log.info("签名异常:"+e);
}
log.info("请求报文:"+ CommonUtil.mapToString(mapData));
String result = HttpRequest.sendPost("https://commonapi.ysepay.com/gateway.do",CommonUtil.mapToString(mapData));
log.info("接口回执:"+result);
boolean resultVerify = false;
try{
resultVerify = YsPaySignUtils.resultVerify(result,"ysepay_single_division_online_query_response");
} catch (Exception e){
log.info("验签异常:"+e);
}
if(!resultVerify){
log.info("验签失败");
}
}
6.3 分账明细 detailResults
[{
"division_mer_usercode": "pinganyinhang02",
"division_amount": "20.2"
}]
7.附录
7.1 返回码说明
7.1.1 分账登记
枚举名称 |
枚举说明 |
0000 |
分账推送成功,已登记 |
9999 |
分账登记失败 |
7.1.2 分账查询
枚举名称 |
枚举说明 |
01 |
受理成功(登记成功) |
02 |
预分账成功(已拆分,待结算) |
00 |
分账成功 |
03 |
无需分账 |
99 |
分账失败 |
7.2 业务错误码
错误码 |
错误描述 |
解决方案 |
ACQ.SYSTEM_ERROR |
系统错误 |
请联系银盛客服 |
ACQ.BUSINESS_TIMEOUT_ERROR |
业务超时 |
请调用查询接口查询订单状态 |