互联网子商户进件

1.修订记录

2.接口说明

（1）场景说明

1、线上子商户进件，包括口令获取、商户注册、注册查询、图片上传接口
2、需要调用口令获取(上传图片需要用到)、图片上传、注册接口进行注册
3、调用查询接口查看注册结果

（2）接口说明

1、商户进件上传口令获取、注册文本接口与查询接口-V3.0版本(新)
2、口令获取：调用接口获取token口令，在图片上传时需要此值
3、图片上传：根据token上传图片，调用商户注册接口时通过上传的token关联对应的图片
4、商户注册：传入商户资料进行子商户注册，注册成功返回子商户号
5、注册查询：商户注册结果未知时，调用接口获取商户注册状态

3.请求地址

4.请求参数说明

4.1 公共请求参数

5.业务参数说明

参数名 biz_content,值为一个json格式对象，下面列表描述json对象的值

5.1 图片上传口令获取

5.1.1 图片上传口令获取

该请求为空参数（但是biz_content依然要求按照json格式填写），每次请求都会获取到一个 TOKEN（口令）字符串，您需要在有效时间内，凭此TOKEN上传图片文件至银盛文件服务器中以备注册使用。TOKEN有效时间为120s，一个TOKEN可以上传N张类型不同的图片文件，同类型的图片文件将以最近一次上传为准，为了提高注册成功率，请一次性将需要提高的图片信息全部上传。

图片上传地址：
生产环境:https://uploadApi.ysepay.com:2443/yspay-upload-service?method=upload
测试环境:https://cloudbilltest.ysepay.com:2080/yspay-upload-service?method=upload

图片上传完毕之后请发起商户注册请求，进行注册。注册接口中的token属性是您上传文件时使用的TOKEN值，您需要记住。

5.1.2 业务响应参数

5.1.3 SDK调用示例

• 银盛将与服务端交互的接口封装在开发工具包（SDK）中，开发者无需自行实现同服务端交互的复杂逻辑，直接将SDK导入自己的工程后，通过sdk示例代码实现同银盛服务端的交互。

 @Test
    public void getToken() throws Exception {
        /**1、获取需要的参数*/
        OnlineReqDataVo req = new OnlineReqDataVo();
        //获取图片上传token的请求路径,建议配置在项目的配置文件里面
        String reqUrl = "https://register.ysepay.com:2443/register_gateway/gateway.do";
        //客户端私钥证书路径: 证书是在入网流程中自己申请的
        String privateKeyFilePath = "D:\\openRSA\\hyfz_test2.pfx";
        //客户端私钥密钥: 私钥密钥在入网流程中自己申请私钥证书时填写的
        String privateKeyPassworde = "123456";
        //银盛公钥证书路径: 证书入网申请后随邮件发放
        String publicKeyFilePath = "D:\\openRSA\\businessgate.cer";
        //商户在银盛支付平台开设的用户号[商户号]:入网申请后发放
        String partnerId = "hyfz_test2";
        //银盛支付服务器主动通知商户网站里指定的页面http路径。
        String notifyUrl = "http://127.0.0.1";
        //设置私钥证书路径
        req.setPrivateKeyFilePath(privateKeyFilePath);
        //设置私钥密钥
        req.setPrivateKeyPassword(privateKeyPassworde);
        //设置ys公钥证书路径
        req.setYsPublicKeyFilePath(publicKeyFilePath);
        //设置请求路径
        req.setReqUrl(reqUrl);
        //设置通知路径
        req.setNotifyUrl(notifyUrl);
        req.setPartnerId(partnerId);

        logger.info("获取图片上传token请求入参为:"+ JSONObject.toJSONString(req));

        /**2、调用API的方法*/
        String result = null;
        try{
            result =  OnlineMercApi.getToken(req);
            //根据返回结果处理自己的业务逻辑,result内容详见接口文档
        }catch (Exception e){
            logger.info("获取图片上传token失败:"+e.getCause().getMessage());
            e.printStackTrace();
            //根据自己要求处理业务逻辑
        }
    }

5.1.4 API接口代码示例

• 需要开发者自己封装调用逻辑，实现调用银盛api接口同银盛服务端交互,该示例没有加签验签及发送http请求代码，需自行下载demo查看。

   @Test
    public void getToken() throws Exception {
        //组装公共请求参数
        Map<String,String> mapDate = new HashMap<String, String>();
        mapDate.put("method","ysepay.merchant.register.token.get");
        mapDate.put("partner_id","hyfz_test2");
        mapDate.put("timestamp", DateUtil.getDateNow());
        mapDate.put("charset","UTF-8");
        mapDate.put("sign_type","RSA");
        mapDate.put("notify_url","http://127.0.0.1");
        mapDate.put("version","3.0");
        mapDate.put("biz_content","{}");
        //进行参数签名，获取sign
        try{
            String sign = YsPaySignUtils.sign(mapDate);
            log.info("产生的签名sign："+sign);
            mapDate.put("sign",sign);
        }catch (Exception e){
            log.info("签名异常："+e);
        }
        //调用TOKEN获取接口
        String result = HttpRequest.sendPost("https://register.ysepay.com:2443/register_gateway/gateway.do",CommonUtil.mapToString(mapDate));
        if(StringUtil.isBlank(result)){
            log.info("接口返回为空");
        }

        //返回数据验签
        boolean flag = false;
        try {
            flag = YsPaySignUtils.resultVerify(result,"ysepay_merchant_register_token_get_response");
            if (!flag){
                throw new Exception("验签失败");
            }
        }catch (Exception e){
            log.info("验签异常："+e);
        }
        //解析接口回执，获取token值
        JSONObject response = (JSONObject) JSON.parseObject(result, Feature.OrderedField).get("ysepay_merchant_register_token_get_response");
        String token = response.get("token").toString();
        log.info("TOKEN:"+token);
    }

5.2 商户注册接口

商户通过上传口令获取接口拿到银盛返回的Token值之后，等同于拿到了一个可以上传图片的口令。商户可以根据这个口令完成图片的上传，这些上传的图片会与本接口传递的文本信息是注册商户不可缺少的元素。图片上传接口是文件上传服务提供的接口，并不是网关接口，商户可以根据下面给出的地址进行访问。

上传图片接口的地址：
https://uploadApi.ysepay.com:2443/yspay-upload-service?method=upload

接口参数请参看4.附相关内容

图片上传完成之后需要在网关上传注册的文本信息，本接口定义的是上传注册文本信息时需要传递的参数。

5.2.1 请求注册接口

5.2.2 业务响应参数

银盛支付对商户的请求数据处理完成后，会将处理的最终结果数据异步回执给商户。

5.2.3 SDK调用示例

• 银盛将与服务端交互的接口封装在开发工具包（SDK）中，开发者无需自行实现同服务端交互的复杂逻辑，直接将SDK导入自己的工程后，通过sdk示例代码实现同银盛服务端的交互。

 @Test
    public void merchantRegister() throws Exception {
        /**1、获取需要的参数*/
        OnlineReqDataVo req = new OnlineReqDataVo();
        //注册线上进件商户的请求路径,建议配置在项目的配置文件里面
        String reqUrl = "https://register.ysepay.com:2443/register_gateway/gateway.do";
        //客户端私钥证书路径: 证书是在入网流程中自己申请的
        String privateKeyFilePath = "D:\\openRSA\\hyfz_test2.pfx";
        //客户端私钥密钥: 私钥密钥在入网流程中自己申请私钥证书时填写的
        String privateKeyPassworde = "123456";
        //银盛公钥证书路径: 证书入网申请后随邮件发放
        String publicKeyFilePath = "D:\\openRSA\\businessgate.cer";
        //商户在银盛支付平台开设的用户号[商户号]:入网申请后发放
        String partnerId = "hyfz_test2";
        //银盛支付服务器主动通知商户网站里指定的页面http路径。
        String notifyUrl = "http://127.0.0.1";
        //设置私钥证书路径
        req.setPrivateKeyFilePath(privateKeyFilePath);
        //设置私钥密钥
        req.setPrivateKeyPassword(privateKeyPassworde);
        //设置ys公钥证书路径
        req.setYsPublicKeyFilePath(publicKeyFilePath);
        //设置请求路径
        req.setReqUrl(reqUrl);
        //设置通知路径
        req.setNotifyUrl(notifyUrl);
        req.setPartnerId(partnerId);

        /**2、组装业务参数*/
        Map<String,Object> bizContentMap = new HashMap<>();
        bizContentMap.put("merchant_no","youname");//平台商唯一标识
        bizContentMap.put("remark","第一个商户");//备注
        bizContentMap.put("cust_type","O");//客户类型O：小微；B：企业；C:个体
        bizContentMap.put("token","TK20211012165208644yMaMr2UD");//token值 :通过getToken接口获取
        bizContentMap.put("another_name","龙商龙行");//商户简称
        bizContentMap.put("cust_name","龙行百货");//公司名称或者客户名称，客户类型是小微商户时客户名称需和身份证号码、法人手机号码匹配
        bizContentMap.put("mer_flag","11");//商户属性。11为普通商户，12为代理商户，不填的情况下默认为普通商户
        bizContentMap.put("industry","23");//行业类别 ，详细类别见3.6节的定义
        bizContentMap.put("province","内蒙古自治区");//省，为完善企业信息请准确填写
        bizContentMap.put("city","呼和浩特市");//市,为完善企业信息请准确填写
        bizContentMap.put("company_addr","滨河北路中海外滩");//详细地址，为完善企业信息请准确填写
        bizContentMap.put("legal_name","李四");//企业法人名字，需和身份证号码、法人手机号码匹配，当客户类型为小微商户是，企业法人可以为空，
        bizContentMap.put("legal_tel","13747255939");//企业法人手机号码
        bizContentMap.put("mail","7691345307@qq.com");//登陆邮箱，请按照正确邮箱格式填写
        bizContentMap.put("contact_man","张三");//联系人
        bizContentMap.put("contact_phone","18888888888");//联系人手机号码
        bizContentMap.put("legal_cert_type","00");//企业法人证件类型，支持类型请参照3.7小节
        bizContentMap.put("legal_cert_no", SrcDesUtil.encryptData(partnerId,"110101198001010010"));//企业法人证件号,请加密传输 注：如果签名方式为RSA，则用DES加密，密钥Src用户号前8位，不足8位前补空; 如果签名方式为SM，则用SM加密
        bizContentMap.put("legal_cert_expire","20360810");//企业法人证件有效期,格式为yyyyMMdd。为空时默认长期有效
        bizContentMap.put("bus_license","沪-A1283123132");//营业执照，客户类型为个体商户、企业户时为必填，为保证商户信息准确，请填写有效营业执照号
        bizContentMap.put("bus_license_expire","20181229");//    营业执照有效期，客户类型为个体商户、企业商户时为必填，格式为yyyyMMdd
        bizContentMap.put("notify_type","1");//通知方式，此通知为商户号审核通知，通知内容包含帐号信息，为空的情况下将不发送通知，支持通知方式1、邮箱，2手机短信，3、邮箱+手机短信
        bizContentMap.put("settle_type","1");//结算方式，0:平台内账户1:银行卡账户.结算方式为0时银行卡信息只涉及提现，为1时涉及到提现以及清算
        bizContentMap.put("bank_account_no","43672221090449733315");//银行帐号，注：当bank_account_type为对公账户时，该属性字段长度可以为String(1,32)
        bizContentMap.put("bank_account_name","王二小");//开户人，银行卡账户名，需和法人姓名或客户姓名一致
        bizContentMap.put("bank_account_type","personal");//银行账户类型，此处必填corporate :对公账户;personal:对私账户
        bizContentMap.put("bank_card_type","debit");//银行卡类型，可填debit|unit.debit借记卡，unit单位结算卡
        bizContentMap.put("bank_name","中国建设银行呼和浩特赛罕区支行");//    开户行名称，为交易能顺利进行，请尽可能填写到街道
        bizContentMap.put("bank_type","中国建设银行");//银行行别
        bizContentMap.put("bank_province","内蒙古自治区");//开户行所在的省份
        bizContentMap.put("bank_city","呼和浩特市");//开户行所在城市
        bizContentMap.put("cert_type","00");//开户人证件类型，目前只支持00,00为身份证
        bizContentMap.put("cert_no",SrcDesUtil.encryptData(partnerId,"110101198001010010"));//开户人证件号码，请加密传输
        bizContentMap.put("bank_telephone_no","13347255979");//银行预留手机号
        bizContentMap.put("service_tel","13347259638");//客服电话
        bizContentMap.put("org_no","6190000067");//机构号
        bizContentMap.put("sub_account_flag","N");//分账参与商户标识

        req.setParamData(bizContentMap);
        logger.info("注册线上进件商户请求入参为:"+ JSONObject.toJSONString(req));

        /**2、调用API的方法*/
        String result = null;
        try{
            result =  OnlineMercApi.merchantRegister(req);
            //根据返回结果处理自己的业务逻辑,result内容详见接口文档
        }catch (Exception e){
            logger.info("注册线上进件商户失败:"+e.getCause().getMessage());
            e.printStackTrace();
            //根据自己要求处理业务逻辑
        }
    }

5.2.4 API接口代码示例

• 需要开发者自己封装调用逻辑，实现调用银盛api接口同银盛服务端交互,该示例没有加签验签及发送http请求代码，需自行下载demo查看。

public static void merchantRegister(){
        //获取token ,查看API接口代码示例获取token接口
        String token = getToken();
        //1.组装报文
        Map<String,String> mapDate = new HashMap<String,String>();

        //1.1组装外层报文 API请求参数
        mapDate.put("charset","UTF-8");
        mapDate.put("method", "ysepay.merchant.register.accept");
        mapDate.put("notify_url","http://127.0.0.1");
        mapDate.put("partner_id","hyfz_test2");
        mapDate.put("sign_type","RSA");
        mapDate.put("timestamp",DateUtil.getDateNow());
        mapDate.put("version","3.0");
        //1.2组装内层报文 业务数据
        JSONObject json = new JSONObject();
        json.put("merchant_no", "637587438028042315");
        json.put("cust_type","O");
        json.put("token",token);
        json.put("another_name","小明");
        json.put("cust_name","小明");
        json.put("industry","23");
        json.put("province","内蒙古自治区");
        json.put("city","呼和浩特市");
        json.put("company_addr","滨河北路中海外滩");
        json.put("legal_tel","13347255939");
        json.put("legal_cert_type","00");
        json.put("legal_cert_expire","20360810");
        json.put("settle_type","1");
        json.put("bank_account_no","43672221090449733315");
        json.put("bank_account_name","小明");
        json.put("bank_account_type","personal");
        json.put("bank_card_type","debit");
        json.put("bank_name","中国建设银行呼和浩特赛罕区支行");
        json.put("bank_type","中国建设银行");
        json.put("bank_province","内蒙古自治区");
        json.put("bank_city","呼和浩特市");
        json.put("cert_type","00");
        json.put("bank_telephone_no","13347255939");
        json.put("org_no","6190000067");
        //证件号加密
        try {
            //SrcDesUtil.encryptData(key,data) key直接传partner_id，方法内部会进行format：取商户号前8位，不足8位前面补空
            json.put("legal_cert_no",SrcDesUtil.encryptData("hyfz_test2","110101198001010010"));
            json.put("cert_no",SrcDesUtil.encryptData("hyfz_test2","110101198001010010"));
        } catch (Exception e){
            log.info("DES加密异常:"+e);
        }
        mapDate.put("biz_content",json.toString());

        //2 参数签名
        try {
            String sign = YsPaySignUtils.sign(mapDate);
            mapDate.put("sign",sign);
            mapDate.put("biz_content", URLEncoder.encode(mapDate.get("biz_content"),"utf-8"));
        }catch (Exception e){
            log.info("签名异常：",e);
        }

        //3发送请求
        log.info("发送请求数据"+CommonUtil.mapToString(mapDate));
        String result = HttpRequest.sendPost("https://register.ysepay.com:2443/register_gateway/gateway.do",CommonUtil.mapToString(mapDate));
        if (StringUtil.isBlank(result)){
            log.info("返回结果为空！");
        }

        //4对接口返回结果进行验签
        boolean resultVerify = false;
        try {
            log.info("待验签数据："+result);
            resultVerify = YsPaySignUtils.resultVerify(result,"ysepay_merchant_register_accept_response");
        }catch (Exception e){
            log.info("验签失败："+e);
        }
        log.info("验签结果"+resultVerify);
    }

5.3 商户注册查询接口

5.3.1 商户注册查询接口

5.3.2 业务响应参数

5.3.3 SDK调用示例

• 银盛将与服务端交互的接口封装在开发工具包（SDK）中，开发者无需自行实现同服务端交互的复杂逻辑，直接将SDK导入自己的工程后，通过sdk示例代码实现同银盛服务端的交互。

@Test
    public void queryMerchant() throws Exception {
        /**1、获取需要的参数*/
        OnlineReqDataVo req = new OnlineReqDataVo();
        //主动查询商户注册信息的请求路径,建议配置在项目的配置文件里面
        String reqUrl = "https://register.ysepay.com:2443/register_gateway/gateway.do";
        //客户端私钥证书路径: 证书是在入网流程中自己申请的
        String privateKeyFilePath = "D:\\openRSA\\hyfz_test2.pfx";
        //客户端私钥密钥: 私钥密钥在入网流程中自己申请私钥证书时填写的
        String privateKeyPassworde = "123456";
        //银盛公钥证书路径: 证书入网申请后随邮件发放
        String publicKeyFilePath = "D:\\openRSA\\businessgate.cer";
        //商户在银盛支付平台开设的用户号[商户号]:入网申请后发放
        String partnerId = "hyfz_test2";
        //银盛支付服务器主动通知商户网站里指定的页面http路径。
        String notifyUrl = "http://127.0.0.1";
        //设置私钥证书路径
        req.setPrivateKeyFilePath(privateKeyFilePath);
        //设置私钥密钥
        req.setPrivateKeyPassword(privateKeyPassworde);
        //设置ys公钥证书路径
        req.setYsPublicKeyFilePath(publicKeyFilePath);
        //设置请求路径
        req.setReqUrl(reqUrl);
        //设置通知路径
        req.setNotifyUrl(notifyUrl);
        req.setPartnerId(partnerId);

        /**2、组装业务参数*/
        Map<String,Object> bizContentMap = new HashMap<>();
        bizContentMap.put("usercode",null);//已注册用户号（usercode与merchant_no必填一个）
        bizContentMap.put("merchant_no","hyfz_test2");//平台商的用户号（usercode与merchant_no必填一个)

        req.setParamData(bizContentMap);
        logger.info("主动查询商户注册信息请求入参为:"+ JSONObject.toJSONString(req));

        /**2、调用API的方法*/
        String result = null;
        try{
            result =  OnlineMercApi.queryMerchant(req);
            //根据返回结果处理自己的业务逻辑,result内容详见接口文档
        }catch (Exception e){
            logger.info("主动查询商户注册信息失败:"+e.getCause().getMessage());
            e.printStackTrace();
            //根据自己要求处理业务逻辑
        }
    }

5.3.4 API接口代码示例

• 需要开发者自己封装调用逻辑，实现调用银盛api接口同银盛服务端交互,该示例没有加签验签及发送http请求代码，需自行下载demo查看。

 public void queryMerchant()throws Exception{
        Map<String,String> mapDate = new HashMap<>();
        mapDate.put("charset","UTF-8");
        mapDate.put("method", "ysepay.merchant.register.query");
        mapDate.put("notify_url","http://127.0.0.1");
        mapDate.put("partner_id","hyfz_test2");
        mapDate.put("sign_type","RSA");
        mapDate.put("timestamp",DateUtil.getDateNow());
        mapDate.put("version","3.0");

        JSONObject json = new JSONObject();
        json.put("merchant_no","hyfz_test2");
        json.put("usercode",null);

        mapDate.put("biz_content",json.toString());

        //签名
        try {
            String sign = YsPaySignUtils.sign(mapDate);
            mapDate.put("sign",sign);
        }catch (Exception e){
            log.info("签名异常："+e);
        }

        //调用查询接口
        String result = HttpRequest.sendPost("https://register.ysepay.com:2443/register_gateway/gateway.do",CommonUtil.mapToString(mapDate));
        if (StringUtil.isBlank(result)){
            log.info("结果返回空");
            throw new Exception("查询接口结果返回空");
        }
        JSONObject jsonObject = JSONObject.parseObject(result,Feature.OrderedField);
        JSONObject content = (JSONObject) jsonObject.get("ysepay_merchant_register_query_response");
        String sign = jsonObject.get("sign").toString();
        //验签
        boolean resultVerify = false;
        try{
            log.info("待验签数据："+content);
            resultVerify = YsPaySignUtils.resultVerify1(content.toJSONString(),sign);
        }catch (Exception e){
            log.info("验签异常："+e);
        }

        log.info("验签结果："+resultVerify);
    }

5.4 商户注册异步通知接口

银盛支付对商户的请求数据处理完成后，会将处理的结果数据通过服务器主动通知的方式通知给商户网站。这些处理结果数据就是服务器异步通知参数。

请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。

5.5 参考错误码

5.6 用户状态与客户状态

用户状态与客户状态是两个不同的概念，一个用户不一定是客户，是客户就一定是用户。

5.7 行业类别

5.8 证件类别

6.附：文件上传服务-图片上传

6.1 图片上传注意事项

为确保商户注册成功率，请按照以下注意事项检查图片后再上传：

1.基本要求：图像文字清晰，人眼可辨别；对比度、亮度适中；尽量不要有背景，即证件充满图片，如果不能保证没有背景，请选择纯黑背景而且背景不宜过多。

2.对扫描图像的要求：扫描时选择分辨率300dpi，不能低于150 dpi，分辨率最好不要过高。

3.对拍摄图像的要求：拍摄时注意光照的影响，尽量避免反光和黑影，尤其是证件有薄膜覆盖的时候；拍摄时做好聚焦，以免图像模糊不清；拍摄时将证件放正；尽量不要使拍摄角度倾斜过大，以免造成图像变形；拍摄时请不要选择过高的分辨率拍摄，一方面造成图片过大，不利于传输，一方面分辨率过高也会影响识别率。拍摄时可以选择1280*960分辨率拍摄，低一些的分辨率也可以选择，但是要确保图像文字清晰

4.企业商户请尽量使用最新的竖版“三证合一”营业执照。

5.为确保商户进件响应速度，建议图片大小在1M内，企业客户注册时我司会进行营业执照真伪校验，整体响应时间预计在40-60s内。

6.2 请求图片上传参数

请求参数是商户在与银盛支付进行数据交互时，提供给银盛支付的请求数据，以便银盛支付根据这些数据进一步处理。

6.3 业务响应参数

银盛支付对商户的请求数据受理完成后，会将处理的结果数据同步回执给商户，返回对象UploadPicResult 详细定义：

6.4 图片文件的类型以及说明

附表1

图片类型的必要性，打钩为必填项：