反扫码支付

1、修订记录

2、业务说明

（1）场景说明

1、用户打开付款APP 如微信、支付宝 ，展示付款码；

2、收银员在商户系统操作生成支付订单，用户确认支付金额；

3、商户收银员用扫码设备扫描用户的条码/二维码，商户收银系统提交支付；

4、支付后台系统收到支付请求，根据验证密码规则判断是否验证用户的支付密码，不需要验证密码的交易直接发起扣款，需要验证密码的交易会弹出密码输入框。支付成功后会弹出成功页面，失败会弹出错误提示。

适用于各类商家系统，如大型商超、餐饮，连锁品牌等商家。商家需使用扫码枪等条码识别设备，扫描用户钱包上的 条码/二维码 完成收款，用户仅需出示付款码，所有收款操作由商家端完成

（2）接口说明

1、整合银联云闪付、微信、支付宝反扫接口，调用该接口进行反扫支付

2、收银员使用扫码设备读取用户 APP 展示的二维码后，商家系统识别付款APP， 通过系统调用该接口发起支付

3、当收单机构返回支付中或交易状态不明时， 需要调用交易查询接口查询订单实际支付状态。

4、notify_url 通知字段，支持成功时异步通知。

3、请求地址

4、参数说明

4.1公共请求参数

4.2 业务请求参数

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

4.3 二级商户 SubMerchantInfo

4.4 收货人信息 ConsigeeInfo

4.5 微信营销 detail

4.5.1 goods 微信商品列表

4.6 支付宝营销 AliGoodsDetail

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

4.8 银联单品信息营销 UnionPayGoodsDetail

5.同步响应参数说明

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

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

5.1 公共响应参数

5.2 业务响应参数

5.3 微信营销 wxpay_coupon_info

5.3.1 响应参数 promotionDetail

5.4 微信营销列表 wxpay_coupon_good_detail

5.5 支付宝营销 alipay_coupon_info

5.5.1 AlipayTradeFundBill（支付金额）

5.5.2 VoucherDetail（所有优惠券）

5.5.2.1 响应参数 ContributeDetail 说明

5.6 支付宝营销 alipay_coupon_good_detail

type参数说明：WXREQ”:微信单品营销请求；“WXRESP”:微信单品营销渠道响应；“ALIREQ”:支付宝单品营销请求；“ALIRESP”:支付宝单品营销渠道响应；

goodsDetailJson参数说明：type为WXREQ/ALIREQ请求类型时，为请求时传入值。type为WXRESP/ALIRESP时为渠道返回的响应值

5.6.1 type为“ALIRESP”时响应参数goodsDetailJson说明

5.6.2 type为“WXRESP”时响应参数goodsDetailJson说明

5.6.3 type为“WXREQ”时响应参数goodsDetailJson说明

5.6.4 type为“ALIREQ”时响应参数goodsDetailJson说明

6.服务器交易成功异步通知

银盛支付对商户的请求数据处理完成后，会将处理的结果数据通过系统程序控制客户端页面自动跳转的方式通知给商户网站。这些处理结果数据就是页面跳转同步通知参数。

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

6.1 微信优惠 wxpay_coupon_good_detail

6.2 支付宝 ali_goods_details

6.3 银联 CupQrCouponDetail

6.4 银联 CouponInfo

6.4.1 CupQrCouponDetail

6.4.2 IssAddnData

6.4.2.1 DctDetail说明

6.4.3 CupAcpCouponInfo说明

7.服务器交易失败异步通知

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

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

8.样例

Json串为原始串，变成字符串时，会添加\“等转义符进去

8.1 detail 字段值

//注意goods_detail字段的格式为"goods_detail":[{}],较多商户写成"goods_detail":{}
{
    "cost_price":608800, 
    "receipt_id":"wx123", 
    "goods_detail":[
        {
            "goods_id":"商品编码", 
            "wxpay_goods_id":"1001", 
            "goods_name":"", 
            "quantity":1, 
            "price":528800
        }, 
        {
            "goods_id":"商品编码", 
            "wxpay_goods_id":"1002", 
            "goods_name":"iPhone6s 32G", 
            "quantity":1, 
            "price":608800
        }
    ]
}

8.2 wxpay_coupon_info

{
    "cash_fee": 22.09,
    "cash_fee_type": "CNY",
    "coupon_fee": 4,
    "fee_type": "CNY",
    "promotionDetails": [{
        "activity_id": "72560",
        "amount": 4,
        "merchant_contribute": 0,
        "name": "21--30 单品免充 4",
        "other_contribute": 4,
        "promotion_id": "0219457",
        "scope": "SINGLE",
        "type": "DISCOUNT",
        "wxpay_contribute": 0
    }],
    "settlement_total_fee": 22.09,
    "total_fee": 26.09
}

8.3 wxpay_coupon_good_detail

{
    "discount_amount": 4,
    "goods_id": "11111",
    "goods_remark": "商品名称",
    "price": 26.1,
    "quantity": 1
}

8.4 AliGoodsDetail 营销信息

[
    {
        "goods_id":"apple-01",
        "alipay_goods_id":"20010001",
        "goods_name":"ipad",
        "quantity":1,
        "price":2000,
        "goods_category":"34543238",
        "categories_tree":"124868003| 126232002| 126252004",
        "body":"特价手机",
        "show_url":"http://www.alipay.com/xxx.jpg"
    }
]

8.5 coupon_info 信息

[{
    "spnsrId": "1",
    "offstAmt": 1
}, {
    "spnsrId": "2",
    "offstAmt": 2
}]

8.6 sub_merchant 说明

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

8.7 收信人信息 consignee_info

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

8.8 业务扩展 extend_params

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

8.9 支付宝业务拓展参数extend_params_channel

{
    "food_order_type": "qr_order"
}

8.9 SDK调用示例

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

    @Test
    public void barcodepayTest() throws Exception {
        /**1、组装调用反扫码支付 ScanCodePayApi.barcodepay需要的参数*/
        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");
        //业务代码，反扫D0为00510080
        bizContent.put("business_code", "00510080");
        //二维码行别，微信-1902000 支付宝-1903000 QQ扫码-1904000 银联扫码-9001002 招商银行:-3085840
        bizContent.put("bank_type", "1903000");
        //支付场景，条码支付取值：bar_code;声波支付取值：wave_code。注：当bank_type域为支付宝-1903000时，此域为必填字段。
        bizContent.put("scene", "bar_code");
        //扫码支付授权码，设备读取用户展示的条码或者二维码信息
        bizContent.put("auth_code", "23423");
        //终端设备号。注：当bank_type域为中国银联-9001002时，此域为必填字段
        bizContent.put("device_info", "");


        //=================二级商户信息, 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","");//身份证号,只支持身份证格式(如果签名方式为RSA，则用DES加密，密钥为商户号前8位，不足8位在商户号前补空格；如果签名方式为SM，则用SM加密)
        //二级商户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);


        //=================跨境支付付款人信息json格式，当收款方商户为跨境商户时，此域所有字段必填=================
        JSONObject crossBorderInfo = new JSONObject();
        subMerchantInfoJson.put("cross_border_name","");//付款人姓名
        crossBorderInfo.put("cross_border_idno","");//付款人身份证号码(如果签名方式为RSA，则用DES加密，密钥为商户号前8位，不足8位在商户号前补空格；如果签名方式为SM，则用SM加密)
        crossBorderInfo.put("cross_border_card_number","");//付款人银行卡号
        crossBorderInfo.put("cross_border_mobile","");//付款人手机号码
        crossBorderInfo.put("cross_border_tag","");//交易类型标识，只可以填写【服务类】或者【货物类】
        //跨境支付付款人信息json格式
        bizContent.put("cross_border_info",crossBorderInfo);

        //微信分配的子商户公众号账号ID
        bizContent.put("appid", "wx8888888888888888");
        //订单所属省编号（省市编号必须同时为空或者同时非空、并且需要符合层级关系）（特殊可空）
        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");

        //================要上传的商品信息json格式(可空)=================
        //注意：如果detail已经不为空，那么detail里面wxpay_goods_detail不可空，goods_id/quantity/price不可空
        JSONObject detail = new JSONObject();
        detail.put("cost_price",0.23);//订单原价，整数不超过14位，小数不超过2位，单位元
        detail.put("receipt_id","Ys001001");//商品小票，长度不能超过32位
        //================商品列表goods_detail(如果detail已经填写，goods_detail不可空)=================
        JSONArray goodsDetail = new JSONArray();
        JSONObject goods = new JSONObject();
        goods.put("goods_id","Shouji_abcef_001-001");//商品编码由半角的大小写字母，数字，下划线，中划线中的一种或者几种组成，长度不能超过32位
        goods.put("wxpay_goods_id","1001");//微信支付定义的统一商品编号，长度不能超过32
        goods.put("goods_name","手机");//商品的实际名称，长度不能超过256
        goods.put("quantity",1000);//数量，只能是正整数
        goods.put("price",100.20);//商品单价，单位元，整数部分不能超过12位，小数不能超过2位
        goodsDetail.add(goods);
        //商品列表goods_detail设置到商品信息detail中
        detail.put("goods_detail",goodsDetail);
        //商品信息json格式
        bizContent.put("detail",detail);

        //================支付宝营销单品详情列表，反扫D0暂不支持(可空)=================
        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);

        //子商户ip，反扫D0暂不支持
        bizContent.put("submer_ip","112.112.112.112");//子商户ip

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

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

8.10 API接口代码示例

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

 public static void main(String[] args) {
        Map<String,String> mapData = new HashMap<>();
        //组装公共参数
        mapData.put("method", "ysepay.online.barcodepay");
        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("bank_type","1903000");//二维码行别，微信-
        // 支付宝-1903000   中国银联-9001002,苏宁-1905000
        json.put("scene","bar_code");//支付场景，条码支付取值：bar_code;声波支付取值：wave_code。注：当bank_type域为支付宝-1903000时，此域为必填字段
        json.put("auth_code","280540348433980465");//扫码支付授权码，设备读取用户展示的条码或者二维码信息

        JSONObject json_detail = new JSONObject();
        json_detail.put("cost_price","1.0");
        json_detail.put("receipt_id","5432");

        JSONObject json_detail_good = new JSONObject();
        json_detail_good.put("goods_id","5432");
        json_detail_good.put("wxpay_goods_id","543");
        json_detail_good.put("goods_name","测试商品");
        json_detail_good.put("quantity","1");
        json_detail_good.put("price","1.0");

        json_detail.put("goods_detail",json_detail_good.toString());
        json.put("detail",json_detail.toString());
        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_barcodepay_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("接口验签失败");
        }
    }

8.11 UnionPayGoodsDetail 营销信息

[
    {
        "goods_id":"apple-01",
        "goods_name":"ipad",
        "quantity":1,
        "price":2000,
        "goods_category":"34543238",
        "addnInfo":"内容自定义"

    }
]

9.附录

9.1 交易状态（trade_status）

9.2 交易扩展状态（trade_status_ext）

9.3 支付宝-支付渠道代码

9.4 支付宝-券类型

注：不排除将来渠道新增其他类型的可能，商家接入时注意兼容性避免硬编码

9.5 支付网关编号

9.6 响应码介绍