微信支付 V3(APIv3)比 V2 安全、规范,但刚接入时最容易在证书和签名上反复踩坑。这篇把最容易出错的环节一次讲透。

微信支付 V3 接入四步流程:第一步分清三把钥匙,APIv3 密钥用于解密、商户私钥用于签名、平台证书用于验签;第二步构造签名串,HTTP 方法、请求 URL、时间戳、随机串、请求体五行换行拼接后做 SHA256-RSA 签名;第三步回调验签解密,先用微信平台证书验签,再用 APIv3 密钥做 AES-256-GCM 解密;第四步幂等与应答,按商户订单号去重只处理一次,成功后返回 200 与 SUCCESS。
微信支付 V3 接入四步:钥匙 → 签名 → 验签解密 → 幂等应答

一、先分清三把「钥匙」

微信支付 V3 三把密钥/证书的用途对照
钥匙谁给的用来做什么
APIv3 密钥商户平台自己设置,32 位解密回调和敏感字段,不参与请求签名
商户 API 证书自己申请,私钥 + 证书请求签名用私钥签,微信用你的证书验
微信支付平台证书微信下发验证响应和回调的签名,需定期下载更新
最常见的错误:把 APIv3 密钥当成签名密钥,或者用错平台证书。记住——签名用商户私钥,验签用微信平台证书,解密回调用 APIv3 密钥。

二、签名串的构造顺序

签名串由五行内容按固定顺序拼接,再对整串做 SHA256-RSA 签名,放进 Authorization 头。这五行分别取什么、怎么排、换行符用哪种,是签名失败的头号来源——顺序、空格或换行错一个字符,接口只会返回一个笼统的签名错误,不会告诉你是哪一行出的问题。

知道要拼五行,和真的拼对,是两件事。定位靠逐项比对,不靠猜:时间戳是否秒级、请求 URL 是否带完整 query、请求体的序列化是否与签名时一致、换行符是否统一。这四项目前只能靠经验排,我们把常见的错误组合整理成了对照表,放在技能里。

三、回调验签与解密

  1. 先用微信平台证书验证回调头里的签名,确认这真是微信发来的。
  2. 验签通过后,用 APIv3 密钥对 resource.ciphertext 做 AES-256-GCM 解密,拿到支付结果明文。
  3. 必须做幂等:同一笔支付结果微信可能重试推送多次,用商户订单号去重,只处理第一次成功。
  4. 处理成功后按要求返回 200 与 {"code":"SUCCESS","message":"成功"},否则微信会一直重试。
这四步的顺序不能颠倒:先验签再解密,解密完再做幂等。顺序错的表现往往不是报错,而是数据看着对、实际重复入账,等对账时才发现。

四、高频报错对照

微信支付 V3 高频报错、常见原因与处理方式对照
现象常见原因怎么处理
签名错误时间戳不是秒级;请求 URL 没带完整 query;五行拼接的换行不对三处逐项核对,顺序和换行错一个字符都会失败
证书过期或不匹配平台证书有有效期,到期未轮换定时轮换,建议接平台证书自动下载
回调收不到回调地址不是公网 HTTPS,或外网访问不通、证书不受信任三项逐项验,缺一项都收不到
上面这些是判断,帮你定位问题出在哪一环;真正落地还差执行:可直接调用的签名实现、回调验签与解密的完整代码、三十多条真实报错与对应改法、平台证书自动轮换的定时任务。这些我们做成了一个可买断的 AI 技能,把报错信息丢给它,会直接告诉你卡在哪一步、怎么改。技能已经上架,拉到页面底部点那张卡片,微信支付 19 元,付完当场就能看全部内容,不用等审核。