支付宝生活号接口

1、修订记录

2、业务说明

（1）场景说明

帮助商户代创建和代运营生活号。在商户完成对开发者的授权后，开发者即默认添加为商户生活号的操作员，即可通过接口或生活号后台帮商户维护生活号。

（2）接口说明

1、调用此接口前，请确保已开通“生活号第三方应用“

2、代创建提交且支付宝审核通过后，下一步则需商户做代创建的授权确认，商户可登录商家中心b.alipay.com查看待办事项，并确认授权

3、请求地址

4、请求参数说明

4.1公共请求参数

4.2 业务请求参数

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

4.2.1 二级商户 SubMerchantInfo

4.2.2 收货人信息 ConsigeeInfo

4.2.3 支付宝营销 AliGoodsDetail

4.2.4 银联259号文条码改造字段 UnionQrCodeBaseRequest

4.2.5 购买人实名认证信息 buyer_realname_info

4.2.6 付款方GPS信息 GpsInformation

5、响应参数说明

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

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

5.1 公共响应参数

5.2 业务响应参数

6、服务器交易成功异步通知参数说明

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

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

6.1 支付宝营销 GoodsDetail

7、交易失败异步通知

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

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

8、Jsapi支付

//下单完成，拿到支付串后进行jsapi支付，并唤起支付控件
<p id="result">result: </p>
<script type="application/javascript">
    // 调试时可以通过在页面定义一个元素，打印信息，使用alert方法不够优雅
    function log(obj) {
        $("#result").append(obj).append(" ").append("<br />");
    }

    $(document).ready(function(){
        // 页面载入完成后即唤起收银台
        // 此处${tradeNO}为模板语言语法，实际调用样例类似为
         tradePay("2016072621001004200000000752")
        //这个值即取自上面jsapi_pay_info参数里的tradeNO的值
         tradePay("${tradeNO}"); 

         // 点击payButton按钮后唤起收银台
         $("#payButton").click(function() {
            tradePay("${tradeNO}");
         });

         // 通过jsapi关闭当前窗口，仅供参考，更多jsapi请访问
         // /aod/54/104510
         $("#closeButton").click(function() {
            AlipayJSBridge.call('closeWebview');
         });
     });

    // 由于js的载入是异步的，所以可以通过该方法，当AlipayJSBridgeReady事件发生后，再执行callback方法
     function ready(callback) {
         if (window.AlipayJSBridge) {
             callback && callback();
         } else {
             document.addEventListener('AlipayJSBridgeReady', callback, false);
         }
     }

     function tradePay(tradeNO) {
        ready(function(){
             // 通过传入交易号唤起快捷调用方式(注意tradeNO大小写严格)
             AlipayJSBridge.call("tradePay", {tradeNO: tradeNO
             }, function (data) {
                 log(JSON.stringify(data));
                 if ("9000" == data.resultCode) {
                     log("支付成功");
                 }
             });
        });
    }
</script>

result.resultCode  
支付结果：
9000∶ 订单支付成功;
8000∶正在处理中;
4000∶ 订单支付失败∶
6001∶用户中途取消;
6002∶网络连接出错；
99∶用户点击忘记密码快捷界面退出（onlyiOS sice9.5）

9、样例

9.1 业务扩展 extend_params

{
    "cartTYpe": "00",
    "order_mode": "01",
    "seller_list": [{
        "seller_id": "123"
    }, {
        "seller_id": "456"
    }]
}

9.2 二级商户 sub_merchant

{
    "merName": "二级商户名称",
    "merShortName": "二级商户简称",
    "merAddr": "二级商户地址",
    "mobileNo": "二级商户服务电话",
    "merNo": "二级商户编号",
    "category": "类目",
    "mrchntCertId": "身份证号"
}

9.3 收货人 consignee_info

{
    "consigneeName": "收货人姓名",
    "consigneeAddr": "收货地址",
    "transportationInfo": "物流配送信息",
    "commodityName": "商品名称",
    "commodityNumber": "商品数量"
}

9.4 支付宝业务拓展参数extend_params_channel

{
    "food_order_type": "qr_order"
}

9.5 SDK调用示例

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

    @Test
    public void alipayTest() throws Exception {
        /**1、组装调用支付宝生活服务窗支付接口 ScanCodePayApi.alipay需要的参数*/
        OnlineReqDataVo reqDataVo = new OnlineReqDataVo();
        //请求路径,具体见文档
        reqDataVo.setReqUrl("https://qrcode.ysepay.com/gateway.do");

        //商户在银盛支付平台开设的用户号[商户号]
        reqDataVo.setPartnerId("hyfz_test2");

        //银盛支付服务器主动通知商户网站里指定的页面http路径，支持多个url进行异步通知，多个url用分隔符“,”分开，格式如：url1,url2,url3
        reqDataVo.setNotifyUrl("http://127.0.0.1");

        //客户端私钥证书路径: 证书是在入网流程中自己申请的
        reqDataVo.setPrivateKeyFilePath("D:/cer/hyfz_test2.pfx");

        //客户端私钥密钥: 私钥密钥在入网流程中自己申请私钥证书时填写的
        reqDataVo.setPrivateKeyPassword("123456");

        //银盛公钥证书路径: 证书入网申请后随邮件发放
        reqDataVo.setYsPublicKeyFilePath("D:/cer/businessgate.cer");

        //交易类型，说明：1或者空：即时到账，2：担保交易
        reqDataVo.setTranType("1");
        /** -----------组装业务参数,并设置到入参里面reqDataVo.setParamData(bizContentMap): 业务参数说明详细见接口文档 -------------*/
        Map<String, Object> bizContent = new HashMap<>();
        //商户生成的订单号，生成规则前8位必须为交易日期，如20180525，范围跨度支持包含当天在内的前后一天，且只能由大小写英文字母、数字、下划线及横杠组成
        bizContent.put("out_trade_no", "201805256843192280647118");
        //商户日期(该参数做交易与查询时需要一致) 该日期需在当日的前后一天时间范围之内
        bizContent.put("shopdate", "20211013");
        //商品的标题/交易标题/订单标题/订单关键字等。该参数最长为250个汉字
        bizContent.put("subject", "支付宝生活服务窗支付接口测试");
        //该笔订单的资金总额，单位为RMB-Yuan。取值范围为[0.01，100000000.00]，精确到小数点后两位。Number(10,2)指10位长度，2位精度
        bizContent.put("total_amount", "2.99");
        //支持币种：CNY(人民币)、HKD(港币)、USD(美元)、EUR(欧元)、JPY(日元)
        //注:不填默认是CNY(人民币)，如是非跨境商户，币种不能填HKD(港币)、USD(美元)、EUR(欧元)、JPY(日元)中的任意一种外币币种
        bizContent.put("currency", "CNY");
        //收款方银盛支付用户号
        bizContent.put("seller_id", "hyfz_test2");
        //收款方银盛支付客户名
        bizContent.put("seller_name", "银盛支付服务股份有限公司行业发展部");
        //设置未付款交易的超时时间，一旦超时，该笔交易就会自动被关闭。
        //(需申请业务权限，权限未开通情况下该参数不生效，默认未付款交易的超时时间为7d)取值范围：1m～15d。m-分钟，h-小时，d-天。该参数数值不接受小数点，如1.5h，可转换为90m。
        //注意：设置了未付款交易超时时间的情况下，若我司在限定时间内没有收到成功支付通知，则会关闭交易，关闭后该笔交易若付款方支付成功的情况下，会自动原路退款至付款方
        bizContent.put("timeout_express","96h");
        //业务扩展参数，一个json字符串,order_mode订单模式，暂时可选的值为:00 代表购物车模式;seller_list参与分账的收款方信息数组，每个元素包含seller_id收款方银盛支付用户号。
        //实时分账业务，order_mode和seller_list均不能为空，order_mode的值必须为00
        bizContent.put("extend_params","{\"cartTYpe\": \"00\",\"order_mode\": \"01\",\"seller_list\": [{\"seller_id\": \"123\"},{\"seller_id\": \"456\"}]}");
        //公用回传参数
        bizContent.put("extra_common_param", "extra_common_param");
        //业务代码
        bizContent.put("business_code", "00510080");
        //买家支付宝账号，和buger_id不能同时为空(可空)
        bizContent.put("buyer_logon_id", "233423423");
        //买家支付宝用户ID，和buyer_logon_id不能同时为空。
        //buyer_id获取方法：https://doc.open.alipay.com/doc2/detail.htm?spm=a219a.7629140.0.0.8ujLD6&treeId=115&articleId=104114&docType=1通过网页授权获取用户信息，同步响应结果中的user_id对应文档中的buyer_id
        bizContent.put("buyer_id", "23342342233");


        //=================二级商户信息, Json格式=================
        //如果有值则二级商户信息都不能为空，如果没值则都不能有值
        JSONObject subMerchantInfoJson = new JSONObject();
        subMerchantInfoJson.put("merName","");//二级商户名称,支持25个中文
        subMerchantInfoJson.put("merShortName","");//二级商户简称,支持25个中文
        subMerchantInfoJson.put("merAddr","");//二级商户地址,支持100个中文
        subMerchantInfoJson.put("telephone","");//固定电话/手机号码二选一
        subMerchantInfoJson.put("merNo","");//二级商户编号
        subMerchantInfoJson.put("category","");//类目，按附件内容输入类目编号
        subMerchantInfoJson.put("mrchntCertId","");//身份证号,只支持身份证格式(DES加密，密钥为商户号前8位，不足8位在商户号前补空格)
        //二级商户json格式
        bizContent.put("sub_merchant",subMerchantInfoJson);


        //=================收货人信息json格式(可空)=================
        JSONObject consigneeInfoJson = new JSONObject();
        subMerchantInfoJson.put("consigneeName","");//收货人姓名
        subMerchantInfoJson.put("consigneeAddr","");//收货地址
        subMerchantInfoJson.put("transportationInfo","");//物流配送信息（物流名称+订单号）
        subMerchantInfoJson.put("commodityName","");//商品名称
        subMerchantInfoJson.put("commodityNumber","");//商品数量
        //收货人信息json格式
        bizContent.put("consignee_info",consigneeInfoJson);


        //订单所属省编号（省市编号必须同时为空或者同时非空、并且需要符合层级关系）（特殊可空）
        bizContent.put("province",null);
        //订单所属市编号（省市编号必须同时为空或者同时非空、并且需要符合层级关系）（特殊可空）
        bizContent.put("city",null);
        //是否限制信用卡。值为1表示禁用信用卡，0或为空表示不限制
        bizContent.put("limit_credit_pay","0");
        //花呗分期期数,仅在支付宝支付的时候生效,目前期数支持6,12
        bizContent.put("hb_fq_num","6");
        //是否允许多次支付,Y：允许;N：不允许（参数为空或者Y时，默认该笔订单交易状态非成功状态时，支持选择其他支付方式继续付款，适用于收银台模式。 当为N时表示该笔订单交易状态为失败状态时，不支持选择其他支付方式继续付款，收银台模式下建议该参数为空）
        bizContent.put("allow_repeat_pay","N");
        //失败通知地址（交易状态为失败时，银盛支付服务器主动通知商户网站里指定的页面http路径，支持多个url进行异步通知，多个url用分隔符“,”分开，格式如：url1,url2,url3）注：只有不允许重复支付的交易才会通知
        bizContent.put("fail_notify_url","http://127.0.0.1");


        //================支付宝营销单品详情列表(可空    )=================
        JSONArray aliGoodsDetails = new JSONArray();
        //================支付宝营销单品详情aliGoodsDetail=================
        JSONObject aliGoodsDetail = new JSONObject();
        aliGoodsDetail.put("goods_id","Shouji_abcef_001-001");//营销单品编号
        aliGoodsDetail.put("alipay_goods_id","1001");//营销单品支付宝侧编号
        aliGoodsDetail.put("goods_name","手机");//营销单品名称
        aliGoodsDetail.put("quantity",1000);//数量，只能是正整数
        aliGoodsDetail.put("price",100.20);//[0,999999999] 左闭右闭区间，小数点后最多允许两位
        aliGoodsDetail.put("goods_category","");//营销单品类目
        aliGoodsDetail.put("categories_tree","");//营销单品类目树
        aliGoodsDetail.put("body","");//营销单品描述
        aliGoodsDetail.put("show_url","");//营销单品展示地址
        aliGoodsDetails.add(aliGoodsDetail);
        //支付宝营销单品详情列表
        bizContent.put("aliGoodsDetails",aliGoodsDetails);

        bizContent.put("submer_ip","112.112.112.112");//子商户ip(可空    )

        //设置业务参数到biz_content
        reqDataVo.setParamData(bizContent);

        /** 2、调用ScanCodePayApi.alipay方法 */
        String result = null;
        try{
            System.out.println("支付宝生活服务窗支付接口-调用sdk接口alipay请求入参为:"+ JSONObject.toJSONString(reqDataVo));
            result = ScanCodePayApi.alipay(reqDataVo);
            //根据返回结果处理自己的业务逻辑,result内容详见接口文档
        }catch (Exception e){
            System.out.println("支付宝生活服务窗支付接口-失败:"+e.getCause().getMessage());
            e.printStackTrace();
        }
        System.out.println("支付宝生活服务窗支付接口-调用sdk接口alipay返回结果为:"+result);
    }

9.5 API接口代码示例

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

public static void main(String[] args) {
        Map<String,String> mapData = new HashMap<>();
        //组装公共参数
        mapData.put("method", MethodConstants.Order.ALIJSAPI_PAY);
        mapData.put("partner_id","hyfz_test2");//发起方商户号
        mapData.put("timestamp", DateUtil.getDateNow());
        mapData.put("charset","utf-8");
        mapData.put("sign_type","RSA");//签名类型
        mapData.put("notify_url","http://127.0.0.1");//异步通知地址，需要外网可访问，接受到通知后需要返回success
        mapData.put("version","3.0");

        //组装业务参数
        JSONObject json = new JSONObject();
        json.put("out_trade_no", SerialGenerator.getOrder());//商户的订单号
        json.put("shopdate",DateUtil.getDateNowYmd());
        json.put("subject","支付宝生活服务窗支付测试");
        json.put("timeout_express","96h");//超时时间，需要申请权限后，该参数才会生效，否则默认7d，超出时间后，银盛会关闭渠道方的预支付订单。
        json.put("total_amount","0.01");
        json.put("currency","CNY");
        json.put("seller_id","hyfz_test2");//收款方
        json.put("seller_name","银盛支付服务股份有限公司行业发展部");
        json.put("business_code","01000010");//发起方商户的业务代码
        json.put("buyer_logon_id","19967567859");

        mapData.put("biz_content",json.toString());
        //对参数进行签名
        try{
            log.info("待签名参数："+ CommonUtil.mapToString(mapData));
            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://qrcode.ysepay.com/gateway.do",CommonUtil.mapToString(mapData));
        log.info("接口回执："+result);
        if(StringUtil.isBlank(result) ||null == result){
            log.info("接口返回结果为空！");
        }
        //对接口回执进行验签
        JSONObject resultJson = JSONObject.parseObject(result, Feature.OrderedField);
        String resultContent = resultJson.getString("ysepay_online_alijsapi_pay_response");
        String resultSign = resultJson.getString("sign");
        boolean resultVerify = false;
        try{
            resultVerify = YsPaySignUtils.resultVerify1(resultContent,resultSign);

        } catch (Exception e){
            log.info("验签异常："+e);
        }
        if(!resultVerify){
            log.info("接口验签失败");
        }
    }

10.附录

10.1 交易状态

10.2 支付网关编号