微信支付回调接口排查指南
回调没收到？先分清是“没发”还是“没接”
微信支付回调接口是商户系统接收支付结果的核心通道。支付成功但订单状态不更新，大部分情况下不是支付流程出了问题，而是回调链路的某个环节卡住了。排查时先想清楚一个问题：微信到底有没有把通知发出来？
判断方法很简单。登录微信支付商户平台，在“交易中心—支付账单”里找到那笔订单，查看它的“通知记录”。如果记录里显示通知已发送且商户返回了“处理成功”，那问题大概率出在你自己系统的业务逻辑上，比如回调逻辑抛了异常、更新订单时条件不匹配。如果通知记录压根不存在，或者显示多次重试仍失败，那才需要往下查。
最常见的几个堵塞点
1. 回调地址配错了
商户平台里“产品中心—AppID授权管理”或“API安全—回调配置”中填写的URL必须是可以公网访问的HTTPS地址。很多开发者在测试环境用局域网IP或带端口的地址凑合，微信在公网无法访问，自然发不到。另外，如果填写的是http而不是https，微信支付从2021年起已强制要求HTTPS，这个雷现在基本踩不到，但检查一下没坏处。
2. 请求被中间链路拦截
回调通知来自微信的固定IP段，但一些服务器防火墙或云安全组策略对入站请求做了严格限制。排查时翻一下服务器日志，看有没有来自微信支付IP段（可在微信支付官方文档中查到）的POST请求被拒。如果有，放行相关IP段即可。
3. 签名验证没通过，代码直接拒绝
微信支付APIv3的回调通知使用商户API密钥做签名，且通知内容经过AES-256加密。如果验签或解密逻辑写得不对，比如密钥配置错误、证书序列号不匹配、或解密时没注意到报文中的`ciphertext`是Base64编码，就会导致验签失败。微信在收到非“SUCCESS”响应时会反复重试，所以数据库里可能出现同一笔订单收到几十次通知的情况——这也是判断验签是否出问题的重要线索。
4. 响应格式或状态码不对
微信支付要求商户系统在收到通知后，必须返回HTTP 200，且响应体为特定的JSON格式：`{"code": "SUCCESS", "message": "成功"}`。很多新手容易在这里踩坑：要么返回了200但响应体是空字符串，要么返回的是`{"code": "fail"}`（注意是错误码“FAIL”，大小写别写错），要么直接抛出500。这些都会让微信判定为处理失败，然后按间隔重新发起通知。
5. 处理逻辑有状态依赖
比如有些系统只在订单状态为“待支付”时才接受回调更新，一旦前一次回调已经把订单状态改成“已支付”，后一次重复通知就会被当成无效请求直接忽略。这个本身没问题，但要注意：如果第一次回调处理时订单还没创建成功，回调逻辑返回了失败，微信会重试，可重试时订单状态可能已经变化，代码却还按旧逻辑判断，就会一直卡住。
一条省事的排查路径
按下面顺序过一遍，能覆盖绝大部分问题：
- 先看商户平台通知记录，确认微信是否已发送，以及商户返回了什么
- 再看服务器访问日志，确认POST请求是否到达
- 如果请求到了，单独写个测试脚本，用微信官方SDK的验签函数去验证当前证书、密钥是否匹配
- 确认返回格式严格参考官方文档，尤其注意响应的Content-Type是否为`application/json`
- 最后看应用日志里有没有验签之外的安全拦截（比如网关层面的WAF规则误伤）
回调本地模拟也是个好办法
微信支付官方提供了“支付回调模拟器”，但很多时候用起来不顺手。更快的办法是自己写一段脚本，构造一个符合微信格式的通知报文，POST到你自己的回调地址。这样验签逻辑、解密逻辑、业务更新逻辑全链路在本地就能调通。等本地模拟通过了再切真实环境，远比对着线上日志猜快得多。
另外，别忽略时区问题。微信回调报文中的`time`字段是UTC秒级时间戳，如果代码里误当成北京时间解析，可能导致业务侧时间判断错位，看起来像是“回调失败”，其实只是数据错乱了。
回调排查说到底是链路问题，从微信侧发起到你系统处理完返回，一个节点一个节点地过，很快能找到堵点。别一上来就改代码，先确认通知有没有走到你家门口。
