案例 支付宝 notify_url 用 http 会静默丢通知:还有 cancel 的空 action 和全额退款不发通知

2026-11-21 21:04:36

支付宝 OpenAPI V3 对接笔记:HTTP 200、空 action 与验签通过之后

alipay-gosdk 是支付宝开放平台 OpenAPI V3 协议的 Go SDK,RSA2 签名,证书模式与密钥模式都支持,零外部依赖。下面记录的是 2026-08-03、2026-09-08 两次生产探测中,几个「响应看着正常、结论却是错的」的点。

notify_url 用 http 会静默丢通知

notify_url 必须是 HTTPS。填 http 地址时,支付宝不会投递通知,也不会报错:付款成功,接收端一条通知都收不到,从接收端排查不出原因。2026-09-08 实测,同一台接收机换成 https 隧道后 8 秒收到通知。

资金单据变更通知走应用网关地址(消息服务通道),不受这个限制。

通知本身是 V2 form 格式,和 API 协议版本无关。

同步返回只代表支付流程结束

客户端 SDK 回调 resultStatus=9000、return_url 的同步跳转参数,都只是「支付流程结束」的信号。前端 my.tradePay 的 resultCode === '9000' 同理。

付款结论只能取异步通知,或 trade.Query 返回的 trade_status,并且只有 TRADE_SUCCESS / TRADE_FINISHED 才算成功。

return_url 回来的 GET 参数用 notify.VerifyReturn 验签,验签通过同样不能当付款成功的依据。

验签通过不等于这单是你的

ParseTrade 只做签名与 app_id 校验。另外三项是调用方的责任:

  • out_trade_no 确实属于自家系统;
  • total_amount 与订单实际金额一致;
  • seller_id 确为该单据的收款方。

不做这三项,一条签名合法但属于别人订单的通知就会被当成自己的。

err := notify.Verify(c, params) // params: 已 url-decode 的通知参数
tn, err := notify.ParseTrade(c, params)
// tn.OutTradeNo / tn.TradeNo / tn.TradeStatus / tn.TotalAmount / tn.NotifyID
// ParseTrade 只校验签名与 app_id;下面三项由调用方补:
// out_trade_no 属于自家订单、total_amount 与订单金额一致、seller_id 是收款方
err = notify.VerifyReturn(c, params)
notify.Ack(w) // 应答纯文本 success

官方对异步通知验签的口径是:除 sign、sign_type 两个参数外,所有通知参数都是待验签参数(生活号异步通知需保留 sign_type,用 verifyV2);参数 url_decode 后字典排序拼串,sign base64 解码后用支付宝公钥验签;RSA2 用 SHA256WithRSA。

验签失败常见原因:用了应用公钥而不是支付宝公钥;charset 不一致;sign_type 与公钥不匹配(RSA 与 RSA2 不能混用);自行解析时没剔除 sign/sign_type、没 url_decode、没排序。

应答只认纯文本 success

处理成功后调 notify.Ack(w),应答纯文本 success,多一个空格都算失败,支付宝会重投。同一 notify_id 可能重复投递,幂等由调用方负责。

trade.cancel:空 action 不等于关单成功

trade.cancel 是这条链路上的「静默成功」接口:单号不存在与交易已关闭两种情形都返回 HTTP 200、retry_flag=N、action 与 trade_no 全空,从响应里分不开。沙箱与生产均实测如此。

action 为空只能读成「这一次什么都没做」,交易到底什么状态必须再调 Query。用假单号探测返 HTTP 200 + 空 action,只坐实签名与链路通得过,证明不了接口已部署或字段拼装被接受。真实未付款单的 action=close 才算确认。

fastpay.refund.query:空对象不是「没退款」

交易存在但该退款请求号没有退款时,接口返回 HTTP 200 + 全空对象,连 out_trade_no 都不回显。沙箱与生产真实单据都实测如此。

所以退款成功的唯一判据是 RefundStatus == trade.RefundStatusSuccess。

另一个生产实测结论:全额退款不发异步通知。只监听通知的对账系统会漏掉全额退款,退款结果必须靠主动 RefundQuery 兜底。

错误码前缀别合并

收单交易的业务错误码带 ACQ. 前缀原样透传,例如 ACQ.TRADE_NOT_EXIST。转账链路的错误码没有前缀,两者不是一套,server 侧分类表不要合并。

trade.query 金额是带引号的字符串

沙箱实测 trade.query 的金额字段返回带引号的字符串("0.01"),但文档三处口径不一,因此仍用两向兼容的类型接。

bill.downloadurl.query 的 secure=true 在沙箱返 http://、生产返 https://。沙箱行为不可直接外推,完整差异见 COVERAGE.md。

证书轮换:新旧 PEM 拼接过渡

支付宝更换公钥证书前会先通知商户,不会静默切换。收到通知后下载新的 alipayCertPublicKey_RSA2.crt,把新旧两张证书的 PEM 拼在一起填进 AlipayCertPEM 先上线,等网关切到新证书后再把旧证书拿掉:

AlipayCertPEM: read("alipayCertPublicKey_RSA2.crt") + "\n" + read("alipayCertPublicKey_RSA2_new.crt"),

New 会解析全部证书并按 SN 建索引;V3 响应按 alipay-sn 头精确选公钥;异步通知/回跳验签时 form 里不一定有 alipay_cert_sn,会依次尝试每把公钥。

响应头 alipay-sn 不在本地证书里时报 ErrAlipayCertMismatch,错误信息带网关给的 SN 与本地持有的 SN 列表;配了多张证书而响应没带 alipay-sn 头时同样报错,不挨个试。本库不自动下载证书:资金类 SDK 静默换验签公钥不可接受。

沙箱能验的,和生产能验的

沙箱适合跑通签名链路、字段拼装、通知 form 解析和回调格式;以下这些必须生产实测,或者不能从沙箱外推:

  • 通知是否真的投递(http 的 notify_url 在沙箱可能看起来正常,生产静默丢);
  • 全额退款是否发通知;
  • bill.downloadurl.query 的 secure=true 返回协议;
  • 加签方式二选一的生产约束。一个 APPID 只能配一种加签方式,但沙箱不强制这条:密钥模式在沙箱也能转账成功,沙箱能过不代表生产能过。

另外几条文档约束:资金支出类接口必须用公钥证书方式签名(如 alipay.fund.trans.uni.transfer);2026-11-09 起新增 5 个转账接口,新建应用调用必须配置 IP 白名单,否则请求直接拦截;加签方式变更后新方式立即生效,旧方式 7 天后失效。

trade.cancel 和 fastpay.refund.query 的空响应在沙箱与生产表现一致,这两类可以在沙箱先把「空 action / 空对象之后必须再查」的处理逻辑写对,但真实未付款单的 action=close、真实退款单的 RefundStatus,仍要拿生产单据确认。

复制全文 生成海报 支付 支付宝 接口对接 Go

推荐文章

程序员茄子在线接单