微信小程序支付回调 notify_url 为何收不到通知？

Question

微信小程序支付回调 notify_url 收不到通知，常见原因有五类：一是服务器未正确配置 HTTPS（微信强制要求 443 端口、有效 SSL 证书，自签名或过期证书均被拒）；二是 notify_url 地址未在商户平台【产品中心→开发配置】中准确填写并保存生效（注意：需是完整 URL，如 `https://api.xxx.com/pay/notify`，且不能带参数或重定向）；三是服务端未按规范返回 `success`（纯文本、无空格/换行/HTML 标签），导致微信认为处理失败而停止重试；四是服务器防火墙、Nginx 或云厂商安全组拦截了来自微信 IP 段（如 182.254.0.0/16、140.207.0.0/16）的 POST 请求；五是未开启支付结果异步通知（部分服务商 SDK 默认关闭，需显式启用）。建议通过微信商户平台「API安全→回调告警」查看失败日志，并用 curl 模拟回调验证服务端响应逻辑。

Answer 1

```html

一、表层现象：回调无日志、无请求痕迹（可观测性缺失）

最直观表现是服务端 Nginx access.log 或应用日志中完全查不到 /pay/notify 的任何 POST 记录，连 TCP 连接都未建立。此时问题不在业务逻辑，而在网络链路或平台配置层面。需优先排除 DNS 解析失败、域名未备案（尤其国内云主机）、HTTPS 重定向（如 http→https 301）导致微信客户端拒绝跳转等隐性拦截。

二、协议合规性校验：HTTPS 强制规范与证书可信链深度解析

微信支付回调强制要求：

• 必须使用 443 端口，非 443（如 8443）将被静默丢弃；
• SSL 证书须由 受信 CA 签发（Let’s Encrypt、DigiCert 等），自签名、局域网 CA、过期/未生效/域名不匹配证书均触发 TLS 握手失败；
• 推荐使用 openssl s_client -connect api.xxx.com:443 -servername api.xxx.com 验证证书链完整性与有效期。

三、平台侧配置闭环：商户后台「开发配置」的5个易错细节

检查项	正确示例	典型错误
URL 格式	https://api.xxx.com/pay/notify	带查询参数：?v=1；含重定向路径：/redirect?to=/pay/notify
保存状态	点击“保存”后出现绿色提示“配置成功”	仅填写未点保存；保存后未等待 1–3 分钟全局生效

四、服务端响应契约：为什么只返回 "success" 还不够？

微信回调验证极为严格：必须满足纯文本、UTF-8 编码、HTTP 200 状态码、响应体仅含 7 字符 success（无换行、无空格、无 BOM、无 HTML 标签、无 JSON 包裹）。常见陷阱：

// ❌ 错误示例（Spring Boot）
return ResponseEntity.ok().body("{\"result\":\"success\"}"); // 含 JSON、引号、大括号
// ✅ 正确示例
response.setContentType("text/plain;charset=UTF-8");
response.getWriter().write("success");
response.getWriter().flush();

五、网络策略穿透：微信官方 IP 段白名单与中间件放行实践

微信回调源 IP 并非固定，但主要来自以下 CIDR 段（需在云安全组、Nginx allow 指令、防火墙 iptables三级同步放行）：

• 182.254.0.0/16（含 182.254.128.1 等高频出口）
• 140.207.0.0/16
• 58.250.128.0/17（部分新节点）

建议 Nginx 配置示例：

location /pay/notify {
    allow 182.254.0.0/16;
    allow 140.207.0.0/16;
    deny all;
    proxy_pass http://backend;
}

六、SDK 行为差异：主流 SDK 默认关闭异步通知的真相

以 weixin-java-pay v4.5.0+ 为例，WxPayService 初始化后需显式启用：

config.setNotifyUrl("https://api.xxx.com/pay/notify");
// ⚠️ 关键：默认 false，必须手动设为 true！
config.setUseSandbox(false); // 沙箱环境也需开启
wxPayService.setConfig(config);

而 PayJS、Yansongda Pay 等 SDK 则要求在下单时传入 notify_url 参数，且不能依赖全局配置。

七、诊断工具链：从平台告警到本地模拟的完整闭环

推荐分阶段验证：

1. 登录【微信商户平台 → API安全 → 回调告警】查看失败类型（如“连接超时”“证书错误”“HTTP 502”）；
2. 用 curl 模拟真实回调（注意添加微信 UA 和原始 XML body）：

curl -X POST https://api.xxx.com/pay/notify \
  -H "Content-Type: application/xml" \
  -H "User-Agent: MicroMessenger" \
  -d '<xml><return_code>SUCCESS</return_code><result_code>SUCCESS</result_code><out_trade_no>ORDER_123</out_trade_no><total_fee>1</total_fee><sign>ABC123</sign></xml>'

八、进阶排查：TLS 版本、HTTP/2 兼容性与 CDN 缓存干扰

微信服务器目前仅支持 TLS 1.2+，不兼容 TLS 1.0/1.1；若使用 CDN（如腾讯云 CDN、Cloudflare），需确认：

• CDN 是否缓存了 /pay/notify 路径（必须禁用缓存）；
• 是否开启 HTTP/2（部分旧版 Nginx + OpenSSL 组合存在握手失败）；
• CDN 回源是否透传原始 Host 头（避免虚拟主机路由错误）。

九、架构级加固：幂等设计与回调重试机制的工程化落地

微信对失败回调采用8次指数退避重试（最大间隔2小时），服务端必须实现：

• 基于 out_trade_no 或 transaction_id 的唯一索引防重复；
• 异步落库 + 状态机更新（pending → success → notified）；
• 独立回调处理线程池，避免阻塞主业务。

十、可视化诊断流程：微信回调全链路状态决策树

graph TD
  A[收到回调告警] --> B{是否有 access_log 记录？}
  B -->|否| C[检查 DNS/HTTPS/安全组/IP 白名单]
  B -->|是| D{响应状态码是否 200？}
  D -->|否| E[检查 Nginx 返回逻辑、反向代理配置]
  D -->|是| F{响应体是否纯 'success'？}
  F -->|否| G[检查编码、BOM、空格、框架自动包装]
  F -->|是| H[验证业务逻辑：订单是否存在、状态是否已终态]

```