在线支付系列【12】微信支付之Spring Boot集成官方SDK

迈不过友情╰ 2023-10-09 15:29 55阅读 0赞

> **有道无术，术尚可求，有术无道，止于术。**

#### 文章目录 ####

*   *  概览
     *  名词解释
     *   *  私钥
         *  证书
         *  商户API证书
         *  商户API私钥
         *  微信支付平台证书
         *  证书序列号
         *  API v3密钥
     *  证书与密钥时序图
     *  案例演示
     *   *  1. 环境搭建
         *  2. 加载商户私钥
         *  3. 配置类
         *  4. 签名验证器
         *  5. 构建HttpClient对象
         *  6. Native下单
         *  6. 查询订单
         *  7. 关单

### 概览 ###

为了帮助开发者调用开放接口，微信支付提供了`JAVA`、`PHP`、`GO`三种语言版本的开发库，封装了**签名生成、签名验证、敏感信息加/解密、媒体文件上传**等基础功能（更多语言版本的开发库将在近期陆续提供）。

[官网Github][Github]  
![在这里插入图片描述][03a53243ba394b5d87b5a4e72be6d280.png]

`wechatpay-apache-httpclient`是微信支付`API v3`的`Apache HttpClient`扩展，实现了请求签名的生成和应答签名的验证。使用`HttpClient`在执行请求时将自动携带身份认证信息，并检查应答的微信支付签名。

当前版本`0.4.9`为测试版本。请商户的专业技术人员在使用时注意系统和软件的正确性和兼容性，以及带来的风险。

若你使用的版本为`0.3.0`，升级前请参考[升级指南][Link 1]。

下面我们使用`wechatpay-apache-httpclient`进行案例演示。

### 名词解释 ###

#### 私钥 ####

数字签名通常定义了两种运算： **签名和验签**。

发送者用自己的私钥对消息的哈希值进行签名，接收者用对方的公钥进行验签。因此，在使用数字签名时，需要通信的双方都要事先生成公钥、私钥，并且完成双方的公钥交换。其中，私钥是只能由拥有者使用的不公开密钥，公钥是可以公开的密钥。

#### 证书 ####

由于公钥本身并不含有拥有者的身份信息，使用时无法确认它是真实有效的。所以需要证书**认证机构（简称 CA）在**核实公钥拥有者的信息后，将公钥拥有者的身份信息（如商户号、公司名称等），公钥、签发者信息、有效期以及扩展信息等进行签名，制作成“**证书**”。

为了符合监管的要求，保证更高的安全级别。《中华人民共和国电子签名法》、《金融电子认证规范》及《非银行支付机构网络支付业务管理办法》中规定 “**电子签名需要第三方认证的，由依法设立的电子认证服务提供者提供认证服务**。”，所以需使用第三方`CA`来确保数字证书的唯一性、完整性及交易的不可抵赖性。

#### 商户API证书 ####

`商户API证书`是用来**证实商户身份**的。证书中包含**商户号、证书序列号、证书有效期**等信息，由**证书授权机构**(`Certificate Authority` ，简称`CA`)签发，以防证书被伪造或篡改。如何获取请见[商户API证书][API]。

#### 商户API私钥 ####

商户申请商户`API证书`时，会生成**商户私钥**，并保存在本地证书文件夹的文件`apiclient_key.pem`中。

**注：不要把私钥文件暴露在公共场合。**

#### 微信支付平台证书 ####

`平台证书`是指由微信支付负责申请的，包含**微信支付平台标识、公钥信息的证书**。商户可以使用平台证书中的公钥进行应答签名的验证。

获取平台证书需通过[获取平台证书列表接口][API]下载。

商户在调用`API` 时用自身的私钥签名，微信支付使用**商户证书**中的公钥来验签。微信支付在响应的报文中使用自身的私钥签名，商户使用平台证书中的公钥来**验签**。

#### 证书序列号 ####

每个证书都有一个由CA颁发的唯一编号，即证书序列号。如何查看证书序列号请看[这里][Link 2]。

登陆商户平台`【API安全】->【API证书】->【查看证书】`，可查看商户API证书序列号。

商户API证书和微信支付平台证书均可以使用第三方的证书解析工具，查看证书内容。或者使用`openssl`命令行工具查看证书序列号。

$ openssl x509 -in 1900009191_20180326_cert.pem -noout -serial
    serial=1DDE55AD98ED71D6EDD4A4A16996DE7B47773A8C

#### API v3密钥 ####

为了保证安全性，微信支付在回调通知和平台证书下载接口中，对关键信息进行了`AES-256-GCM`加密。`API v3`密钥是加密时使用的对称密钥。商户可以在`【商户平台】->【API安全】`的页面设置该密钥。

### 证书与密钥时序图 ###

接下来，我们看下在交互时，商户和微信支付之间，是如何使用证书和秘钥的。

**商户向微信发起请求时：**

1.  用户使用申请**商户API证书**时发放的私钥计算签名，请求微信服务，微信使用商户的公钥进行验签。
2.  微信使用**微信平台私钥**计算签名，同步返回给商户，商户使用**微信平台公钥**验签。

**微信回调商户时：**

1.  微信进行签名，请求商户，商户收到回调后，使用**微信平台证书**中的公钥进行签名。

**下载平台证书请求时：**

1.  商户向微信发起请求时，互相签名、验签。
2.  互相签名、验签都没有问题，确保了双方之前身份的可信性。用户发起下载平台证书请求，并使用商户私钥签名，微信收到请求后，使用商户**商户API证书**中的公钥验签。
3.  微信返回**微信平台证书**，并使用`API v3密钥`对称加密，商户收到数据后，使用`API v3密钥`对称解密。

**交互敏感信息时：**

1.  用户发起敏感信息请求，使用**微信平台证书**中的公钥进行加密，微信收到后，使用对应私钥进行解密。
2.  微信返回敏感信息时，使用**商户API证书**中的公钥对数据加密，用户收到后，使用**商户API证书**时发放的私钥解密。

![在这里插入图片描述][f779ae9e4e28402f88d8f907b959ffb7.png]

### 案例演示 ###

#### 1. 环境搭建 ####

创建一个`Spring Boot` 工程，并加入依赖：

<dependency>
                <groupId>com.github.wechatpay-apiv3</groupId>
                <artifactId>wechatpay-apache-httpclient</artifactId>
                <version>0.4.9</version>
            </dependency>

#### 2. 加载商户私钥 ####

在申请**商户API证书**时，会生成`商户私钥`，并保存在本地证书文件夹的文件`apiclient_key.pem`中。商户开发者可以使用方法`PemUtil.loadPrivateKey()`加载证书。  
![在这里插入图片描述][df886aa08c8f4c50acef1baafcd346f0.png]  
`apiclient_key.pem`文件，就是一个字符串，我们可以通过加载文件，或者字符串的方式转为`私钥对象`。  
![在这里插入图片描述][262d4057d0b84e7caf7d458ee2551691.png]  
**代码示例：**

public class MchPrivateKeyUtils {
        
    
        /**
         * 通过私钥文件加载商户私钥
         *
         * @param path 私钥文件路径
         * @return 商户私钥
         * @throws IOException IO异常
         */
        public static PrivateKey loadPrivateKeyByPath(String path) throws IOException {
        
            return PemUtil.loadPrivateKey(
                    Files.newInputStream(Paths.get(path)));
        }
    
        /**
         * 通过私钥String字符串加载商户私钥
         *
         * @param keyStr 私钥字符串
         * @return 商户私钥
         * @throws IOException IO异常
         */
        public static PrivateKey loadPrivateKeyByStr(String keyStr) throws IOException {
        
            if (StrUtil.isEmpty(keyStr)) {
        
                throw new RemoteException("私钥字符串不能为空");
            }
            return PemUtil.loadPrivateKey(
                    new ByteArrayInputStream(keyStr.getBytes(StandardCharsets.UTF_8)));
        }
    
        public static void main(String[] args) throws IOException {
        
            PrivateKey privateKeyByPath = MchPrivateKeyUtils.loadPrivateKeyByPath("D:\\apiclient_key.pem");
            System.out.println("算法：" + privateKeyByPath.getAlgorithm()); // 打印为：RSA
            System.out.println("私钥：" + Base64.encode(privateKeyByPath.getEncoded()));
        }
    }

#### 3. 配置类 ####

添加属性配置类，读取微信所需**参数、秘钥、证书**等信息。

@Getter
    @Setter
    @ConfigurationProperties("pay.wechat")
    public class WechatPayProperties {
        
        /**
         * APPID
         */
        private String appId;
      
        /**
         * 商户号
         */
        private String merchantId;
    
        /**
         * 商户API证书序列号
         */
        private String merchantSerialNumber;
    
        /**
         * 商户私钥文件路径
         */
        private String privateKeyPath;
    
        /**
         * APIv3密钥
         */
        private String apiV3Key;
    }

在`application.yml`中添加相关配置。

pay:
      wechat:
        private-key-path: D:\\apiclient_key.pem
        api-v3-key: 填写APIv3密钥
        merchant-id: 填写商户号
        merchant-serial-number: 填写商户API证书序列号
        app-id: 填写APPID

添加一个配置类，用于注入相关`Bean`对象，并开启属性配置类。

@Configuration
    @EnableConfigurationProperties(WechatPayProperties.class)
    public class WechatPayConfig {
        }

#### 4. 签名验证器 ####

在之前用户和微信平台的时序图中，双方通信时，都需要进行双向的**签名验签**，所以在执行请求和接收响应时，需要提供一个签名验证器，用于签名和验签。

@Bean
        public Verifier verifier(WechatPayProperties wechatPayProperties) throws IOException, NotFoundException, GeneralSecurityException, HttpCodeException {
        
            // 加载商户私钥
            PrivateKey merchantPrivateKey = MchPrivateKeyUtils.loadPrivateKeyByPath(wechatPayProperties.getPrivateKeyPath());
            // 私钥签名对象（签名）
            PrivateKeySigner privateKeySigner = new PrivateKeySigner(wechatPayProperties.getMerchantSerialNumber(), merchantPrivateKey);
            // 身份认证对象（验签）
            WechatPay2Credentials wechatPay2Credentials = new WechatPay2Credentials(wechatPayProperties.getMerchantId(), privateKeySigner);
            // 获取证书管理器实例
            CertificatesManager certificatesManager = CertificatesManager.getInstance();
            // 向证书管理器增加需要自动更新平台证书的商户信息
            certificatesManager.putMerchant(wechatPayProperties.getMerchantId(), wechatPay2Credentials, wechatPayProperties.getApiV3Key().getBytes(StandardCharsets.UTF_8));
            // 从证书管理器中获取签名验证器
            return certificatesManager.getVerifier(wechatPayProperties.getMerchantId());
        }

#### 5. 构建HttpClient对象 ####

通过`WechatPayHttpClientBuilder`构建`HttpClient`对象，用于向微信发起请求，该对象会自动的处理签名和验签，并进行证书自动更新。

@Bean
        public CloseableHttpClient closeableHttpClient(Verifier verifier,WechatPayProperties wechatPayProperties) throws IOException {
        
            // 加载商户私钥
            PrivateKey merchantPrivateKey = MchPrivateKeyUtils.loadPrivateKeyByPath(wechatPayProperties.getPrivateKeyPath());
            // HttpClient构建者
            WechatPayHttpClientBuilder builder = WechatPayHttpClientBuilder.create()
                    .withMerchant(wechatPayProperties.getMerchantId(), wechatPayProperties.getMerchantSerialNumber(), merchantPrivateKey)
                    .withValidator(new WechatPay2Validator(verifier));
            // 构建HttpClient
            // 通过WechatPayHttpClientBuilder构造的HttpClient，会自动的处理签名和验签，并进行证书自动更新
            return builder.build();
        }

#### 6. Native下单 ####

创建一个测试类：

@SpringBootTest
    class PearlPayDemoApplicationTests {
        
    
        @Resource
        CloseableHttpClient httpClient;
    
        @Resource
        WechatPayProperties wechatPayProperties;
    }

调用微信支付`Native下单`接口，微信后台系统返回链接参数`code_url`，商户后台系统将`code_url`值生成二维码图片，用户使用微信客户端扫码后发起支付。

// Native下单：商户Native支付下单接口
        @Test
        void saveOrder() throws Exception {
        
            // 构建POST请求
            HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/pay/transactions/native");
            httpPost.addHeader("Accept", "application/json");
            httpPost.addHeader("Content-type", "application/json; charset=utf-8");
            // 使用JSON库，构建请求参数对象
            ByteArrayOutputStream bos = new ByteArrayOutputStream();
            ObjectMapper objectMapper = new ObjectMapper();
            ObjectNode rootNode = objectMapper.createObjectNode();
            rootNode.put("mchid", wechatPayProperties.getMerchantId()) // 直连商户号
                    .put("appid", wechatPayProperties.getAppId()) // 应用ID
                    .put("description", "Image形象店-深圳腾大-QQ公仔")// 商品描述
                    .put("notify_url", "https://www.weixin.qq.com/wxpay/pay.php") // 通知地址
                    .put("out_trade_no", "12177235656501201407031113368012");// 商户订单号
            rootNode.putObject("amount") // 订单金额对象
                    .put("total", 1); // 总金额，单位为分
            objectMapper.writeValue(bos, rootNode);
            httpPost.setEntity(new StringEntity(bos.toString("UTF-8"), "UTF-8"));
            // 执行请求
            CloseableHttpResponse response = httpClient.execute(httpPost);
            // 获取响应
            String bodyAsString = EntityUtils.toString(response.getEntity());
            System.out.println(bodyAsString); // {"code_url":"weixin://wxpay/bizpayurl?pr=dsuDtoyzz"}
        }

#### 6. 查询订单 ####

调用`商户订单号查询订单`接口：

@Test
        void selectOrder() throws Exception {
        
            URIBuilder uriBuilder = new URIBuilder("https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/12177235656501201407033233368019?mchid="+wechatPayProperties.getMerchantId());
            HttpGet httpGet = new HttpGet(uriBuilder.build());
            httpGet.addHeader("Accept", "application/json");
            CloseableHttpResponse response = httpClient.execute(httpGet);
            String bodyAsString = EntityUtils.toString(response.getEntity());
            System.out.println(bodyAsString); //
        }

返回结果：  
![在这里插入图片描述][77ee4205acb44ffa935d400d2324fb17.png]

#### 7. 关单 ####

@Test
        void closeOrder() throws Exception {
        
            HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/12177235656501201407033233368019/close");
            httpPost.addHeader("Accept", "application/json");
            httpPost.addHeader("Content-type","application/json; charset=utf-8");
            ByteArrayOutputStream bos = new ByteArrayOutputStream();
            ObjectMapper objectMapper = new ObjectMapper();
            ObjectNode rootNode = objectMapper.createObjectNode();
            rootNode.put("mchid",wechatPayProperties.getMerchantId());
            objectMapper.writeValue(bos, rootNode);
            httpPost.setEntity(new StringEntity(bos.toString("UTF-8"), "UTF-8"));
            CloseableHttpResponse response = httpClient.execute(httpPost);
            String bodyAsString = EntityUtils.toString(response.getEntity());
            System.out.println(bodyAsString); // {"code":"ORDERPAID","message":"该订单已支付"}
        }

[Github]: https://github.com/wechatpay-apiv3
[03a53243ba394b5d87b5a4e72be6d280.png]: https://img-blog.csdnimg.cn/03a53243ba394b5d87b5a4e72be6d280.png
[Link 1]: https://github.com/wechatpay-apiv3/wechatpay-apache-httpclient/blob/master/UPGRADING.md
[API]: https://wechatpay-api.gitbook.io/wechatpay-api-v3/ren-zheng/zheng-shu#shang-hu-api-zheng-shu
[Link 2]: https://wechatpay-api.gitbook.io/wechatpay-api-v3/chang-jian-wen-ti/zheng-shu-xiang-guan#ru-he-cha-kan-zheng-shu-xu-lie-hao
[f779ae9e4e28402f88d8f907b959ffb7.png]: https://img-blog.csdnimg.cn/f779ae9e4e28402f88d8f907b959ffb7.png
[df886aa08c8f4c50acef1baafcd346f0.png]: https://img-blog.csdnimg.cn/df886aa08c8f4c50acef1baafcd346f0.png
[262d4057d0b84e7caf7d458ee2551691.png]: https://img-blog.csdnimg.cn/262d4057d0b84e7caf7d458ee2551691.png
[77ee4205acb44ffa935d400d2324fb17.png]: https://img-blog.csdnimg.cn/77ee4205acb44ffa935d400d2324fb17.png