代码 支付异步回调回执写错的两个方向:微信 v3 的 200 漏单与支付宝的 JSON 重试

2026-11-16 09:01:27

支付异步回调回执写错的两个方向:微信 v3 的 200 漏单与支付宝的 JSON 重试

支付异步通知的回执是协议的一部分,不能当成普通接口的返回值。回执写错只有两个方向:把失败写成成功,对方会停止重推,本地漏单;把成功写成失败或无法识别的形式,对方会按固定节奏重推,直到次数耗尽。两种都出现在线上过,而且大多数要等到对账才发现。

下面按微信支付 APIv3、微信支付 v2、支付宝三家的回执规则对照,再讲三个具体现场和排查顺序。

三家回执规则对照

渠道请求形态成功回执失败回执重试
微信 APIv3POST + JSON body,签名在 Wechatpay-Signature / Wechatpay-Timestamp / Wechatpay-Nonce / Wechatpay-Serial 头HTTP 200 或 204,不看 body4xx/5xx,需带应答报文最多 15 次,总计 24h4m
微信 v2POST + XMLbody 里 SUCCESSFAIL 会触发重推按 v2 文档节奏
支付宝POST + application/x-www-form-urlencoded纯文本 success,7 个字符任何非 success 的内容25 小时内 8 次,最长 24h22m

这张表里最容易看错的是微信 v3:成功与否只由 HTTP 状态码决定,body 里的 code 字段不参与判断。

微信支付 APIv3

应答要求是 HTTP 200 或 204,无需返回应答报文。处理异常时返回 5xx 或 4xx,可以带 {"code":"FAIL","message":"失败"} 这样的报文。

也就是说,200 + {"code":"FAIL"} 会被判为接收成功,微信不再重推。验签失败必须返回 4xx/5xx;如果返回 200,等于主动关闭了重试。

重试节奏:15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h,总计 24h4m,最多 15 次。必须在 5 秒内应答,验签完成即可先应答,业务异步处理。

notify_url 必须 https,不能带参数,不能是内网 IP 或 localhost;未设置 APIv3 密钥不会推送回调。

另外,极少数回调的 Wechatpay-Signature 带 WECHATPAY/SIGNTEST/ 前缀,这是微信在探测是否真验签。按正常流量验签,验不过照样返回 4xx/5xx。

微信支付 v2

v2 的回执是 XML:


v2 看的是 body 里的 return_code,写 FAIL 会重推。这和 v3 正好相反。很多老项目从 v2 迁 v3 时把回执逻辑原样抄过来,写出的就是“HTTP 200 + body code=FAIL”。

支付宝

异步通知是 POST 表单,参数直接用 $_POST / request.Form 取。回执必须原样输出纯文本 success:无引号、无空格、无 HTML 标签、无多余字符。

只要不是 success 就继续重发,最长 24 小时 22 分钟;一般 25 小时内 8 次,间隔 4m/10m/10m/1h/2h/6h/15h(境外版文档写 2m/10m/10m/1h/2h/6h/15h)。

notify_url 不能重定向:重定向后支付宝收不到 success 字符,判定异常并重发。通知页不能有登录态,cookie/session 无效。同一笔交易多次重发的 notify_id 不变,可以当幂等键。常用二次校验是 alipay.trade.query 查单,或 RSA2 验签。

三个翻车现场

一、v3 回执照抄 v2:200 + code=FAIL

代码里 return json(['code' => 'FAIL'], 200),本意是“我处理失败了你重推”。微信看到 200 就认为收下了,不再推。结果是钱到了,本地订单还是待支付,T+1 对账才发现单边账。

反向的错同样致命:验签失败却 return 200,等价于永久关掉重试,异常回调全部静默丢弃。

二、支付宝回执被框架包装

Laravel / ThinkPHP 里 return 'success' 之前有统一 JSON 包装中间件,或者全局 after 中间件追加 debug 信息,或者走了 view 渲染。支付宝收到的是 {"code":0,"msg":"success"},不是 7 个字符,重发 8 次后放弃。

还有一种:return response('success') 本身没问题,但 Content-Type 自动加了 charset、响应体前后多了空格换行,字节数对不上。支付宝要的是恰好 7 个字节。

三、notify_url 配成 http,301 把 POST 变成 GET

nginx 对 http 强跳 https 写 return 301,支付宝或微信的客户端跟随跳转时,可能把 POST 降级成 GET。RFC 7231 允许这么做,curl 对 301/302 默认也降级,需要 --post301 才保留方法。

跳转后对方发来的是 GET,参数全空,验签报签名错误或参数缺失;支付宝则直接因为看不到 success 开始重发。307/308 才会强制保留请求方法。

复现与排查

curl 复现

# 看响应体是否恰好是 success,-i 同时看状态码和 headers
curl -i -X POST https://example.com/pay/notify \
-d 'out_trade_no=test123&trade_status=TRADE_SUCCESS'

# 观察 301 之后的方法是否被降级
curl -i -L --post301 -X POST http://example.com/pay/notify -d 'a=1'

# 检查响应体字节数,支付宝要正好 7
curl -s -X POST https://example.com/pay/notify -d 'a=1' | wc -c

nginx 与网关层

  • access log 里有没有这条 POST,状态码是 200 还是 301/302/413/403/499。
  • 强制 https 的 rewrite / return 301 会把 POST 变 GET;回调路径应 return 308,或直接只监听 https。
  • client_max_body_size 默认 1m,普通回调 body 很小,但自定义大 JSON 回调可能 413。
  • WAF / CDN:拦截 UA、拦截非常规 path、返回 5 秒 JS 挑战页,对方收到的是 HTML,验签和回执全失败。回调路径要加白名单。
  • gzip:排查时先对回调路径关掉,避免响应被改写。
  • PHP-FPM 超时、框架 boot 耗时过长,都会撞上微信 5 秒应答窗口。

三层归因顺序

第一层:请求到没到。 在 access log 按路径 + 方法筛 POST,看有没有 4xx/5xx/30x。没有记录就是网关或 DNS 层,不是代码问题。

第二层:回应对不对。 抓响应体字节。微信看 HTTP 状态码;支付宝看是否恰好是 success 七个字节。

第三层:业务生没生效。 查幂等表 / 订单表,看是否因为唯一键冲突把业务吞掉,或者应答在业务之前(先回 200,进程随后被杀,业务没跑完)。

正确的回执写法

框架无关的要点先列出来:回执路径要绕开统一响应包装中间件;不经过 view 渲染;输出层只写状态码或 success;先把消息投进队列再应答,真正的业务在队列里跑,避免 5 秒超时。

微信 APIv3:

// 成功只看状态码,不要复用统一 JSON 响应
public function wechatNotify(Request $request)
{
$raw = $request->getContent();

if (!$this->wechatVerifier->verify($request->headers->all(), $raw)) {
http_response_code(401);
header('Content-Type: application/json');
echo json_encode(['code' => 'FAIL', 'message' => '验签失败']);
exit;
}

$this->dispatchToQueue($raw);
http_response_code(204);
exit;
}

支付宝:

public function alipayNotify(Request $request)
{
$this->dispatchToQueue($request->post());

// 响应体必须恰好 7 个字节,不要包 JSON、不要加空格换行
return response('success', 200)
->header('Content-Type', 'text/plain');
}

Laravel 里如果路由挂在统一 JSON 响应中间件组下,用单独中间件组或 withoutMiddleware 把它摘掉,别让包装层碰这个路由。

文档确认与未实测

文档确认的部分:v3 只看 HTTP 状态码、重试节奏与 24h4m / 15 次上限、5 秒应答窗口、notify_url 的 https 与无参数要求;v2 以 XML return_code 判断;支付宝 success 七字符、24h22m / 8 次、notify_id 幂等。

未实测的部分:301 之后各家客户端具体用什么方法重发,本文依据 RFC 7231 与 curl 默认行为说明,没有逐家抓包验证;支付宝境内与境外文档给出的首轮间隔分别是 4m 与 2m,以接入区域的文档为准。

复制全文 生成海报 支付回调 微信支付 支付宝 排障 nginx

推荐文章

程序员茄子在线接单