接入易错点

 平台证书与微信支付公钥须择一使用

 说明：同一商户号的平台证书与微信支付公钥作用相同，用于验证微信支付应答、验证回调签名和加密敏感字段，长期使用时应择一作为验签模式；切换期间允许并存，但必须按 Wechatpay-Serial 同时兼容两种模式。
正确应该怎么做：① 先梳理商户号关联的全部系统，选择平台证书或微信支付公钥作为目标模式；② 若从平台证书切为公钥，先完成全部项目的双模式验签兼容，再执行公钥灰度并确认两个比例均为 100%；③ 若从公钥切回平台证书，先确认系统已停止使用公钥，再按官方流程配置安全联系人并生成平台证书。
典型反例：只完成一个项目的模式改造就在商户平台启动切换，其他项目仍固定使用原证书或原公钥验签。
见 4012068814-平台证书产品介绍、4012153196-微信支付公钥产品介绍、4012154180-如何从平台证书切换成微信支付公钥、4013038816-微信支付公钥常见问题、4015419357-如何从微信支付公钥切换成平台证书、4024350132-证书密钥概览 

 多项目仍使用不同模式且未按序列号路由时，APIv3 应答或回调会因证书与公钥不匹配而验签失败，支付流程受阻。

 V3应答与回调均须验证签名

 说明：APIv3 所有请求应答和回调通知都需要验签；请求使用商户 API 证书私钥签名，使用平台证书模式时，应答和回调使用平台证书验签。只验证请求签名、不验证应答或回调，无法确认消息来自微信支付且未被篡改。
正确应该怎么做：① 对每个 V3 应答校验 Wechatpay-Signature、Wechatpay-Timestamp、Wechatpay-Nonce 和原始报文主体，按 timestamp\nnonce\nbody\n 构造验签串；② 对每个回调通知执行同样的验签，验签通过后再解密和处理业务；③ 检查时间戳偏差，建议不超过 5 分钟；验签失败时拒绝该应答或返回失败等待重试。
典型反例：只实现了下单请求的签名，未验证微信支付应答和支付结果回调的签名。
见 4012068814-产品介绍、4012068829-平台证书更换操作指引、4012069411-常见问题、4012071382-如何解密回调报文和平台证书、4012072428-申请商户API证书、4012073044-合作伙伴平台证书产品介绍、4012073146-合作伙伴平台证书更换操作指引、4012073263-合作伙伴平台证书常见问题、4012075420-回调通知注意事项、4012076506-使用Java SDK、4012154180-如何从平台证书切换成微信支付公钥、4012365342-总述-APIv3如何签名和验签、4012365870-总述-APIv3如何签名和验签、4012551764-下载平台证书、4013038816-微信支付公钥常见问题、4013053420-如何使用平台证书验签名、4013059030-如何使用平台证书验签名、4015164042-回调接口、4024350132-证书密钥概览 

 回调真实性无法确认，存在伪造或篡改通知风险；验签缺失时异常回调可能被当作有效结果处理，造成订单状态错误。

 验签须按Wechatpay-Serial选择对应证书

 说明：平台证书轮换时新旧证书可能同时有效，微信支付在 APIv3 应答或回调请求头 Wechatpay-Serial 中声明本次签名所用平台证书序列号，商户须以该值查找对应平台证书完成验签，不能始终使用单张证书或只调用 getValidCertificate()。
正确应该怎么做：① 从每条应答或回调的 HTTP 头读取 Wechatpay-Serial；② 在本地证书池中按该序列号查找对应平台证书；③ 使用对应证书公钥验证签名；④ 若本地没有该序列号，先调用下载接口刷新证书池，再重新执行校验；⑤ 使用官方 SDK 时，确认其证书管理器和版本确实支持多证书缓存及按序列号动态验签。
典型反例：虽然支持多证书下载，但验签代码始终取当前有效证书或数据库中的唯一证书，不读取 Wechatpay-Serial。
见 4012068814-平台证书产品介绍、4012068829-平台证书更换操作指引、4012069411-常见问题、4012071382-如何解密回调报文和平台证书、4012073146-平台证书更换操作指引、4012073263-常见问题、4012076498-SDK概述、4012076506-使用 Java SDK、4012153196-微信支付公钥产品介绍、4012154180-如何从平台证书切换成微信支付公钥、4012365342-总述-APIv3如何签名和验签、4012365346-报错：HTTP header缺少微信支付平台证书序列号(Wechatpay-Serial)、4012551764-下载平台证书、4012715700-下载平台证书、4013038816-微信支付公钥常见问题、4013053249-如何使用微信支付公钥验签、4013053264-如何使用平台证书加密敏感字段、4013053420-如何使用平台证书验签名、4013059030-如何使用平台证书验签名、4013070756-开发必要参数说明、4015164042-回调接口、4016241880-验证微信支付响应的签名报错：签名验证失败、4024350132-证书密钥概览、wechatpay-apache-httpclient 

 验签失败，接口应答或回调无法正常处理；常见报错为 Cannot found the serial(... )'s configuration; which's from the response(header:Wechatpay-Serial)，支付和退款回调可能中断。 

 平台证书到期前须完成平滑切换

 说明：平台证书用于 APIv3 应答与回调通知验签，也用于部分接口敏感字段加密；每张平台证书有效期为 5 年，到期前必须更换。平台证书更换期间新旧两份证书同时有效，微信支付会按灰度比例使用其中一份签名，并在应答或回调的 Wechatpay-Serial 请求头中声明本次所用证书序列号，商户须用对应证书验签；也可按官方指引切换为无物理有效期的微信支付公钥。
正确应该怎么做：① 排查所有使用该商户号的 V3 业务系统，确认其已实现多平台证书验签，并能按 Wechatpay-Serial 选择对应证书；② 通过平台证书下载接口获取并保存全部有效期内的新旧平台证书，不要硬编码单张证书；③ 新证书下发并完成部署后，由超级管理员登录商户平台，进入「账户中心 → API安全 → 平台证书 → 管理证书」，开启手动灰度，先设置较小比例，观察业务正常后逐步提升至 100%，出现异常可随时终止灰度；④ 若评估不再使用平台证书，按「如何从平台证书切换成微信支付公钥」改造验签和敏感字段加解密，再在商户平台完成切换。
典型反例：始终使用单张固定平台证书验签；或未确认全部业务系统均已获取并部署新旧两份证书就开启灰度。
见 4012068814-产品介绍、4012068829-平台证书更换操作指引、4012069411-常见问题、4012071382-如何解密回调报文和平台证书、4012072428-申请商户API证书、4012073044-产品介绍、4012073146-平台证书更换操作指引、4012073263-常见问题、4012076524-平台证书下载工具、4012081606-APIv3概述、4012153196-微信支付公钥产品介绍、4012154180-如何从平台证书切换成微信支付公钥、4012551764-下载平台证书、4013053057-如何更换商户API证书、4013053420-如何使用平台证书验签名、4024350132-证书密钥概览 

 旧平台证书到期后，APIv3 应答与回调通知验签失败，敏感字段加解密异常，导致支付、退款、账单下载及相关回调处理中断；平台证书下载接口可能返回「平台证书已过期失效」及 NOT_ENOUGH。 

 同一商户号全部V3系统须统一适配换证

 说明：平台证书更换期间会同时存在新旧两份有效证书，系统需要能自动获取或部署多张证书，并根据报文中的 Wechatpay-Serial 选择对应证书验签；微信支付官方 SDK 已支持平台证书平滑切换。
正确应该怎么做：① 清点同一商户号下所有调用 APIv3 的系统，包括支付、退款、支付结果回调和敏感字段加解密链路；② 每个系统均实现定期更新平台证书，不硬编码单一证书；③ 保存有效期内的多张平台证书，并按 Wechatpay-Serial 路由验签；④ 使用官方 SDK 时，同时核对实际调用的 SDK 组件、版本和初始化方式；⑤ 所有系统完成改造并验证后，再生成或下发新平台证书并启动灰度；⑥ 若系统只能部署一份证书且无改造能力，只能按指引停服后一次性更换，应优先完成多证书改造。
典型反例：只升级主支付系统，其他独立服务仍固定使用旧平台证书，就启动整商户号灰度。
见 4012068814-产品介绍、4012068829-平台证书更换操作指引、4012069411-常见问题、4012551764-下载平台证书、4024350132-证书密钥概览 

 灰度切到新证书后，未完成改造的系统无法验签，支付应答、回调或退款处理会失败；采用单证书停服替换时，切换窗口内全部交易还会中断。

 仅支持单证书时须部署新证书后一次切换

 说明：系统不支持同时部署多张平台证书时，无法执行按 Wechatpay-Serial 选证验签的平滑切换，只能在停止服务期间一次性替换证书。
正确应该怎么做：① 优先改造为下载并缓存多张证书、按 Wechatpay-Serial 选择对应证书验签；② 确需使用单证书方案时，在业务窗口停止服务，部署新平台证书；③ 在商户平台启动灰度并直接设置 100%，确认微信支付全部使用新证书签名；④ 完成验证后再恢复服务。
典型反例：系统只能读取一份固定证书，却直接启动部分灰度，导致部分应答已改用新证书时本地仍只有旧证书。
见 4012068814-产品介绍、4012068829-平台证书更换操作指引、4012069411-常见问题、4012551764-下载平台证书、4013053420-如何使用平台证书验签名 

 新旧证书切换期间会出现验签失败；若在新证书尚未部署时让旧证书到期，系统会自动使用新证书签名，APIv3 支付、退款及回调处理会持续失败。

 APIv3密钥仅用于解密，不得替代验签

 说明：平台证书公钥用于验证微信支付应答和回调签名，APIv3 密钥仅用于解密回调业务密文及下载平台证书时返回的证书密文，两者用途不同。
正确应该怎么做：① 使用应答或回调头中的时间戳、随机串、原始报文及签名构造验签串，使用 Wechatpay-Serial 对应的平台证书公钥验证签名；② 签名验证通过后，再使用 APIv3 密钥按 AEAD_AES_256_GCM 解密回调通知的 resource 或平台证书下载结果；③ 不得以“已经能用 APIv3 密钥解开密文”代替消息真实性校验。
典型反例：回调代码只使用 APIv3 密钥解密通知资源，没有读取 Wechatpay-Serial、Wechatpay-Signature 等请求头，也未执行签名验签。
见 4012069411-平台证书常见问题、4012071382-如何解密回调报文和平台证书、4013053420-如何使用平台证书验签名、4024350132-证书密钥概览 

 无法校验消息来源和报文完整性；若误将 APIv3 密钥作为验签密钥，签名验证会失败，回调通知无法正常处理。

 重置APIv3密钥后须同步更新所有系统配置

 说明：APIv3密钥用于解密平台证书下载结果和V3回调通知；修改后应联系技术人员在所有相关服务中替换，并测试服务可用性。
正确应该怎么做：① 重置前盘点使用同一商户号的全部应用、环境和历史服务，并确认APIv3密钥的保存位置；② 暂停相关服务或安排维护窗口；③ 在商户平台修改APIv3密钥；④ 同步更新全部系统中的新密钥并验证平台证书下载、回调解密和业务处理；⑤ 无法找回原密钥时，按此流程重置，不得只修改其中一个系统。
典型反例：只更新主支付服务，遗漏回调服务或其他调用方；重置后仍让部分服务保留旧密钥。
见 4012071382-如何解密回调报文和平台证书、4012072195-配置APIv3密钥 

 旧密钥立即失效后，平台证书下载结果的解密、V3回调报文解密会失败，支付结果和退款通知无法处理。

 更换回调TLS根证书后须提前验证回调

 说明：微信支付支持GlobalSign Root R46根证书；商户更换支付及退款回调服务所使用的TLS根证书前，应使用新的回调URL验证兼容性，测试由商户侧完成。
正确应该怎么做：准备承载新根证书链的回调URL，分别验证支付结果通知与退款结果通知能够完成HTTPS连接、签名验证及业务应答，再切换生产回调服务。 

 根证书兼容性不满足时，支付或退款回调无法正常到达商户，支付成功后的订单出票、发货或退款状态更新受阻。

 商户API证书不区分APIv2和APIv3版本

 说明：商户 API 证书用于证实商户身份，同一份证书可用于 APIv2 和 APIv3 接口；区分版本的是接口路径和 API 密钥。
正确应该怎么做：① 在【账户中心-API安全-商户API证书】申请或更新证书；② 按接口版本配置 APIv2 或 APIv3 密钥；③ 证书到期前更换。
典型反例：为兼容旧系统另行申请“v2 证书”，或认为 APIv3 证书不能用于 v2 接口。
见 4012072428-申请商户API证书、4012072195-配置APIv3密钥 

 误以为缺少证书而阻塞联调，或把证书与密钥版本混用导致签名失败。

 商户API证书私钥须妥善保管且丢失无法找回

 说明：商户API证书私钥apiclient_key.pem只能通过证书工具导出，丢失后无法重新下载或找回，只能作废原证书并重新申请。
正确应该怎么做：① 申请新API证书后，将证书和私钥交由技术人员部署；② 私钥存入密钥管理或受限配置，禁止提交到Git、写入客户端代码或暴露在公共场合；③ 限制访问权限并保留交接记录；④ 怀疑泄露或丢失时，立即在商户平台作废原证书并申请新证书，完成部署后验证APIv3请求签名。
典型反例：将apiclient_key.pem提交到代码仓库或写入客户端代码；或只备份证书文件而未单独保管私钥。
见 4011985891-安全规范、4012072428-申请商户API证书、4012365345-报错：商户证书序列号有误。请使用签名私钥匹配的证书序列号、4012365347-状态码401或签名验签失败、4012551764-下载平台证书、4013053057-如何更换商户API证书、4013058943-服务商如何更换商户API证书、4013070756-开发必要参数说明、4024350132-证书密钥概览 

 私钥丢失后无法生成APIv3请求签名，支付、退款等接口无法调用；必须作废原证书并重新申请、部署，期间业务可能中断。

 同一商户号最多同时生效3份商户API证书

 说明：一个商户号最多可同时生效 3 份商户API证书，机构号同样最多支持 3 张，旧证书在有效期内且未作废时可继续使用；新增证书会挤占有效名额，影响已有证书的有效性。
正确应该怎么做：新增或轮换商户API证书前先检查当前有效证书数量；需要新增时申请新证书并替换代码中的证书私钥和证书序列号，在确认旧证书调用量归零后再作废旧证书；④ 证书更换后在灰度或监控中确认全部调用方已切换到仍在有效期内的证书。
见 4012072428-申请商户API证书、4013053057-如何更换商户API证书？、4024350132-证书密钥概览 

 超过同时生效数量后无法继续新增商户API证书，证书轮换流程受阻；新增证书后原有证书被挤出有效名额，使用旧证书的下单、查单等接口调用失败，影响线上交易。

 作废商户API证书后七日内可恢复

 说明：商户 API 证书自作废之日起 7 日内仍可由商户号超级管理员取消作废并恢复使用，超过该期限后不能再恢复。
正确应该怎么做：① 作废前先申请并部署新证书，核对旧证书调用量是否归零；② 如需验证旧证书是否仍被业务使用，可作废后在 7 日内观察并随时恢复；③ 超级管理员登录商户平台【账户中心-账户设置-API安全-管理证书】，点击对应证书的“恢复”并完成安全验证。
典型反例：未先保留新证书和回退窗口便直接作废，随后发现仍有旧证书调用但已超过可恢复期限。
见 4013053057-如何更换商户API证书？ 

 超过 7 日后旧商户 API 证书无法恢复，只能重新申请并部署证书；仍使用旧证书的服务会持续调用失败。