平台证书切换微信支付公钥指引
更新时间：2024.12.20# 1.背景
APIv3依赖平台证书进行签名验签，该证书每五年需商户主动更换一次。为避免更换不及时或过程中出现的系统风险影响业务，建议商户将模式切换为公私钥模式。
# 2.什么商户需要修改
- 微信支付APIv3接口需要用到平台证书签名验签、加解密，需要切换。
- 微信支付APIv2接口不涉及平台证书，无需切换。
# 3.哪些场景需要修改
- API v3的请求应答场景、回调场景、敏感字段加解密场景都使用到平台证书，因此都需切换成公私钥模式。
- 【平台证书切换微信支付公钥】的流程不能和【灰度更换新平台证书】的流程同时进行，具体参考文末【特殊说明章节】
# 3.1请求应答场景
请求场景，商户需要使用商户API证书私钥生成签名，微信支付会使用商户的API证书公钥验证签名，该部分不涉及平台证书，但商户需要在发起请求时通过http请求头的Wechatpay-Serial告知微信支付当前请求将使用平台证书还是微信公钥来验签名，具体的操作步骤参考本文4.2的切换部分。
应答场景，在平台证书模式，微信支付会使用平台证书私钥生成签名，商户需要用平台证书私钥验证签名。因此应答场景需要商户使用微信支付公钥来替换平台证书，具体的操作步骤参考本文4.2的切换部分
# 3.2回调场景
回调加密：微信支付会使用apiv3密钥加密回调信息，商户需要用apiv3密钥解密回调信息，该部分不涉及平台证书，商户无需修改。
签名验签：在平台证书模式，微信支付会使用平台证书私钥生成签名，商户需要用平台证书公钥验证签名，因此回调验签场景需要商户使用微信支付公钥来替换平台证书，具体的操作步骤参考本文4.2的切换部分
# 3.3敏感字段加解密场景
敏感信息上送：在平台证书模式，商户需要使用平台证书公钥加密敏感信息，例如姓名等，微信支付会使用平台证书私钥解密敏感信息。该场景需要商户使用微信支付公钥来替换平台证书，具体的操作步骤参考本文的切换部分
敏感信息接收：微信支付会使用商户API证书公钥加密敏感信息回传给商户，商户需要使用商户API证书私钥解密，该部分不涉及平台证书，商户无需修改。
# 4.如何将平台证书模式切换为公私钥模式
# 4.1获取公钥文件
如果你是商户，请登录商户平台 (opens new window)（需要超级管理员或者安全联系人登录，安全联系人可由超管在安全中心-安全联系人设置），进入账户中心-API安全，找到“微信支付公钥”，点击申请公钥
如果你是服务商，请登陆合作伙伴平台 (opens new window)（需要超级管理员或者安全联系人登录，安全联系人可由超管在安全中心-安全联系人设置），进入账户中心-API安全，找到“微信支付公钥”，点击申请公钥
| （1）帐户中心->API安全 | （2）微信支付公钥入口页面 |
|---|---|
 |  |
| （3）下载微信支付公钥 | （4）得到公钥文件和公钥ID（公钥序列号） |
|---|---|
 |  |
# 4.2按场景将平台证书切换到公私钥模式
# SDK场景
如果你使用了微信支付SDK，SDK已经实现了请求应答、回调、敏感信息加解密，可参考以下说明，并阅读对应sdk的readme文档
- Java (opens new window)的SDK请升级至0.2.14 及以上版本
- PHP (opens new window) SDK
- go (opens new window) SDK请升级至0.2.20 及以上版本
# 非SDK场景
商户将平台证书切换到公私钥模式的过程中，建议通过逐步灰度控制切换的范围，因此切换过程中你需要实现同时兼容平台证书模式和公私钥模式，切换完成可以只支持公私钥模式，具体切换参考本章节的按场景切换的具体说明。
# （1）请求应答场景
所有的请求都需要自行通过http头部的Wechatpay-Serial告知微信支付本次请求将使用公钥还是平台证书来验签，微信支付会根据这个字段来选择要使用公钥还是平台证书来加签。如下图
- 携带公钥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）回调场景
启动灰度后，微信支付会在7天内，逐步用微信支付私钥生成回调的签名，商户需要通过微信支付返回的http请求头的Wechatpay-Serial来确定具体的模式，详细可参考如下图说明
# （3）敏感字段加解密场景
敏感字段加解密场景，商户在发起请求的时候使用公钥加密敏感信息，并且在发起请求的商户在http请求头带上Wechatpay-Serial 告知微信支付本次使用的是公钥加密
# （4）商户平台点击更换验签方式
完成了以上场景的开发之后，商户可以在商户平台点击“开始更换”，页面会区分回调、请求应答两个进度条分别展示切换进度。
- 如上文描述回调的灰度切换进度由微信支付自动控制，在7天左右完成；
- 请求应答的切换进度由商户通过http的Wechatpay-Serial来控制
- 若你的系统出现故障，可以点击“停止更换”，停止后将全部切换回平台证书，请谨慎操作
# （5）完成切换，作废平台证书
当你所有业务场景的请求已经携带了公钥ID，且经过7天回调灰度后，你可以在商户平台看到【回调使用公钥比例】和【应答使用公钥比例】都为100%，请确保业务已经覆盖完全，并且点击作废微信支付平台证书，至此变更完成
# 特殊情况说明
在请求应答场景下，若商户未在http头部传入Wechatpay-Serial，微信支付则默认使用平台证书加签
“平台证书切换微信支付公钥”的流程，不能和“灰度更换新平台证书”的流程同时进行，如果你正在灰度更换新的平台证书，系统将有下面提示，需要停止新平台证书的灰度更换（API安全-平台证书，进入查看平台证书灰度更换情况，请谨慎操作），才能继续进行当前流程。
