1.Java接入银联支付(chinapay)教程及避坑点

川长思鸟来 2024-03-16 21:05 65阅读 0赞

#### 一、背景及效果展示 ####

现如今，诸多的供应链系统需要使用电子钱包功能，所以接入银联B2B无卡支付，是很多系统应用需要做的事情。银联支付的类型分很多种：网关支付（带token请求实现，下次有空再分享）、B2B无卡支付（带证书秘钥请求实现）分商户和机构入网，具体和更详细的内容可以去看中国银联开放平台，今天这里主要针对于企业中所涉及的的B2B无卡快捷支付做介绍与讲解。

#### 二、B2B快捷支付流程 ####

![在这里插入图片描述][5034b1f8631142bd9a76ec4339957a90.png_pic_center]

此流程图在商户接入手册中有展示，可以在文档中详细查看

##### 2.1 B2B支付流程介绍 #####

![在这里插入图片描述][f747abc00b4d48b284d544f140adc4d3.png_pic_center]

我们正常做的B2B支付对于银联来说，即是前台支付(B2B业务中都是前台支付)，后台支付不用管。

###### 整体流程走向： ######

1.通过后端先将支付请求的参数构建好并返回给到前端，前端请求银联的前台支付地址；

2.前端处理银联的响应信息(银联返回的是页面，可新开页签)，后续到支付流程都是银联侧；  
![在这里插入图片描述][4d5b2de001cb4aa58969658b8abc395a.png_pic_center]

\*\*注：\*\*此处没有进行银行的选择，是在进行支付请求时传递了银行的机构码，银联的网关前置功能会自动跳转至对应的银联支付页面

3.填写银行卡密码等信息，填写完成后点击支付

4.支付完成后，银联会回调我们的后端回调接口或前端页面(前端页面回调地址可不传，采用手动关闭银联的页面)

5.接收到银行的支付回调信息后，主动调 **交易查询接口** 进行当前订单的支付状态

6.对支付回调信息与交易查询的响应信息进行处理，判断支付状态，进行后续的业务操作

\*\*后续(退款类)\*\*交易接口与支付流程基本一致，不过后续(退款类)交易接口是直接通过后端完成即可

#### 三、前置工作 ####

当接入银联无卡支付的时候，会有银联的对接人给你们申请，通过邮件发送开发所需的文件，如下：  
![在这里插入图片描述][c4a7c33f1ef44af580605495e5e38c01.png_pic_center]

1、开发文档ChinaPay新一代商户接入手册\_20220616.pdf

2、公钥证书 CP.rar，需要解压此rar文件

3、usexxx.zip，私钥和密码压缩包，需解压后，生成私钥xxxxxxxx.sm2和密码

4、插件包，里面提供了Java、.net、C和PHP的插件包，java核心jar包就是chinapaysecure-sm-1.0.jar，通过此jar中的方法进行签名的生成、验签，加密解密  
![在这里插入图片描述][dbef860e0e904af79edb96bef86e07a1.png_pic_center]

5、需要联系银联的对接人员开通B2B支付的测试账号

6、让银联方配置测试ip白名单，固定的对外IP

\*\*注：\*\*如果确实需要银联方提供demo参考(不建议)，可让对接人员提供，demo本身基于servlet + jsp构建的eclipse项目，注释也很少，有问题建议直接跟银联方沟通，确认好自己的需求，效率会高很多。

#### 四、正式接入 ####

##### 4.1 新建私钥及证书配置文件 #####

在当前项目下，新建security.properties文件，配置好对应的公私钥及密码等信息

#报文中不参与签名的字段名称，多个字段用逗号进行分隔
    sign.invalid.fields=Signature,CertId
    #报文中签名的字段名称
    signature.field=Signature
    #是否输出调试日志,true输出，其他只输出错误日志
    log.info=false
    #私钥算法
    secss.privateAlg=SM2
    #私钥路径
    secss.privatePath=/xxx/xxx.sm2
    #私钥密码
    secss.privatePwd=a111111
    #公钥算法
    secss.publicAlg=SM2
    #公钥路径
    secss.publicPath=/xxx/xxx.cer
    #是否排除过期秘钥
    secss.excludeExpiredCert=true

注：公私钥路径最好采用文件的绝对路径

##### 4.2 引入chinapaysecure-sm-1.0.jar #####

项目中使用maven或gradle进行依赖管理时，可先将此jar包解压至本地仓库，后通过maven的gav坐标将其引入(gradle引入依赖与此类似)

<dependency>
    	<groupId>com.unionpay</groupId>
    	<artifactId>chinapaysecure-sm</artifactId>
    	<version>1.0</version>
    </dependency>

注：如果maven仓库是采用的私服仓库，上传了这个jar后，如果项目中无法获取，需要检查仓库的更新策略，具体可以联系公司内的相关人员进行处理

##### 4.3 代码接入 #####

4.3.1 核心工具类 SecssUtil 初始化

@Slf4j
    @Configuration
    public class SecssConfig {
        
    
        @Value("${china.pay.securityUrl}")
        private String securityUrl;
    
        @Bean
        public SecssUtil init(){
        
            //执行secss初始化
            SecssUtil secssUtil = new SecssUtil();
            boolean bool = secssUtil.init(securityUrl);
            if (bool) {
        
                log.info("ChinaPay交易证书、验签证书初始化成功！");
            } else {
        
                log.error("ChinaPay交易证书、验签证书初始化失败："+secssUtil.getErrCode() + "=" + secssUtil.getErrMsg());
            }
            return secssUtil;
        }
    
    }

4.3.2 构建支付请求参数

@Autowired
    private SecssUtil secssUtil;
    
    private TreeMap<String,Object> buildPayParams(SendPayReq payReq){
        
            TreeMap<String,Object> req = new TreeMap<>();
            req.put(Constants.VERSION,Constants.REQUEST_VERSION);
            req.put(Constants.MER_ID,merId);
            req.put(Constants.MER_ORDER_NO,payReq.getPayOrderId());
            req.put(Constants.TRAN_DATE, TimeUtil.date2String(LocalDate.now()));
            req.put(Constants.TRAN_TIME,TimeUtil.time2String(LocalTime.now()));
            //元转分
            Long orderAmt = payReq.getRemitterAmt().multiply(new BigDecimal(100)).longValue();
            req.put(Constants.ORDER_AMT,orderAmt.toString());
            req.put(Constants.BUSI_TYPE,Constants.BUSINESS_TYPE);
            //req.put("BankInstNo", param.getAccCode()); // 支付机构号-银联在线支付(这个参数必填，如果是无卡支付前端请求，否则会失败)
            //req.put("TranType",Constants.PAY_TRAN_TYPE);
            //支付接口后端回调地址
            req.put(Constants.MER_BG_URL,backPayUrl);
            //付款支付完成后跳转至的系统前台展示地址
            if (StringUtils.isNotEmpty(payReq.getMerPageUrl())){
        
                req.put("MerPageUrl",payReq.getMerPageUrl());
            }
            req.put(Constants.REMOTE_ADDR,remoteAddr);
            secssUtil.sign(req);
            log.info("支付交易签名响应is {}，信息 {}",secssUtil.getErrCode(),secssUtil.getErrMsg());
            String sign = secssUtil.getSign();
            req.put(Constants.SIGNATURE,sign);
            return req;
       }

4.3.3 接收支付回调

支付完成后，银联会回调我们的这个接口，具体内容及接收方法课看下第五大点中的5.3回调接口

4.3.4 构建交易查询接口参数

/**
         * 构建银联商务交易查询参数
         * @param param
         * @return
         */
        private TreeMap<String,Object> buildQueryPayParams(AccountStorageQueryReq param){
        
            TreeMap<String,Object> req = new TreeMap<>();
            req.put(Constants.VERSION,Constants.REQUEST_VERSION);
            req.put(Constants.MER_ID,merId);
            req.put(Constants.MER_ORDER_NO,param.getPayOrderId());
            req.put(Constants.TRAN_DATE, param.getOriTranDate());
            req.put(Constants.TRAN_TYPE,Constants.QUERY_TRAN_TYPE);
            req.put(Constants.BUSI_TYPE,Constants.BUSINESS_TYPE);
            secssUtil.sign(req);
            log.info("商务交易签名响应is {}，信息 {}",secssUtil.getErrCode(),secssUtil.getErrMsg());
            String sign = secssUtil.getSign();
            req.put(Constants.SIGNATURE,sign);
            return req;
        }

#### 五、注意点 ####

##### 5.1 参数类型 #####

在向银联发起支付、交易查询、退款类等请求时，虽说文档中每个字段类型各异，但实际上所有参数都是string类型

##### 5.2 字段解密 #####

如果需要对银行的返回信息中某个字段需要进行解密时，需要先注意下返回的加密信息是否含有 “%”，如果含有，则需要先通过url解码对字符串解码，去除该特殊符号，然后继续采用解密方法进行解密

import java.net.URLDecoder;
    
    public String getDecData(String encData){
        
            try {
        
                //对加密内容进行url解码
                String cardTranData = URLDecoder.decode(encData, Charsets.UTF_8);
                //调用核心类方法进行解密
                secssUtil.decryptData(cardTranData);
                //获取解密后的内容
                String cardData = secssUtil.getDecValue();
                if (StringUtils.isNotEmpty(cardData)){
        
                    Map map = JSONObject.parseObject(cardData, Map.class);
                    return (String)map.get("CardNo");
                }else {
        
                    return "";
                }
            }catch (Exception e){
        
                log.warn("银行账户字段解签错误");
                return "";
            }
      }

##### 5.3 回调接口 #####

我们接收银联回调的接口，地址需要能直接被银联方访问到，(公网地址，并配置银联的白名单)。采用HttpServletRequest接收参数，并用获取paramMap方法拿到所有的响应参数内容

/**
         * 银联支付接口异步回调
         * @return
         */
    @PostMapping("/")
    public ApiResult<Void> payCallback(HttpServletRequest request){
        
        Map<String, String[]> parameterMap = request.getParameterMap();
        log.info("4.1支付异步回调响应信息 is {}",parameterMap);
        if (CollectionUtils.isEmpty(parameterMap)){
        
            return ApiResult.fail("4.1支付异步回调响应信息为空");
        }
        return ApiResult.ok();
    }

##### 5.4 请求参数签名 #####

银联构建的所有参数都需要进行签名(签名字段本身除外)，然后一起组装到请求参数中，发送至银联的对应接口

public String getSign(TreeMap<String,Object> req){
        
            secssUtil.sign(req);
            log.info("待签名信息is {}，签名响应: {}",secssUtil.getErrCode(),secssUtil.getErrMsg());
            String sign = secssUtil.getSign();
            return sign;
      }
    联的对应接口
    
    ```java
    public String getSign(TreeMap<String,Object> req){
        
            secssUtil.sign(req);
            log.info("待签名信息is {}，签名响应: {}",secssUtil.getErrCode(),secssUtil.getErrMsg());
            String sign = secssUtil.getSign();
            return sign;
      }

[5034b1f8631142bd9a76ec4339957a90.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/8ce6c1bfca004dbea7612466ae0a234a.png
[f747abc00b4d48b284d544f140adc4d3.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/690a943d0ca24d9980ee9243b10ad4b2.png
[4d5b2de001cb4aa58969658b8abc395a.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/21ffd2c3691944758631427f3338b168.png
[c4a7c33f1ef44af580605495e5e38c01.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/26a9c444912c4b89aaa94e89819a9d98.png
[dbef860e0e904af79edb96bef86e07a1.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/6cc22bcb81f14bf293a430e9e0fce849.png