虚拟支付 -15006 / -15005 / 268490003:签名失败该按什么顺序查
从四条报错开始
同一套 xpay(米大师)接口,签名出错的报错会出现在三个地方,写法各不相同:
| 位置 | 报错 |
|---|---|
客户端 wx.requestVirtualPayment | -15006 PAY_SIG_INVALID(paySig 错)、-15005 SIGNATURE_INVALID(用户态 signature 错) |
服务端 /xpay/* | 268490003 签名错误 |
| 微信侧拒收 | errmsg 直接回 签名字段[pay_sig]为空 rid: ... |
微信开放社区里两个典型提问:
- 「虚拟支付 fail PAY_SIG_INVALID -15006?」——开发者 Node/TS 代码把 uri 写成
'/xpay/requestVirtualPayment'。官方回复:客户端 uri 填requestVirtualPayment,不带/xpay。改完后报错变为-15005 SIGNATURE_INVALID,即 paySig 过了、用户态签名还错。(帖中复现过程,未实测) - 「query_order 按官方文档实现仍返回『签名字段[pay_sig]为空』」——请求 URL 形如
https://api.weixin.qq.com/xpay/query_order?access_token=...&pay_sig=...&signature=...,body 最小化为{"openid":...,"env":0,"order_id":...},access_token 获取成功(长度 137),日志确认参与签名的 body 与实际发送一致,uri 只用/xpay/query_order,仍返回同一句 errmsg。官方给的下一步是用 rid 去developers.weixin.qq.com/console/devtools/debug或api_getridinfo查平台侧真实收到的请求。该帖没有最终结论,属未闭环案例(未实测)。
两条线索指向同一个排查入口:平台侧到底收到了什么。rid 能查到收到的 uri、body、签名串,比自己猜快。
两条签名公式与 uri 差异
paySig = to_hex(hmac_sha256(appKey, uri + '&' + signData))
signature = to_hex(hmac_sha256(sessionKey, signData))
uri 的取值是两条链路最大的分歧点:
| 参数 | wx API(客户端 wx.requestVirtualPayment) | 服务器 API |
|---|---|---|
| uri | 固定填 requestVirtualPayment | 实际接口路径,如 /xpay/query_user_balance |
官方示例里有一条注释:uri 切记不可带参数,即去掉 ? 及后面部分。
其余输入:
appKey:MP 后台 虚拟支付 → 基本配置 → 基础配置。沙箱 AppKey 和现网 AppKey 是两把;env=0对应现网,env=1对应沙箱。signData:客户端取基础库signData字段;服务端就是 api 的 post body。- 官方注释明确写了 JSON 序列化结果在不同语言/版本可能不同,示例为保证稳定直接写死字符串;实际只需保证参与签名的 post_body 与真正发起 HTTP 请求的一致。
Go:
func hmacHex(key, data string) string {
m := hmac.New(sha256.New, []byte(key))
m.Write([]byte(data))
return hex.EncodeToString(m.Sum(nil))
}
// 客户端:uri 固定,不带 /xpay、不带 query
paySig := hmacHex(appKey, "requestVirtualPayment"+"&"+signData)
// 服务端:uri 用实际接口路径
uri := "/xpay/query_user_balance"
paySig = hmacHex(appKey, uri+"&"+postBody)
signature := hmacHex(sessionKey, postBody)
PHP:
function hmac_hex(string $key, string $data): string {
return hash_hmac('sha256', $data, $key);
}
// 客户端
$paySig = hmac_hex($appKey, 'requestVirtualPayment' . '&' . $signData);
// 服务端
$uri = '/xpay/query_order';
$paySig = hmac_hex($appKey, $uri . '&' . $postBody);
$signature = hmac_hex($sessionKey, $postBody);
pay_sig 与 signature 的位置
两个签名都放在 query 后面,不是 header、不是 body 字段:
https://api.weixin.qq.com/xpay/query_user_balance?access_token=xxxx&pay_sig=xxx
query_order 请求体:openid 必填,env 必填(0 正式、1 沙箱),order_id 与 wx_order_id 二选一。
query_order 返回的 order.status:
| 值 | 含义 |
|---|---|
| 0 | 初始化(不可支付) |
| 1 | 创建成功 |
| 2 | 已支付待发货 |
| 3 | 发货中 |
| 4 | 已发货 |
| 5 | 退款商户侧扣款完成 |
| 6 | 已关闭 |
| 7 | 退款失败 |
| 8 | 用户侧收款完成 |
order.order_type:0 普通虚拟支付、1 普通退款、7 苹果 iOS 支付、8 苹果 iOS 退款。
参与签名的字符串与实际发送不一致:五处按命中概率
1. 客户端 uri 写成了接口路径
'/xpay/requestVirtualPayment' 是错值,正确值只有 requestVirtualPayment。同理,uri 后面挂上 ?a=1 也会立刻变成 -15006。这是社区里最先被翻出来的一处。
2. signData 在中途被重新序列化
SDK 返回的 signData 是一段已经算好签名的字符串,JSON.parse 再 stringify 会改变字段顺序和空格,直接导致验签失败。优先原样透传:
wx.requestVirtualPayment({ signData: result.signData, ... })
数字类型同样会破坏它:offerId 必须传字符串,传数字会验签失败。部分 SDK 文档还提到微信 Midas 验签服务端会按字典序重组 signData、对字段顺序敏感(三方文档说法,未实测)。
3. appKey 用错环境
沙箱 key 配 env=0,或现网 key 配 env=1,paySig 一定不匹配。注意 -15011 会先拦一道:现网版本的 env 只能是 0,不能填 1。
4. 服务端 uri 与实际请求路径不一致
服务端 uri 是 /xpay/query_order 这类路径,不是完整 URL,也不能把 access_token、pay_sig 拼进去。相对路径写成 xpay/query_order(少了前导 /)同样对不上。
5. signature 那一路用了另一把 key
signature 用 sessionKey 算,paySig 用 appKey 算,两者混用会稳定 -15005。另外 session_key 过期本身有独立错误码 -15007,但客户端拿旧 key 加签、服务端又走签名校验时,也可能先看到 268490003 / 268490009 用户 session_key 不存在或已过期,请重新登录。
用固定测试向量先自测算法
官方 Python 示例可直接当断言用,先确认自己的 hmac 实现没问题,再谈参数:
uri = '/xpay/query_user_balance'
appkey = "12345"
post_body = '{"openid": "xxx", "user_ip": "127.0.0.1", "env": 0}'
# pay_sig = c37809f27c6d7fd1837ad2500a04512b66b34fd793a39a385fade56dca89a4b5
session_key = "9hAb/NEYUlkaMBEsmFgzig=="
# signature = 089d9e8dc5d308977360c4b79ec600a93d736802802a807d634192328032f6c7
自测顺序:先把 uri / body / appkey 写死成和示例完全一致,跑出两个断言值;对得上说明算法和拼接符(uri + '&' + signData)没问题。再逐项换回自己的参数:uri 不带 query、body 与真实 HTTP 请求逐字节一致、appkey 与环境匹配。
CloudBase 文档反复强调的一点:签名必须基于原样字符串,任何解析后重新序列化、字段 trim、补空格都会改变待签内容。安全模式下回调校验的是 msg_signature 而不是 signature,这是那里最高频的错误(未实测)。
这些其实不是签名问题
签名排查最容易走偏的地方,是把下面这些也当成加签错误反复改代码:
| 错误码 | 真实原因 |
|---|---|
-15002 | outTradeNo 重复使用,换新单号重试 |
-15011 | 现网版本 env 只能是 0,不能填 1(沙盒) |
-15014 | 道具 / 代币发布未生效,禁止下单,约 10 分钟后生效 |
-15013 | goodsPrice 道具价格错误 |
268490001 | openid 错误 |
服务端侧还有几条与签名无关:268490002 请求参数字段错误(看 errmsg)、268490009 用户 session_key 不存在或已过期、268490011 数据生成中、268490014 退款操作进行中(可用相同参数重试)、268490015 频率限制、268490004 重复操作(赠送 / 代币支付 / 充值广告金,表示之前已成功)。
其余客户端码一并对照:-15007 session_key 过期、-15012 调用米大师失败导致关单(换新单号重试)、-15004 currencyType 错误(目前只能填 CNY)、-15010 道具 productId 未发布、-15018 道具 / 代币审核不通过、-15016 signData 格式有问题、-15008 二级商户进件未完成、-2 支付取消、-4 风控拦截。
幂等键用 wx_order_id,别用 outTradeNo
发货推送 Event=xpay_goods_deliver_notify,字段包含 OpenId / OutTradeNo / WeChatPayInfo.MchOrderNo(平台单号,即 wx_order_id)/ GoodsInfo.ProductId / GoodsInfo.Quantity。
应答必须与推送内容格式一致:XML 推送回 0,JSON 推送回 {"ErrCode":0},否则微信会重试,最多 15 次。
幂等键建议用平台单号 wx_order_id。用商家单号 outTradeNo 去重,会在「用户取消后重新下单复用同一单号」时误判为重复而漏发货。
执行顺序是 查重 → 处理 → 落标记。先落标记再处理,一旦处理失败,重推会被当成重复忽略,永久丢单。
商品信息不全不要一律返回成功:quantity 非法(0 / 小数 / 非数字)应抛错触发重推,静默改成 1 会造成「买 5 件只发 1 件」的资损。
outTradeNo 规则:8–32 字符,只能用数字、大小写字母和 _-|*@,不能以下划线开头,每单只能用一次。
排查清单
- 拿到 rid,去
developers.weixin.qq.com/console/devtools/debug或api_getridinfo查平台侧收到的 uri 与 body。 - 客户端 uri 是否为
requestVirtualPayment,没有/xpay前缀、没有?及其后内容。 - 服务端 uri 是否为
/xpay/xxx形式的接口路径,不带域名、不带 query。 - 用官方固定测试向量跑一遍 hmac,确认算法与
uri + '&' + signData拼接正确。 - 打印出的 post_body 与真实发出的字节是否完全一致,全链路无二次序列化。
offerId等字段类型是否为字符串。- appKey 与
env是否配套(0 现网 / 1 沙箱),现网是否误填env=1。 sessionKey是否过期,signature用的是 sessionKey 而非 appKey。pay_sig与signature是否都拼在 query 后面。- 排除
-15002 / -15011 / -15014 / -15013 / 268490001这类非签名错误。 - 发货回调应答格式与推送格式一致,幂等键取
wx_order_id,先处理后落标记。