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

更新时间:2024.11.06

# 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文档

# 非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%,请确保业务已经覆盖完全,并且点击作废微信支付平台证书,至此变更完成

# 特殊情况说明

“平台证书切换微信支付公钥”的流程,不能和“灰度更换新平台证书”的流程同时进行,如果你正在灰度更换新的平台证书,系统将有下面提示,需要停止新平台证书的灰度更换(API安全-平台证书,进入查看平台证书灰度更换情况,请谨慎操作),才能继续进行当前流程。