线上分账系统接口

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.请求地址

环境 HTTPS请求地址
正式环境 https://commonapi.ysepay.com/gateway.do

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";
        //ys公钥证书存放地址 建议配置在项目的配置文件里面
        String publicKeyFilePath = "D:\\opensdk\\businessgate.cer";
        //私钥证书密钥,建议配置在项目的配置文件里面
        String privateKeyPassworde = "123456";

        //银盛支付服务器主动通知商户网站里指定的页面http路径
        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");//原订单交易金额,20长度位,保留2位小数
        bizContent.put("sys_flag", "DD");//可空。系统标志 DD:订单交易,DS:代收交易,默认是DD,订单交易
        bizContent.put("is_divistion", "01");//原订单是否参与分账01:是,02否
        bizContent.put("is_again_division", "N");//是否重新分账Y:是,N:否
        bizContent.put("division_mode", "01");//分账模式01 :比例,02:金额
        //分账明细,参与分账时不可以空,明细中的是否必填按照分账来描述
        JSONArray divList = new JSONArray();
        JSONObject divObject = new JSONObject();
        divObject.put("division_mer_usercode","hyfz_test2");//分账商户号
//        divObject.put("div_amount","0.09");//分账金额, 可空按分账模式可填
        divObject.put("div_ratio","0.90");//分账比例,分账比例之和必须为1, 可空按分账模式可填
        divObject.put("is_chargeFee","02");//是否收取手续费(01:是,02否)若配置手续费收支分离,该参数配置的手续费承担方不生效
        divList.add(divObject);
        divObject = new JSONObject();
        divObject.put("division_mer_usercode","y2110091506590197537");//分账商户号
//        divObject.put("div_amount","0.09");//分账金额, 可空按分账模式可填
        divObject.put("div_ratio","0.10");//分账比例,分账比例之和必须为1, 可空按分账模式可填
        divObject.put("is_chargeFee","01");//是否收取手续费(01:是,02否)
        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);
            //根据返回结果处理自己的业务逻辑,result内容详见接口文档
        }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";
        //ys公钥证书存放地址 建议配置在项目的配置文件里面
        String publicKeyFilePath = "D:\\opensdk\\businessgate.cer";
        //私钥证书密钥,建议配置在项目的配置文件里面
        String privateKeyPassworde = "123456";

        //银盛支付服务器主动通知商户网站里指定的页面http路径
        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");//可空。系统标志 DD:订单交易,DS:代收交易,默认是DD,订单交易
        req.setParamData(bizContent);
        String result = null;
        try{
            logger.info("线上分账查询调用sdk接口addScanMerc请求入参为:"+ JSONObject.toJSONString(req));
            result = MercFundApi.divisionOnlineQuery(req);
            //根据返回结果处理自己的业务逻辑,result内容详见接口文档
        }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");//是否重新分账Y:是,N:否
        json.put("division_mode","01");

        //分账明细,参与分账时不可以空,明细中的是否必填按照分账来描述
        JSONArray divList = new JSONArray();
        JSONObject divObject = new JSONObject();
        divObject.put("division_mer_usercode","hyfz_test2");//分账商户号
        //divObject.put("div_amount","0.09");//分账金额, 可空按分账模式可填
        divObject.put("div_ratio","0.90");//分账比例,分账比例之和必须为1, 可空按分账模式可填
        divObject.put("is_chargeFee","02");//是否收取手续(01:是,02否)若配置手续费收支分离,该参数配置的手续费承担方不生效
        divList.add(divObject);
        divObject = new JSONObject();
        divObject.put("division_mer_usercode","y2110091506590197537");//分账商户号
        //divObject.put("div_amount","0.09");//分账金额, 可空按分账模式可填
        divObject.put("div_ratio","0.10");//分账比例,分账比例之和必须为1, 可空按分账模式可填
        divObject.put("is_chargeFee","01");//是否收取手续费(01:是,02否)
        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 业务超时 请调用查询接口查询订单状态

results matching ""

    No results matching ""