代码 H5(MWEB) 支付接入：referer 为空、域名不一致和空白页的排查路径

2026-09-21 09:01:08

H5(MWEB) 支付接入：referer 为空、域名不一致和空白页的排查路径

用户在手机浏览器里点了「微信支付」，跳过去的不是收银台，而是「商家参数格式有误，请联系商家解决」。这篇文章记录微信支付 H5(MWEB) 接入中常见的几类调起失败：referer 为空、H5 支付域名与发起页或回跳域名不一致、在微信内打开、mweb_url 被截断，给出对应报错原文和要检查的位置，并说明 mweb_url 的 5 分钟有效期、redirect_url 的回跳时机与查单兜底。

H5 支付不是 JSAPI，也不是 Native

H5 支付的场景定义是：商户在微信客户端外的移动端网页展示商品，用户在该页面确认支付后，商户发起服务唤起微信客户端完成支付。主要用于触屏版手机浏览器，可以从外部浏览器唤起微信。

三类场景别混：

微信内网页 → JSAPI 支付
PC 网页、公众号内 → Native 或 JSAPI
APP 内 → APP 支付。H5 支付不建议在 APP 端使用，否则可能有兼容性问题

下单拿到的是中间页链接，5 分钟过期

统一下单接口返回支付跳转链接，V3 文档叫 h5_url，V2 叫 mweb_url。商户在已配置 H5 支付域名的前端网页跳转该链接拉起微信收银台。链接是中间页，形如：

https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=...&package=...

几个必须记住的点：

该链接有效期为 5 分钟，超过后要用原下单参数重新请求下单接口拿新链接
严禁篡改、拆分、截断，微信侧会调整链接长度和参数数量
若需支付后跳回指定页面，只允许在参数后拼接 redirect_url，不能再拼其他任何参数
prepay_id 有效期 2 小时，针对 H5 支付这个参数无特殊用途

V2 统一下单 scene_info 必填，H5 固定传 h5_info，按场景三选一：

{"h5_info":{"type":"IOS","app_name":"","bundle_id":""}}
{"h5_info":{"type":"Android","app_name":"","package_name":""}}
{"h5_info":{"type":"Wap","wap_url":"","wap_name":""}}

另有门店信息 {"store_info":{"id":"","name":"","area_code":"","address":""}}。

跨境 V3 文档（/v3/global/transactions/mweb）里 scene_info 是必填对象，含 payer_client_ip 等字段，并注明服务商模式及普通商户模式下 scene_info 可不传。国内接入以国内 V3 H5 下单接口的字段为准，这两处口径不一致，需自行验证。

H5 支付域名与 referer

调起支付前必须在商户平台配置 H5 支付域名，只有配置了该域名的网页才能跳转链接。路径：商户平台 → 产品中心 → 开发配置 → H5 支付。

两项必须与配置域名完全一致：

支付发起页面的域名（不含 http:// 或 https://）
redirect_url 回跳地址的域名（若设置）

referer 是微信侧取域名的来源，所以要抓包确认这个头。

跨境文档写的是「所配置域名为一级域名即可」，例如配 qq.com，则 xxx.xx.qq.com 或 xx.qq.com/xx 都覆盖。国内配一级域名还是精确子域名，两处口径不同，以官方文档和商户平台实际校验为准。

三类典型报错怎么查

「商家参数格式有误，请联系商家解决」

referer 为空导致，一般是因为直接访问 h5_url 调起支付。按正常流程页面跳转后发起支付，或抓包确认 referer 值。App 里调起 H5 支付需要在 webview 手动设置：

extraHeaders.put("Referer", 授权域名)

「商家存在未配置的参数，请联系商家解决」

当前调起支付域名（微信侧从 referer 获取）与申请 H5 支付时提交的授权域名不一致；或者设置了 redirect_url，但回跳地址域名与授权域名不一致。

「请在微信外打开订单，进行支付」

H5 支付不能直接在微信客户端内调起，要在外部浏览器打开；微信内拉起请改用 JSAPI 支付。

其余几条：

mweb_url 打开是空白页：不支持 APP 内嵌 H5
「系统使用量大，稍后操作」：预鉴权失败，调起参数不对，多数是 MWEBURL 缺少 package，即链接被篡改或截断
「商户号该产品权限预开通中」：需要先开通 H5 支付产品权限

redirect_url 回跳不等于支付结束

回跳地址要先 urlencode：

mweb_url + "&redirect_url=" + urlencode("https://www.wechatpay.com.cn")

设置 redirect_url 后，回跳可能发生在：微信支付中间页调起收银台后超过 5 秒；用户点击「取消支付」，或支付完成后点击「完成」。所以无法保证回跳时支付流程已经结束——落地页不能自动执行查单，应让用户点按钮触发查单。

Safari 浏览器传 redirect_url 支付完成后会新开一个页面，属设计如此，防止商户无限循环调用微信客户端。

同一个 h5_url 只被一个微信号调起，不同微信号需要重新下单生成新链接。

关单与查单兜底

trade_state 流转：NOTPAY 未支付 → SUCCESS 支付成功 / CLOSED 已关闭。未支付时用户仍可支付，支付失败状态不变。

7 天内商户可对无需继续支付的订单调用关单接口，超过 7 天由微信侧自动关单
退款支持支付成功后 1 年内的订单
支付成功微信会发回调；未收到回调可调用查询订单接口确认

错误码：NOAUTH 无接口权限 / ORDERPAID 订单已支付 / ORDERCLOSED 订单已关闭 / SYSTEMERROR 系统错误（同参重试）/ APPID_NOT_EXIST / MCHID_NOT_EXIST / APPID_MCHID_NOT_MATCH / LACK_PARAMS / OUT_TRADE_NO_USED 商户订单号重复 / SIGN_ERROR 签名错误 / REQUIRE_POST_METHOD / POST_DATA_EMPTY / NOT_UTF8。

下单接口的安全校验

下单接口必须做安全校验，否则交易容易被利用。跨域非简单请求会有 Options 预检，商户后台需支持 Options 并校验 Origin 白名单，不在白名单返回 403 且不返回 Access-Control-Allow-* 头；GET/POST 跨域下单需校验 Origin 合法且用户 Cookie 登录态完备。

参考

开发指引 https://pay.weixin.qq.com/docs/merchant/products/h5-payment/development.html
常见问题 https://pay.weixin.qq.com/doc/v3/merchant/4012791845
统一下单(V2) https://pay.weixin.qq.com/doc/v2/merchant/4011937163
V2 常见问题 https://pay.weixin.qq.com/doc/v2/merchant/4011936869

国内 H5 支付域名是一级域名还是精确子域名、以及不同 webview 里 referer 的默认行为，建议按自己接入的接口版本和商户平台的实际报错再验一遍。

复制全文生成海报微信支付 H5支付 MWEB 支付接入排障