支付回调验签与订单查询的四个坑排查实录

一、现象：收款成功了，订单却还挂着"未支付"

先交代来源：这个问题是我在做一款本地化部署的微信自动回复工具时踩到的，工具按坐席收年费，需要一个能用的在线收款通道，于是接了一家聚合支付的网关。整体流程是教科书式的：服务端创建订单，拿网关返回的二维码展示给客户，客户扫码付款，网关异步回调我们的notify_url，我们验签、更新订单、发货。逻辑简单，但真跑起来之后，四个意料之外的坑接连冒了出来，每一个单看都不难，叠在生产环境里都足以造成资损或者客诉。

第一坑的表象是：客户明确付了款，也确实在我们对账后台看到了入账，但我们系统里的订单状态纹丝不动，还是"待支付"，发货动作迟迟不触发。第二坑的表象是：回调验签通过了，按文档主动查询订单补单时，网关却返回"Order is not found"，而订单明明是今天刚创建的。第三坑的表象是：一部分订单查询永远查不到，CreateAt 一算才发现创建时间已经过去了两天多。第四坑是自找的：压测轮询接口时把对方的查询接口打出了限流，二维码还没过期，查询配额先烧完了。

这篇文章把四个坑逐一拆开：现象、排查过程、根因原理、修复代码，最后给一份可以直接对照自查的清单。代码全部是 Node.js/Express 风格，签名算法是这家网关用的 MD5-ASCII-排序方案，也是国内支付文档里最常见的套路，思路可以直接平移到 SHA1/SHA256 变体上。

二、第一坑：验签失败的真正原因是排序和拼接，不是密钥

2.1 现象与第一轮排查

回调处理上线当天，测试环境全绿：用 Postman 模拟网关回调，验签通过，订单状态正常流转。切到生产之后，验签成功率却掉到了一个很低的水平——网关的重试机制会不断补发通知，我们的日志里全是验签失败的记录，而成功的那几笔，看起来毫无规律。

第一直觉是密钥配错了。把商户后台的密钥、配置文件里的密钥、发起支付请求时用的密钥三方比对，完全一致。密钥没问题时，验签失败只剩一种可能：我们这边算出来的签名和网关带过来的签名，参与计算的内容不一样。也就是说，问题出在"签名串的构造"这一步。

先把这家网关文档里的签名规则抄下来，这也是绝大多数 MD5 签名网关的通用规则：

1. 把所有请求参数（不含sign本身）按参数名的 ASCII 码从小到大排序；
2. 排序后按key=value用&拼接，得到待签名串，末尾不拼&key；
3. 直接拼接商户密钥（或按文档拼在末尾带&key=xxx，以网关文档为准）；
4. 对拼接串做 MD5，转大写十六进制，得到sign；
5. 验签时用收到的参数重新算一遍，与收到的sign做比较。

规则很清楚，坑全在规则的执行细节里。

2.2 拼出来的待签名串对不上

我在验签失败时把待签名串打了出来，同时用网关后台提供的"签名校验工具"算了一份标准答案，两相对比：

我们拼的：amount=10.00&mch_id=20250923001&notify_url=https://a.b/notify&out_trade_no=...&status=1&time=1727068800 标准答案：amount=10.00&mch_id=20250923001&out_trade_no=...&status=1&time=1727068800

差异一眼可见：我们的串里多了notify_url和time两个参数。多出来的来源有两种典型情况，我这两种都中了。

第一种是"参与签名的字段范围"理解错了。文档写的是"所有参数参与签名"，但很多网关会在回调报文里附加一些网关自己加的字段，比如notify_url、time、nonce，这些字段不参与签名。判断标准只有一个：看网关文档里回调报文的字段说明表，逐个字段核对"是否参与签名"这一列。没有文档说明兜底时，就用穷举法：把收到的字段做全集，然后按组合逐个排除尝试——字段数量不多时，组合数是可控的。

第二种是空值参数的处理。MD5 签名的通用惯例是：值为空的参数不参与签名。我们有一个可选参数attach（商户附加数据），下单时没传，网关回调时把它原样带回来了一个空字符串，我们老老实实把它拼进了待签名串，网关那边却把它排除了。这一个字符的差异，MD5 就是两个完全不同的值。

2.3 修复后的验签代码

把三件事做对：ASCII 排序、按文档圈定参与签名的字段并排除空值、比对时防时序攻击。修复后的验签函数如下：

constcrypto=require('crypto');constexpress=require('express');constapp=express();// 网关回调一般用 application/x-www-form-urlencodedapp.use(express.urlencoded({extended:false}));constMCH_KEY=process.env.PAY_MCH_KEY;// 密钥只走环境变量，不进代码库// 文档明确"不参与签名"的字段，硬编码白名单外一律以文档字段表为准constEXCLUDE_KEYS=newSet(['sign','sign_type']);functionbuildSignStr(params){returnObject.keys(params).filter((k)=>{if(EXCLUDE_KEYS.has(k))returnfalse;// 签名本身不参与constv=params[k];if(v===undefined||v===null||v==='')returnfalse;// 空值排除returntrue;}).sort()// Array.prototype.sort 默认按 UTF-16 码元排序，// 对纯 ASCII 参数名等价于 ASCII 升序；含非 ASCII 键时需用 localeCompare 定制.map((k)=>`${k}=${params[k]}`).join('&');}functionverifySign(params){constreceived=String(params.sign||'').toUpperCase();constsignStr=buildSignStr(params)+'&key='+MCH_KEY;constexpected=crypto.createHash('md5').update(signStr,'utf8').digest('hex').toUpperCase();// 防时序攻击：用 timingSafeEqual 而不是 ===consta=Buffer.from(expected);constb=Buffer.from(received);if(a.length!==b.length)returnfalse;returncrypto.timingSafeEqual(a,b);}app.post('/pay/notify',(req,res)=>{constparams=req.body;if(!verifySign(params)){// 注意：验签失败也要按网关文档返回"失败应答"，否则网关会按重试策略疯狂补发returnres.send({code:'FAIL',message:'verify sign error'});}// 验签通过后的业务处理见第三节res.send({code:'SUCCESS'});});app.listen(3000);

这里有两个容易忽略的工程细节。一是sort()的排序语义：JavaScript 的默认排序按字符串码元比较，对纯 ASCII 的参数名（支付网关的字段名基本都是小写字母加下划线）正好等价于 ASCII 升序，但如果字段名里混入了大写或特殊符号，_（0x5F）和大写字母（0x41-0x5A）的先后关系会跟直觉不一样，稳妥做法是显式用(a, b) => (a < b ? -1 : a > b ? 1 : 0)的码元比较，并保证和网关侧算法一致。二是验签失败的应答体：不同网关对"收到但验签失败"和"根本没收到"的处理策略不同，有的会无限重试，所以失败应答也要严格按文档格式返回，避免回调风暴把日志打爆。

2.4 延伸：为什么必须排序，以及 MD5 还能不能用

最后把第一坑背后的原理层补全，回答两个常被追问的问题。

第一个问题：为什么签名一定要按 ASCII 排序？根源在于 HTTP 报文里的字段本身没有顺序承诺。表单编码也好、JSON 也好，规范都不保证键序稳定，同一个请求换一种序列化方式，字段的物理顺序就变了。而签名要求"双方对同一份内容算出同一个摘要"，这就必须先约定一种规范化（canonicalization）规则，把无序的键值对折叠成唯一确定的字符串。ASCII 升序是所有规范化方案里实现成本最低、跨语言歧义最小的一种——任何语言里一行 sort 都能得出完全一致的结果。理解了这一层就会明白：排序规则不是网关的怪癖，而是签名协议成立的前提条件；同理，“空值是否参与”"字段名大小写是否敏感"这些边角规则，本质上都是在补齐规范化的定义，缺了任何一条，两边的规范化结果就可能不同，验签就会随机失败。

第二个问题：MD5 都被碰撞攻击打穿了，为什么还在用？MD5 的抗碰撞性确实早已被打破，但本方案的用法是"密钥拼接后做摘要"，安全目标是防伪造而不是防碰撞，截至目前没有公开的、能在真实网关场景下稳定伪造有效签名的通用攻击。话虽如此，新接入的网关若提供 SHA256 或 HMAC 结构的变体，应当优先选择；被迫使用 MD5 老协议时，靠两道额外防线兜底：一是验签通过后再校验关键业务字段——金额、订单号、商户号——与本地订单库是否一致，防止"签名合法但内容被构造"的极端情况；二是把回调来源 IP 限制在网关文档公布的网段白名单内，让攻击必须先过网络层这一关。签名是第一道闸，但它从来不该是唯一一道。

三、第二坑：查询接口返回"Order is not found"，其实是参数名拼错了

3.1 一个误导性极强的报错

验签修好之后，回调链路通了。但支付回调不是万能保险——网关重试有次数上限，我们自己的服务也可能在回调到达那一刻正在重启。所以任何接支付的团队都会做第二条腿：主动查询兜底。对本地状态还是"待支付"、又过了合理时间的订单，调网关的订单查询接口，用真实支付状态修正本地状态。

实现很简单，几十行代码。结果一跑就撞上了新的报错：

{"code":"ORDER_NOT_EXIST","message":"Order is not found"}

订单明明是刚创建的，二维码刚展示出去，客户端也能拉起支付。第一反应是订单号传错了，反复核对后发现订单号完全正确。第二反应是"是不是要等网关侧落库"，加了延迟重试，照样报错。这个报错文本极具误导性——它让你拼命怀疑"订单"本身，而真正的问题出在请求参数名上。

3.2 根因：out_trade_no 还是 out_trade_order

把请求报文原样打出来，对照文档逐字段看，问题找到了。文档的查询接口参数表里，商户订单号的字段名是out_trade_no；而我们实现时，因为内部数据库的表字段叫out_trade_order（建表时照着回调报文里的某个字段名抄的，抄串了），查询请求里也就跟着发了一个out_trade_order过去。

两个字段名只差最后两个字母。网关收到一个它不认识的参数，不报"参数错误"，而是把请求当成"没有传商户订单号"来处理——按照它的参数解析逻辑，out_trade_no缺省，于是走到"按订单号查库、查不到"的分支，返回了"Order is not found"。

这个坑的教训不在于粗心，而在于三个系统性问题：

1. 网关对未知参数静默忽略。很多 HTTP 接口对多余参数不校验，out_trade_order发过去就像没发过一样。如果网关对未知参数直接拒绝（400 Bad Request），这个 bug 会在第一分钟暴露；静默容忍反而把问题藏到了业务语义层，报错文本还指错了方向。
2. 报错语义与真实原因错位。“Order is not found” 描述的是业务结果，掩盖的是参数错误。遇到这类报错时，正确动作是先把请求报文和文档参数表逐字段 diff，而不是顺着报错去查订单系统。
3. 内部字段名与外部协议字段名交叉污染。我们建表时用了回调报文的字段名风格，写查询代码时又想当然地以为内部名等于外部名。正确的做法是：凡是跨出进程边界的字段名（HTTP 请求体、回调报文），必须以网关文档为准单独维护一份映射，绝不从数据库字段名"推理"。

3.3 修复与防复发

修复本身是改一个词的事，防复发靠的是把"外部协议字段"收敛到一个常量模块里，并给查询接口包一层统一的错误归因：

// pay-protocol.js —— 网关协议字段唯一出口，与网关文档逐字对齐module.exports={// 网关文档《订单查询接口》参数表原文：out_trade_no（商户订单号）QUERY_ORDER:'/api/v1/order/query',FIELD_OUT_TRADE_NO:'out_trade_no',// 注意：不是 out_trade_orderFIELD_MCH_ID:'mch_id',};// pay-query.js —— 主动查询兜底const{QUERY_ORDER,FIELD_OUT_TRADE_NO,FIELD_MCH_ID}=require('./pay-protocol');asyncfunctionqueryGatewayOrder(outTradeNo){constparams={[FIELD_MCH_ID]:process.env.PAY_MCH_ID,[FIELD_OUT_TRADE_NO]:outTradeNo,time:Math.floor(Date.now()/1000),};params.sign=md5Sign(params,process.env.PAY_MCH_KEY);constresp=awaitfetch(QUERY_ORDER,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(params),});constdata=awaitresp.json();if(data.code==='ORDER_NOT_EXIST'){// 关键：先做参数自检，再相信"订单不存在"这个语义constsentKeys=Object.keys(params).filter((k)=>k!=='sign');constrequiredKeys=[FIELD_MCH_ID,FIELD_OUT_TRADE_NO,'time','sign'];constmissing=requiredKeys.filter((k)=>!(kinparams)||params[k]==='');if(missing.length>0){thrownewError(`查询参数缺失，怀疑字段名错误: missing=${missing}sent=${sentKeys}`);}}returndata;}

这段代码里最重要的一行是missing自检：把"参数名拼错"这种低级但高发的错误，从"网关报错后人工排查"前移到"代码自动归因"。从那以后我们所有的网关接口调用都走同一个封装，字段名全部走pay-protocol.js常量，新接一个接口的成本从"通读文档"降到"抄字段表"。

四、第三坑：过期订单被网关清理了——WP 和 OD 两个状态码的含义

4.1 查不到的订单有共同特征

补单逻辑上线后，又出现一类查询失败：同样是"Order is not found"，但这次参数名核对过无数遍，确实没错。把查不到的订单拉出来看，发现了共同特征：全部是创建后超过 48 小时仍然未支付的订单。

对照网关文档的订单状态说明，找到了答案。这家网关对未支付订单有一个自动清理机制：

文档里写得明明白白：未支付订单超过有效期（我们接入的这档产品是 48 小时，不同网关不同产品线差异很大，必须按自己的文档确认）后，状态先转为过期（OD），过期订单在网关侧保留一段时间后会被物理清理，清理之后再查询，返回的就是"Order is not found"——和参数名拼错的报错一模一样。

这就是最迷惑的地方：同一个报错文本，对应两种完全不同的成因。参数名拼错是开发期问题，订单被清理是运行期问题，处理动作完全不同：前者改代码，后者改流程。

4.2 对补单逻辑的连锁影响

这个发现直接否定了我们补单逻辑的一个隐含假设："只要查，网关总能告诉我们订单的最终状态。"实际上，网关对超期未付订单的记忆是有限的。对这类订单，补单的正确姿势不是死磕查询接口，而是接受现实：订单已死，让用户重新下单。

具体到状态机设计，补单流程应该是这样：

constPAY_RESULT_MAP={SU:'PAID',WP:'PENDING',OD:'EXPIRED',CL:'EXPIRED',};asyncfunctionreconcileOrder(order){constdata=awaitqueryGatewayOrder(order.out_trade_no);if(data.code==='ORDER_NOT_EXIST'){// 两种成因在此分流：创建时间很短 → 参数问题告警；创建时间很久 → 视为过期constageHours=(Date.now()-order.createdAt)/3600_000;if(ageHours>GATEWAY_ORDER_TTL_HOURS){awaitmarkOrder(order.id,'EXPIRED','gateway-cleaned');awaitreleaseStock(order.id);// 释放占用的库存/名额return{action:'expired'};}// 订单还很新却查不到：大概率是协议问题，必须告警而不是静默吞掉alertOps(`新订单查询不到:${order.out_trade_no}, age=${ageHours.toFixed(1)}h`);return{action:'alert'};}constgatewayState=PAY_RESULT_MAP[data.trade_state];if(gatewayState==='PAID'&&order.status!=='PAID'){awaitmarkOrder(order.id,'PAID','reconcile');awaitdeliverGoods(order.id);return{action:'paid'};}return{action:'noop'};}

这里的GATEWAY_ORDER_TTL_HOURS是一个必须写进配置而不是写死在代码里的量——它取决于网关产品线的清理策略，换产品线、换网关都要重新确认。另一个实践细节是releaseStock：超期订单如果不释放库存，名义库存会被僵尸订单慢慢吃光，这是比"查不到订单"更隐蔽的资损。

五、第四坑：轮询压测——二维码过期后的退避节奏

5.1 把查询接口打出限流的一次压测

前三坑都修完之后，链路理论上闭环了，但我想验证兜底查询的真实成功率，于是写了个脚本模拟 500 个用户同时扫码、扫完不付，观察补单任务的查询流量。结果脚本跑起来不到两分钟，网关开始返回 429，随后部分请求直接被断开。是补单任务把查询接口打出了限流。

复盘流量构成，问题出在轮询节奏上。我们最初的实现是固定间隔轮询：每 5 秒查一次，直到订单过期。这个节奏对单个订单毫无压力，但它的数学期望算一下就吓人：500 个未付订单 × 12 次/分钟 = 6000 QPS 的查询需求，而补单任务又是全量并发扫表的，等于把所有僵尸订单同时怼到了查询接口上。

固定间隔的问题在于它与订单生命周期的实际价值不匹配。二维码的有效期通常是 2 到 5 分钟（我们设的是 3 分钟）。在前 3 分钟里，用户随时可能付款，轮询有意义；3 分钟一过，二维码已经死了，用户不可能再扫它付款，此时还以 5 秒一次的频率查询，本质上是在用 6000 QPS 去确认一个几乎不可能发生的事件。

5.2 退避设计：5 秒起步，30 秒封顶，二维码过期后转惰性

修正后的轮询策略分三个阶段：

对应代码，核心是一个带退避的调度函数：

constQR_TTL_MS=3*60*1000;// 与下单时传给网关的 expire_time 保持一致constACTIVE_INTERVAL_MS=5*1000;constDECAY_INTERVAL_MS=30*1000;constDECAY_WINDOW_MS=QR_TTL_MS*3;functionnextDelayMs(order){constage=Date.now()-order.createdAt;if(age<QR_TTL_MS)returnACTIVE_INTERVAL_MS;if(age<DECAY_WINDOW_MS)returnDECAY_INTERVAL_MS;returnnull;// 退出轮询，交给每日对账}asyncfunctionpollOnce(order){constdelay=nextDelayMs(order);if(delay===null){awaitmarkOrder(order.id,'POLL_GIVEUP','decay-done');return;}awaitsleep(delay);constresult=awaitreconcileOrder(order);if(result.action!=='paid'&&order.status==='PENDING'){schedulePoll(order);// 继续下一轮}}

除了退避，还有两个并发层面的闸门必须加。一是全局并发上限：补单任务的扫表 SQL 必须带LIMIT，配合一个固定大小的 worker 池，把对网关查询接口的瞬时 QPS 压在配额以内（我们按网关文档给的限流阈值打了对折留余量）。二是抖动：如果 500 个订单都是整点创建的，即便 30 秒一次，也会形成 30 秒一次的脉冲。给每次轮询加 0 到 5 秒的随机抖动，把脉冲摊平。这两个手段合起来，压测的 429 再没有出现过。

另外补一个容易忽略的点：轮询查到"已支付"后要先落库再发货，且落库要用状态机的条件更新（UPDATE orders SET status='PAID' WHERE id=? AND status='PENDING'）防并发——因为回调通道和轮询通道可能在同一秒内同时发现支付成功，两条链路都触发发货就是双重发货。

轮询结果同时驱动前端的交互：活跃期的查询响应里带上二维码剩余有效秒数，前端据此做倒计时；一旦进入衰减期（二维码已死），接口返回明确的状态标记，前端把二维码置灰并引导用户重新下单。这个细节在客服侧的体感很明显——早先版本里二维码死了页面还在原地转圈，用户以为付了款没到账，这类客诉比发货慢还多。

六、四个坑沉淀成一张自查清单

四个坑走完，回头看，它们其实是同一个主题的四个切面：你与网关之间的契约，远比文档第一页写的"发起支付、接收回调"要细得多。最后把这次的全部教训整理成一份自查清单，接入任何一家新的支付网关时逐条过一遍：

最后一句话收尾：支付链路的所有坑，本质上都是"你以为网关会怎样"和"网关实际怎样"之间的差值。把每一处差值用文档核对、用真实请求验证、用清单固化下来，这个差值就会越来越小——这也是这套微信自动回复工具后来再没出过支付类工单的原因。