交易退款接口

1.修订记录

2.业务说明

（1）场景说明

1、对于支付完成的交易，需要进退款操作的，调用此接口来进行退款

（2）接口说明

1、商户根据实情情况，调用退款接口进行退款操作

3.请求地址

4.参数说明

4.1公共请求参数

4.2 业务请求参数

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

5.响应参数

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

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

5.1 公共响应参数

5.2 业务响应参数

6.异步通知参数

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

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

|settlement_amount |Number |N |原订单结算金额 示例值：100.00

6.1 银联 CupQrCouponDetail

6.2 银联 CouponInfo

6.2.1 CupQrCouponDetail

6.2.2 IssAddnData

6.2.2.1 DctDetail说明

6.2.3 CupAcpCouponInfo说明

6.3 wxpay_refund_coupon_info说明

6.3.1 refundDetail说明

6.4 alipay_refund_coupon_info说明

7.样例

7.1 SDK调用示例

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

    @Test
    public void onlineRefundTest() throws Exception {
        /** 组装参数 */
        OnlineReqDataVo reqDataVo = new OnlineReqDataVo();

        //二维码支付请求地址
        reqDataVo.setReqUrl("https://openapi.ysepay.com/gateway.do");

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

        //交易类型，说明：1或者空：即时到账，2：担保交易  根据自己需要退款交易来填写
        reqDataVo.setTranType("1");

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

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

        //银盛公钥证书路径: 证书入网申请后发放
        reqDataVo.setYsPublicKeyFilePath("E:/data/online/businessgate.cer");

        //业务参数: 业务参数说明详细见接口文档
        /** -----------组装业务参数开始 -------------*/
        Map<String,Object> params = new HashMap<>();
        //商户生成的订单号，生成规则前8位必须为交易日期，如20180525，范围跨度支持包含当天在内的前后一天，且只能由大小写英文字母、数字、下划线及横杠组成
        params.put("out_trade_no","201805256843192280647118");
        //商户日期(该参数做交易与查询时需要一致) 该日期需在当日的前后一天时间范围之内
        params.put("shopdate","20180525");
        //银盛交易号 特殊可选
        params.put("trade_no","311160414497667096");
        //需要退款的金额，该金额不能大于订单金额,单位为元，支持两位小数，Number(10,2)指10位长度，2位精度
        params.put("refund_amount","111.00");
        //退款的原因说明
        params.put("refund_reason","不想买了");
        //标识一次退款请求，同一笔交易多次退款需要保证唯一。该参数支持汉字，最大长度为16个。用同一订单号同一退款流水号继续退款时，则会返回第一次退款的结果不会继续退款
        params.put("out_request_no","RD2012061713107");
        reqDataVo.setParamData(params);
        /** -----------组装业务参数结束 -------------*/

        /**2、调用API的方法*/
        String result = null;
        try{
            System.out.println("线上交易退款接口-调用sdk接口tradeRefund请求入参为:"+ JSONObject.toJSONString(reqDataVo));
            result = RefundApi.tradeRefund(reqDataVo);
            //根据返回结果处理自己的业务逻辑,result内容详见接口文档
        }catch (Exception e){
            //根据自己要求处理进件失败的业务逻辑
            System.out.println("线上交易退款接口失败:"+e.getCause().getMessage());
        }
        System.out.println("结果返回:"+result);
    }

7.2 API接口代码示例

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

public static void tradeRefund()throws Exception{

        Map<String, String> mapData = new HashMap<>();
        mapData.put("partner_id", "hyfz_test2");
        mapData.put("method", "ysepay.online.trade.refund");
        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", "20210624093942672109163624997309");
        json.put("shopdate","20210624");
        json.put("refund_amount","0.01");
        json.put("refund_reason","退款测试");
        json.put("out_request_no",SerialGenerator.getOrder());
        json.put("trade_no", "01O210624735217626");

        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://openapi.ysepay.com/gateway.do",CommonUtil.mapToString(mapData));
        log.info("接口回执："+result);
        boolean resultVerify = false;
        //接口回执验签
        try{
            resultVerify = YsPaySignUtils.resultVerify(result,"ysepay_online_trade_refund_response");
        } catch (Exception e){
            log.info("验签异常："+e);
        }
        if(!resultVerify){
            log.info("验签失败");
        }
    }

8.附录

8.1 退款请求错误码