平台证书切换微信支付公钥指引

更新时间：2024.07.24

# 为什么需要商户修改

首先你需要知道平台证书是用于验证微信支付的身份，微信支付使用平台证书私钥签名，商户验签，点击查看什么是平台证书 (opens new window)。

微信支付平台证书有5年的有效期。新旧平台证书的更换，会给商户带来额外的可用性风险和切换成本。因此，你可以选择采用微信支付公钥代替平台证书。

# 什么样的商户需要修改

使用微信支付APIv3的商户。

# 哪些场景需要商户修改

需要商户修改的场景：

在微信支付平台证书切换微信支付公钥过程中，商户同时持有微信支付平台证书和微信支付公钥。

请求场景：商户需要在请求头中携带微信支付公钥ID请求微信支付系统，微信支付会使用请求头中商户指定的微信支付私钥进行签名；

1.1 请求场景中敏感字段的加密同样要根据请求头中指定的微信支付公钥ID使用微信支付公钥进行加密，如果指定了微信支付平台证书序列号则使用微信支付平台证书公钥加密。
回调场景：商户需要同时支持使用微信支付平台证书和微信支付公钥的验签；

微信支付公钥使用可参考公钥使用文档 (opens new window)。

# 商户如何修改

商户平台证书切换微信支付公钥过程如下：

商户到商户平台申请微信支付公钥，获取微信支付公钥文件及微信支付公钥ID；
请求和回调场景需要作以下修改：

2.1 请求场景：需要商户在HTTP请求头中的Wechatpay-Serial字段携带微信支付公钥ID或微信支付平台证书序列号请求微信支付系统：
- 2.1.1 使用SDK的商户可参考新版SDK文档使用微信支付平台证书和微信支付公钥共同初始化NotifyHandler类。SDK初始化示例：
```
1// 初始化 notify.Handler
2handler := notify.NewNotifyHandler(mchAPIv3Key,verifiers.NewSHA256WithRSACombinedVerifier(certificateVisitor, wechatpayPublicKeyID, *wechatPayPublicKey))
```
- 2.1.2 未使用SDK的商户需要在请求头中修改Wechatpay-Serial字段为公钥ID或平台证书序列号；
  - 携带公钥ID请求头示例：
```
1curl -X GET \
2https://api.mch.weixin.qq.com/v3/xxx \
3-H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4-H "Accept: application/json" \
5-H "Wechatpay-Serial: PUB_KEY_ID_00000000000000000000000000000000" // 微信支付公钥ID带有PUB_KEY_ID_前缀
```
  - 携带微信支付平台证书序列号请求头示例：
```
1curl -X GET \
2https://api.mch.weixin.qq.com/v3/xxx \
3-H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4-H "Accept: application/json" \
5-H "Wechatpay-Serial: 5157F09EFDC096DE15EBE81A47057A7232F1B8E1"
```
2.2 回调场景：需要商户兼容微信支付平台证书和微信支付公钥两种验签模式，如果商户请求头中Wechatpay-Serial字段指定使用微信支付平台证书序列号，则使用微信支付平台证书验签；否则应使用微信支付公钥验签；
商户到商户平台调节回调场景灰度比例：即微信支付使用微信支付平台证书和微信支付私钥签名的回调请求比例；