h5_url 只活 5 分钟、回调应答只有 5 秒:微信支付 H5 接入的两条硬约束
微信支付《开发接入检查用例_H5 支付》(更新 2026-11-18)和《接入易错点_平台证书》(更新 2026-10-30)里,和时间、顺序直接相关的要求有两条:H5 下单拿到的 h5_url 有效期 5 分钟,支付成功回调必须在 5 秒内先验签再应答。前者错了用户付不了款,后者错了会重复收到通知甚至被判定回调失败。
h5_url 的 5 分钟是链接有效期,不是支付时限
用例项 recreate_order_when_h5_url_expires 说得很明确:h5_url 有效期为 5 分钟,超时须用原下单参数重新下单。这里的 5 分钟限制的是跳转链接本身,不是要求用户在 5 分钟内完成付款。用户拿到链接后慢慢付,没问题;但链接本身过了 5 分钟就废了。
正确做法两条:
- 用户实际点「去支付」时再调 H5 下单接口拿
h5_url,不要提前批量生成。 - 如果用户在链接生成 5 分钟后才真正发起支付,用原下单参数重新调一次下单接口,换一个新的
h5_url再跳。
典型反例是把 h5_url 预生成后塞缓存长时间复用——比如活动页一上线就给所有用户批量下单、把链接存 Redis 存半小时。表现是用户点进去看到「支付请求已失效,请重新发起支付」,只能重来一遍。
回调必须在 5 秒内先验签再应答
用例项 ack_callback_within_five_seconds:收到支付成功通知后,5 秒内先验签再应答。验签不通过返回 4xx 或 5xx,不得返回 200。返回 200 等于告诉微信「我收下了」,后面不会重试,这笔单就成了只有微信知道、本地没入账的孤儿单。没收到通知时,用查单接口同步状态。
应答体本身没什么花头,200 + {"code":"SUCCESS","message":"成功"} 即可;失败就是 4xx/5xx 加失败体。关键是应答之前那段验签必须真的跑完,而不是「记个日志继续往下走」。用例项 verify_response_and_callback_signatures 专门点了这一条:存在验签方法不等于验签生效,要逐个调用点核对,验签失败即中止。
验签串的尾随换行不能省
V3 的应答和回调都要验,验签串按 timestamp\nnonce\nbody\n 构造——注意 body 后面还有一个换行。少这个换行,签名永远对不上,而且报错信息通常只说验签失败,很难查。
PHP:
$message = $timestamp . "\n" . $nonce . "\n" . $body . "\n";
$ok = openssl_verify(
$message,
base64_decode($signature),
$publicKey, // 或平台证书公钥
OPENSSL_ALGO_SHA256
) === 1;
Go:
message := timestamp + "\n" + nonce + "\n" + body + "\n"
h := sha256.Sum256([]byte(message))
err := rsa.VerifyPKCS1v15(pubKey, crypto.SHA256, h[:], sig)
body 用原始报文,不要先 json_decode 再 json_encode 回去,字段顺序和空白一变签名就废。同时检查 Wechatpay-Timestamp 与本地时间偏差,建议不超过 5 分钟。
按 Wechatpay-Serial 选证书,公钥 ID 带 PUB_KEY_ID_ 前缀
验签用的密钥不是固定的。要从每条应答或回调的 HTTP 头读 Wechatpay-Serial,拿这个序列号去本地证书池里找对应证书;找不到就调下载接口刷新证书池,再重新校验。不能始终用单张证书,也不能只调 getValidCertificate()。
常见报错长这样:
Cannot found the serial(...)'s configuration; which's from the response(header:Wechatpay-Serial)
平台证书和微信支付公钥择一使用,长期应固定一种验签模式;切换期允许并存,但必须按 Wechatpay-Serial 同时兼容两种。公钥的 ID 有 PUB_KEY_ID_ 前缀,看到这个前缀就走公钥验签分支。灰度期间微信侧按 7 天固定进度推进公钥回调比例:第 1 天 0.1%、第 2 天 1%、第 3 天 5%、第 4 天 10%、第 5 天 20%、第 6 天 50%、第 7 天 100%,所以回调代码里必须按请求头判断本次用公钥还是平台证书,不能写死。
另外别把几个序列号搞混:Authorization 里的 serial_no 填商户 API 证书序列号,不填平台证书序列号,也不填公钥 ID;请求头 Wechatpay-Serial 填的是公钥 ID 或平台证书序列号,和前面那个不是同一个东西。APIv3 密钥只用于 AEAD_AES_256_GCM 解密回调密文和下载平台证书返回的证书密文,不能拿来替代验签。
探测流量也要验签
Wechatpay-Signature 以 WECHATPAY/SIGNTEST/ 开头的是微信的探测流量。仍然要按正常流程验签,验签失败就返回 4xx/5xx。别看到这个前缀就直接放行 200,那等于给自己开了一个不验签的口子。
验签通过不等于能入账
用例项 match_callback_and_query_with_local_order 讲得直白:验签只证明报文来自微信支付,不证明这笔钱属于这笔订单。验签通过后,要用通知或查单返回的商户订单号定位本地订单,核对金额、商户号、appid 和订单归属,全部一致才能改状态。外部交易号要完整持久化,防止串单或被覆盖。
应答里别跑重活
5 秒的窗口装不下对账、发券、调第三方。回调处理顺序应该是:验签 → 落库或入队 → 立刻返回 200 → 异步做业务。同步链路里塞一个慢接口,微信重试几次,重复通知就来了。
最后两条基础设施要求:签名、验签、敏感字段加解密、回调验签与解密抽成公共方法,别在每个接口里各写一套,默认用官方工具类(Java WXPayUtility、Go wxpay_utility,原生支持微信支付公钥),非 Java/Go 语言照官方示例实现;商户 API 私钥、证书、APIv3 密钥、APIv2 密钥只留在服务端,从环境变量或 KMS 加载,不硬编码。