接入易错点

 未完成全部系统兼容改造不得开启切换

 说明：平台证书切换微信支付公钥的灰度期间，应答和回调可能分别使用平台证书或微信支付公钥；商户系统须同时兼容两种验签方式，且同一商户号下的全部项目都完成兼容后才可开启切换。 使用 wechatpay-java 时须升级至 0.2.15 及以上版本并采用 RSAPublicKeyConfig.Builder() 初始化请求客户端，旧版本及 RSAAutoCertificateConfig 不适用于纯公钥模式。
正确应该怎么做：① 先下载微信支付公钥及公钥 ID；② 在公共 HTTP 与验签组件中同时加载平台证书和微信支付公钥，并依据 Wechatpay-Serial 选择对应密钥；③ 为含敏感字段的请求增加公钥加密能力；④ 确认全部项目和业务链路支持两种模式后再点击“开始更换”；⑤ 若在灰度中发现异常，点击“停止更换”回到平台证书模式。
典型反例：代码仍只配置平台证书验签，却先发起了公钥切换；或只完成主交易链路，未覆盖公共组件和退费链路。
见 4012154180-如何从平台证书切换成微信支付公钥、4012925289-如何从平台证书切换成微信支付公钥、4013038816-常见问题、4013038589-常见问题、4013053249-如何使用微信支付公钥验签、4013053257-如何使用微信支付公钥加密敏感字段、4012153196-产品介绍、4012925323-微信支付公钥产品介绍（合作伙伴）、4013059017-如何使用微信支付公钥验签、4024350132-证书密钥概览 

 灰度期间可能因无法验证平台证书或公钥签名而出现接口异常、回调验签失败和业务处理中断；误开启后只能停止更换并重新排期；沿用平台证书初始化配置时还可能返回 RESOURCE_NOT_EXISTS 或 Invalid Wechatpay-Serial。 

 切换前须覆盖全部环境及历史退费链路

 说明：公钥灰度和切换按商户号维度进行，同一商户号用于多个项目或环境时须全部支持公钥；切换后的全部业务场景均应使用公钥，包括历史退款。应答使用公钥比例按近 7 天公钥调用次数除以近 7 天 V3 总调用次数计算。
正确应该怎么做：① 盘点共用同一商户号的生产、测试环境及全部应用；② 逐个接入公钥验签与公钥 ID 请求头；③ 单独核查历史退款、查询及其他低频链路；④ 全量改造后再启动切换，并等待统计更新；⑤ 检查是否仍有平台证书请求流量，直至应答比例达到 100%。
典型反例：只切换生产环境而遗漏测试环境；只覆盖新交易而让历史退款继续使用平台证书。
见 4012154180-如何从平台证书切换成微信支付公钥、4013038816-常见问题 

 应答公钥比例可能长期停留在 97% 或 99%，切换无法确认完成；遗留链路继续依赖平台证书，平台证书到期后会阻断对应 V3 业务。

 申请公钥后须在商户平台启用公钥切换

 说明：申请或下载微信支付公钥本身不会自动开启公钥模式，商户平台默认未启用公钥切换；代码完成改造后还需在商户平台启用，才能按公钥模式处理请求。 请求头须使用该商户号带 PUB_KEY_ID_ 前缀的真实公钥 ID，不能填写平台证书序列号或商户 API 证书序列号。
正确应该怎么做：① 先完成公钥验签、回调兼容和敏感字段加解密改造并部署；② 登录微信支付商户平台，进入「账户中心 → API 安全 → 微信支付公钥」，在「管理公钥」区域点击启用或设置并完成确认；③ 请求 Wechatpay-Serial 使用该商户号的真实公钥 ID；④ 调用前确认商户平台已显示公钥切换已开启。
典型反例：只在代码中下载了公钥、配置了公钥 ID 并发送 Wechatpay-Serial，却没有在商户平台启用，便认为接口已进入公钥模式。
见 4013038816-常见问题、4012154180-如何从平台证书切换成微信支付公钥、4013053257-如何使用微信支付公钥加密敏感字段、4012153196-产品介绍、4013053279-请求返回PARAM_ERROR「平台证书序列号Wechatpay-Serial错误」 

 即使请求头已经传了公钥 ID，仍可能返回 PARAM_ERROR，提示「平台证书序列号Wechatpay-Serial错误」，接口调用失败。 

 平台证书到期前须预留约14天切换窗口

 说明：回调使用公钥比例由微信支付在约7天内完成灰度，应答使用公钥比例按近7天 APIv3 调用次数统计，整体需要预留约14天。平台证书到期前未完成公钥切换，会导致 APIv3 应答和回调验签失败。 回调公钥灰度约需 7 天，应答公钥比例按近 7 天调用统计；平台证书临近到期时可选择切换微信支付公钥替代续期平台证书，但须倒排完整改造与灰度时间。
正确应该怎么做：① 先确认平台证书到期时间；② 倒排至少14天的切换窗口，先完成所有代码改造；③ 在商户平台开启公钥切换后，持续观察回调比例和应答比例；④ 两个比例均达到100%后及时确认切换，避免临近证书到期才开始操作。
典型反例：在平台证书到期前一周才启动公钥改造，未给7天回调灰度和7天应答统计留出时间。
见 4012154180-如何从平台证书切换成微信支付公钥、4013038816-微信支付公钥常见问题、4012153196-产品介绍、4012068814-产品介绍 

 平台证书过期时公钥灰度尚未完成，APIv3 应答和回调验签失败，支付结果无法确认，业务中断。

 平台证书灰度与公钥切换不得同时进行

 说明：平台证书替换为微信支付公钥与灰度更换新平台证书是两条互斥流程，不能同时进行。
正确应该怎么做：① 先在账户中心-API安全-平台证书查看是否正在灰度新证书；② 若正在灰度，先停止新平台证书灰度；③ 再按平台证书切换微信支付公钥的步骤启动公钥更换。
典型反例：为解决旧平台证书到期问题，一边启动新平台证书灰度，一边继续保留公钥切换流程。
见 4012154180-如何从平台证书切换成微信支付公钥、4013038816-常见问题 

 系统会提示流程冲突，公钥切换无法继续；若继续同时操作，还会增加两套切换状态难以确认的风险。

 公钥模式须使用公钥验签和敏感字段加密

 说明：微信支付公钥与平台证书是同一商户号用于 V3 验签和敏感字段加密的两种模式，新申请商户号默认为微信支付公钥模式；公钥模式下应使用公钥及公钥 ID，不以平台证书作为验签或加密凭据。 应答和回调须使用微信支付公钥及带 PUB_KEY_ID_... 前缀的公钥 ID 验签，上送敏感字段须使用同一公钥按 RSAES-OAEP 加密；商户请求签名仍使用商户 API 证书私钥（如 apiclient_key.pem），不得与微信支付公钥文件（如 pub_key.pem）混用。
；切换为公钥后，请求签名仍使用商户 API 证书私钥，回调报文解密仍使用 APIv3 密钥，二者不被公钥替换。
正确应该怎么做：① 使用商户 API 证书私钥生成商户请求签名；② 使用微信支付公钥验证微信支付应答和回调；③ 对上送敏感字段使用公钥按 RSAES-OAEP 加密；④ Go SDK 使用 option.WithWechatPayPublicKeyAuthCipher 初始化商户号、商户证书序列号、商户私钥、公钥 ID 和公钥；⑤ 删除平台证书自动下载及证书验签配置。
典型反例：已切换公钥模式，却在 SDK 中继续保留 AutoUpdateCertificatesVerifier 自动更新平台证书。
见 4012925323-产品介绍、4015419376-如何从微信支付公钥切换成平台证书、4013059017-如何使用微信支付公钥验签、4013059044-如何使用微信支付公钥加密敏感字段、4012153196-微信支付公钥产品介绍、4024350132-证书密钥概览、4012154180-如何从平台证书切换成微信支付公钥、4013053249-如何使用微信支付公钥验签、4013053257-如何使用微信支付公钥加密敏感字段、4016241880-验证微信支付响应的签名报错：签名验证失败、4013053279-平台证书序列号Wechatpay-Serial错误、4013053057-如何更换商户API证书？、4013080340-开发必要参数说明、4012081992-申请商户API证书、4012365342-总述-APIv3如何签名和验签 

 公钥模式下仍调用平台证书下载或初始化平台证书验签，会返回 RESOURCE_NOT_EXISTS，提示「无可用的平台证书，请在商户平台-API安全申请使用微信支付公钥」，导致 V3 接口无法正常调用；继续使用平台证书验签会报 Invalid Wechatpay-Serial，继续下载平台证书则可能返回 RESOURCE_NOT_EXISTS。 

 应答验签须按应答Wechatpay-Serial选择密钥

 说明：微信支付根据请求头Wechatpay-Serial携带的公钥ID或平台证书序列号选择应答签名方式，应答头会声明本次使用的标识。商户须按该标识选择微信支付公钥或平台证书验签。
正确应该怎么做：①预先加载当前商户号对应的平台证书和微信支付公钥，并按序列号或公钥ID建立映射；②读取应答头Wechatpay-Serial；③使用对应公钥验证原始应答报文、时间戳和随机串组成的签名串；④在灰度期同时保留平台证书和微信支付公钥两种验签能力。
典型反例：开始切换后把应答验签器固定为微信支付公钥，灰度期仍收到平台证书签名的应答时直接验签失败。
见 4012154180-如何从平台证书切换成微信支付公钥、4013053249-如何使用微信支付公钥验签 

 使用错误的公钥验证应答签名，应答验签失败，无法安全处理下单、查询等接口结果。

 灰度期回调须按Wechatpay-Serial兼容双验签

 说明：微信支付在回调灰度期间会随机使用平台证书或微信支付公钥签名，商户须根据回调请求头 Wechatpay-Serial 判断本次应使用哪种密钥验签。 切换期间应同时加载平台证书与微信支付公钥，并建立“平台证书序列号或公钥 ID 到密钥”的映射，按每次回调的 Wechatpay-Serial 选择验签材料；验签串须包含 Wechatpay-Timestamp、Wechatpay-Nonce 和原始请求体。
正确应该怎么做：① 将平台证书序列号映射到对应平台证书，将公钥 ID 映射到微信支付公钥；② 从每次回调的 Wechatpay-Serial 读取标识并选择对应密钥；③ 使用原始请求体构造验签串并完成 SHA256-RSA 验签；④ 验签失败时返回 4xx 或 5xx，等待微信支付重试；⑤ 灰度结束前不要移除平台证书兼容逻辑。
典型反例：回调处理只写死微信支付公钥，或只按证书序列号查找平台证书，未将 PUB_KEY_ID_ 开头的公钥 ID 纳入密钥映射。
见 4012154180-如何从平台证书切换成微信支付公钥、4013059017-如何使用微信支付公钥验签、4012925289-如何从平台证书切换成微信支付公钥、4013053249-如何使用微信支付公钥验签、4013038816-常见问题、4013053420-如何使用平台证书验签名、4015164042-微信支付公钥回调接口、4012075420-回调通知注意事项 

 灰度期间部分回调验签失败，商户返回 4xx 或 5xx 后微信支付会继续重试，支付结果、退款结果等业务状态可能无法及时处理；验签失败会报 notification parse failed: Validate notification failed, Invalid Wechatpay-Serial，支付或退款结果通知无法及时处理。 

 公钥模式回调须先验签再解密处理业务

 说明：微信支付公钥用于验证应答和回调签名，APIv3 密钥用于解密回调业务数据；仅解密成功不能证明通知来自微信支付。
正确应该怎么做：① 使用公钥文件、公钥 ID 和 APIv3 密钥初始化回调验签与解密组件；② Java SDK 可使用 RSAPublicKeyNotificationConfig，通过 NotificationHandler.parse 完成验签与解密；③ 仅在验签、解密均成功后执行订单或营销业务逻辑；④ 验签失败时返回 4xx 或 5xx，不得按正常通知处理。
典型反例：回调代码只解密 resource.ciphertext，解密成功便直接更新订单状态，没有验证请求头中的签名。
见 4013053249-如何使用微信支付公钥验签、4015164042-回调接口、4012075420-回调通知注意事项、4012072195-配置APIv3密钥、4012154180-如何从平台证书切换成微信支付公钥 

 被篡改或伪造的回调可能触发错误订单状态、营销核销或其他业务处理，造成业务和资金风险。

 签名探测流量须正常验签，不得特殊放行

 说明：微信支付会在少量应答或回调中生成错误签名，用于探测商户是否执行验签。探测签名不应对特殊处理，也不应按请求头识别后直接返回失败。
正确应该怎么做：①所有应答和回调统一进入正常验签流程；②不应以WECHATPAY/SIGNTEST/等特征跳过验签或直接放行；③应答验签失败时舍弃该应答，可按业务需要重试或让用户重新发起请求；④回调验签失败时返回4xx或5xx，等待微信支付重新通知。
典型反例：为了兼容迁移，将带探测标记或特定请求头的报文直接放行。
见 4013053249-如何使用微信支付公钥验签 

 未通过真实性校验的应答或回调可能被当作正常结果处理，支付结果和通知处理存在安全风险。

 全量使用公钥后须停止下载平台证书

 说明：接口 GET /v3/certificates 用于下载平台证书；商户已经全量使用微信支付公钥后，仍调用该接口会继续产生平台证书请求。 须同时排查显式调用 /v3/certificates、RSAAutoCertificateConfig、RSACombinedNotificationConfig、证书管理器、应用启动逻辑和定时任务中的平台证书同步。
正确应该怎么做：① 排查应用启动逻辑、证书管理器、回调解析器和定时任务中是否仍初始化平台证书或兼容配置；② 停止调用 /v3/certificates，移除平台证书自动下载逻辑；③ 确认没有残留平台证书流量后，持续观察应答使用公钥比例。
典型反例：业务已经改用公钥，但某个共享基础库或后台任务仍周期性下载平台证书，导致应答比例长期停在 0% 或不足 100%。
见 4012154180-如何从平台证书切换成微信支付公钥、4013038816-常见问题、4012551764-下载平台证书、4012925289-如何从平台证书切换成微信支付公钥（合作伙伴）、4013038589-微信支付公钥常见问题（合作伙伴） 

 应答使用公钥的比例无法达到 100%，公钥切换进度持续卡住，无法进入确认切换环节；平台证书下载请求继续计入 V3 调用，应答使用公钥比例无法提升，切换进度持续卡住。

 回调公钥比例达100%后须改用纯公钥通知配置

 说明：Java SDK 的 RSACombinedNotificationConfig 在回调切换期间会持续自动下载平台证书；回调灰度达到 100% 后应改为 RSAPublicKeyNotificationConfig。Go SDK 在确认不再依赖平台证书下载后，也应将组合验签器改为纯公钥验签器。
正确应该怎么做：① 切换期间使用组合验签配置同时验证平台证书和公钥；② 等待回调公钥比例达到 100%；③ 将通知配置改为纯公钥模式并移除平台证书自动下载流量；④ 观察应答公钥统计，确认不再因平台证书下载而卡住。
典型反例：回调已全部使用公钥，但通知处理仍保留组合验签配置，继续自动请求 /v3/certificates。
见 4012154180-如何从平台证书切换成微信支付公钥、4012925289-如何从平台证书切换成微信支付公钥、4013038816-常见问题、4012551764-下载平台证书、4013038589-常见问题 

 自动下载平台证书的请求继续计入 V3 调用，应答使用公钥的比例无法达到 100%，公钥切换流程无法完成。