接入易错点

 下单使用的 appid 须与商户号存在绑定关系，不得使用已注销或迁移回收的 appid 

 说明：H5 下单传入的 appid 必须与该 mchid 存在绑定关系，普通（非合单）H5 支付同样校验该绑定关系，不能因请求中没有子单就跳过 APPID 绑定检查；即使该 appid 对应的公众号已迁移或注销回收，只要绑定关系仍在，下单仍可能成功，但该用法不被建议使用。
正确应该怎么做：① 在商户平台【产品中心 > APPID授权管理 > +关联AppID > 新增授权】为当前 H5 商户号提交 appid 授权绑定申请；② 由该 APPID 的管理员登录公众平台或开放平台确认该商户号的授权绑定；③ 在【产品中心 > APPID账号管理 > 我关联的APPID账号】确认绑定生效后，再使用该 appid 调用 H5 下单接口；④ 更换 appid 前先确认新 appid 与该商户号已完成绑定，账号迁移或公众号注销回收后停止继续使用该 appid 下单，改用已完成绑定的新 appid。
典型反例：公众号已迁移回收，仍继续沿用原 appid 下单（因绑定关系未解除而仍能支付成功，误以为该 appid 可以继续使用）；更换业务 APPID 后，沿用历史绑定关系或另一个商户号的绑定关系直接发起普通 H5 支付。
见 4012791834-H5下单、4015614193-H5支付开发接入准备、4013287174-管理商户号绑定的APPID账号、4013426141-管理商户号绑定的APPID账号 

 下单返回 400 APPID_MCHID_NOT_MATCH，提示「appid和mch_id不匹配，请检查后再试」或「AppID和mch_id不匹配」，订单无法创建，用户无法进入收银台。 

 微信客户端内不得使用 H5 支付，须按 UA 分流走 JSAPI 支付

 说明：H5 支付提供的是在手机浏览器网页（非微信客户端内部浏览器）中使用微信支付收款的能力，H5 支付链接不能在微信客户端内直接调起；微信内场景需使用 JSAPI 支付；间连（服务商/从业机构）模式下没有 H5 支付产品，选型阶段不应把 H5 支付作为收款方案。服务商/从业机构模式下，若页面是在微信内直接打开（不在小程序内），同样应按 JSAPI 方式下单并拉起。
正确应该怎么做：① 服务端按请求的 User-Agent 判断是否处于微信内置浏览器（UA 含 MicroMessenger）；② 微信内走 JSAPI 下单取得 prepay_id，前端按 JSAPI 方式调起支付；③ 微信外再调用 H5 下单接口，取得 h5_url 后由前端跳转；④ H5 支付页面在微信内被打开时，引导用户在外部浏览器打开或直接切换到 JSAPI 支付链路。
典型反例：不做环境判断，所有渠道统一走 H5 下单并把 h5_url 交给前端跳转，导致微信内用户打开后白屏。
见 4012791832-H5支付产品介绍、4012791845-H5支付常见问题、4012791870-JSAPI支付开发指引、4012062524-JSAPI支付产品介绍 

 在微信内打开 h5_url 提示「请在微信外打开订单，进行支付」或页面空白，微信内用户无法完成付款。

 App 内不得使用 H5 支付，App 场景须改用 APP 支付

 说明：H5 支付面向手机浏览器网页收款，不支持在 App 内使用；服务商模式的 H5 支付同样明确 App 中不要使用 H5 支付，App 场景应使用 APP 支付。
正确应该怎么做：① 产品选型阶段按使用场景确定支付方式：微信外手机浏览器网页用 H5 支付，商户自有 App（含鸿蒙形态应用）内用 APP 支付；② 按 APP 支付接入：在微信开放平台创建并认证移动应用，完成 APPID 与商户号绑定；③ App 内调用 APP 下单接口并通过微信支付 SDK 拉起支付，不要在 App 的 webview 内嵌 H5 支付链接收款；④ 已按 H5 支付接入且运行在 App 内的，改造为按 APP 支付接入。
典型反例：App 内用 webview 打开 H5 下单返回的 h5_url 完成收款。
见 4012791832-H5支付产品介绍、4012074916-H5支付产品介绍（服务商模式） 

 App 内调起 H5 支付时无法唤起微信客户端（如鸿蒙系统 APK 内提示未安装微信，而同设备浏览器中同样链接可正常拉起），支付流程中断；支付完成后的回跳链路还需另向微信侧申请配置。

 调起支付的页面域名须与商户平台配置的 H5 支付域名完全一致

 说明：只有已在商户平台配置 H5 支付域名的网页才能跳转 H5 支付链接；跳转支付页面的域名（不含 http:// 或 https://）必须与配置的域名完全一致，大小写、是否带 www 及子域名差异都会导致不一致，H5 支付不支持中文域名。域名新增或变更后需重新提交审核，审核期间在该域名上调起支付仍会被拦截。
；域名新增或变更须重新提交审核，审核通常需 3~5 个工作日，审核通过后一般 10 分钟内生效。支付中签约等 H5 场景同样受该域名限制，签约链路发起前也须完成该域名配置，见 4011987320-支付中签约。
正确应该怎么做：① 由超级管理员登录【商户平台 -> 产品中心 -> 开发配置 -> H5支付】添加支付域名（填写格式不含 http:// 或 https://，最多 5 个，不支持中文域名），提交后等待审核（3~5 个工作日，审核通过后一般 10 分钟内生效），并按配置指引提交域名首页、经营服务页与 ICP 备案截图等材料；② 上线前逐一核对调起支付页面的域名与 redirect_url 的域名是否与已配置域名完全一致，包括大小写与子域名；③ 境外机构或子商户场景按境外 H5 支付接入文档在【产品中心 -> H5支付 -> H5支付授权域名】配置，并保证下单请求中的 refer_url 取该域名；服务商模式下在【服务商平台 -> 产品中心 -> 开发配置 -> H5支付】为特约商户配置授权域名，并核对 redirect_url 的域名也已配置。
典型反例：配置了 pay.example.com 却从 www.example.com 或其他子域名发起支付；配置小写域名但实际跳转使用含大写字母的域名；商户存在多个站点或品牌域名时，仅为其中一个配置 H5 支付域名，其他站点复用同一套下单与跳转逻辑；在未配置的测试域名或备用域名上直接跳转 h5_url。
见 4013287193-配置H5支付域名、4012791831-H5支付开发指引、4012791835-H5调起支付、4012791845-H5支付常见问题、4012354170-境外H5支付接入文档（3.3 配置H5支付授权域名）、4013336019-配置H5支付域名（服务商） 

 调起支付时提示「商家存在未配置的参数，请联系商家解决」，或在拉起收银台阶段报验签失败，用户无法完成支付。

 调起 H5 支付须保证请求来源 Referer 不为空，并由已配置域名的页面跳转

 说明：调起 H5 支付时请求来源（Referer）不能为空，须由已配置 H5 支付域名的商户页面跳转支付链接；直接访问 h5_url 会因 Referer 为空被拦截，在 App 的 webview 中跳转时需由商户自行带上 Referer，其值为申请 H5 支付时提交的授权域名。
；在 App 的 WebView 中调起时须显式将 Referer 设置为申请 H5 支付时提交的授权域名。
正确应该怎么做：① 在商户平台【产品中心 -> 开发配置 -> H5支付】配置与调起支付页面完全一致的支付域名；② 由该域名下的 H5 页面发起跳转，不要把 h5_url 直接返回前端当作普通链接打开，也不要直接粘贴到浏览器地址栏做联调自测；③ 在 App 的 webview 中跳转时，手动设置 Referer 请求头为已配置的 H5 支付域名（如 extraHeaders.put("Referer", "已配置的H5支付域名")），iOS WKWebView 默认可能不携带 Referer，需显式设置；④ 在会清空来源信息的浏览器或容器中调起时，同样需主动设置 Referer 后再验证；⑤ 上线前用一笔真实订单验证整条跳转链路可用。
典型反例：后端下单拿到 mweb_url 后直接返回给前端打开；在 App 内直接用 webview 加载 h5_url 且未设置 Referer；把支付链接直接粘贴到浏览器地址栏自测；把 checkmweb 链接当作可分享的支付链接使用。
见 4012791845-H5支付常见问题、4013287193-配置H5支付域名、4012791835-H5调起支付、4012791831-H5支付开发指引、4012354174-H5支付开发指引（全球版）。 

 Referer 为空时调起 H5 支付失败，无法拉起收银台：提示「商家参数格式有误，请联系商家解决」、页面显示为空白，或在部分浏览器（如鸿蒙自带浏览器）中提示「当前页面的URL未注册」。

 APIv3 H5 下单须在 scene_info.payer_client_ip 传入用户真实客户端 IP，不得填 127.0.0.1 或服务端出口 IP

 说明：调用 POST /v3/pay/transactions/h5 时，须在 scene_info.payer_client_ip 上传用户真实 IP，该 IP 须与用户实际调起支付时的客户端 IP 一致，支持 IPv4 与 IPv6，不能填本地回环地址或商户服务端地址；存在反向代理时须从 X-Real-IP、X-Forwarded-For 等可信转发头恢复客户端真实 IP。
正确应该怎么做：① 前端接入层无代理时直接取 REMOTE_ADDR；② 有反向代理时在 Nginx 配置 proxy_set_header X-Real-IP $remote_addr; 与 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;（Apache 启用 mod_remoteip 并配置 RemoteIPHeader X-Forwarded-For），服务端再从 X-Forwarded-For / X-Real-IP 取首跳客户端 IP；③ 下单前校验 scene_info.payer_client_ip 不是内网地址或回环地址，并在日志中留存该取值以便核对；④ 将该真实 IP 写入 POST /v3/pay/transactions/h5 的 scene_info.payer_client_ip。
典型反例：下单时把终端 IP 写死为 127.0.0.1，或统一填成网关、容器或商户服务端的出口 IP；代理层未透传导致取到的是代理服务器 IP。
见 4012791834-H5下单、4018677409-获取用户ip指引（APIv3）、4012791845-H5支付常见问题、4012354174-全球支付开发指引（H5支付获取用户IP指引章节） 

 用户付款时提示「由于商家传入的H5交易参数有误，该笔交易暂时无法完成，请联系商家解决」，该笔交易无法完成。

 下单报文字段须使用 UTF-8 字符，不得传入表情等非 UTF-8 字符

 说明：微信支付接口仅支持 UTF-8 字符编码的一个子集，即使用一至三个字节编码的字符，不支持 Unicode 辅助平面中四至六字节编码的字符（如部分表情符号）。
正确应该怎么做：服务端在组装下单报文时，对商品描述等来自用户输入的文本字段做字符校验，将四字节及以上的表情、特殊字符剔除或替换后再提交，确保整包以 UTF-8 编码下单。
见 4012081709-基本规则、4011986641-协议规则（V2） 

 下单接口返回 err_code=INVALID_REQUEST、err_code_des=请求内容传入了非UTF8参数，订单创建失败，用户无法进入支付流程。 

 h5_url 有效期为 5 分钟，超时须用原下单参数重新下单

 说明：h5_url 的有效期为 5 分钟，该有效期指支付跳转链接本身的有效期，并非要求用户在 5 分钟内完成付款；超过有效期须使用原下单参数重新请求下单接口获取新的 h5_url。如需限制用户可支付的时长，应通过下单参数 time_expire 或商户系统内部倒计时关单实现，不与这 5 分钟混淆。
；与 Native 支付 code_url 2 小时的有效期不同，两类支付链接的有效期须分别处理，不能沿用同一套缓存与过期策略。
正确应该怎么做：① 在用户实际发起支付的时点再调用 H5 下单接口获取 h5_url，避免提前长时间缓存；② 若用户在链接生成 5 分钟后才发起支付，用原下单参数重新调用下单接口换取新的 h5_url 后再跳转；③ 订单可支付时长另行用 time_expire 设置。
典型反例：提前批量预生成 h5_url 并长时间缓存复用。
见 4012791834-H5下单、4012791831-H5支付开发指引、4012791845-H5支付常见问题 

 超过 5 分钟后访问提示「支付请求已失效，请重新发起支付」，用户需要重新下单才能继续付款。

 redirect_url 须为已配置的 H5 支付域名，并做 urlencode 后拼在 h5_url 末尾

 说明：支付完成后默认返回发起支付的页面；如需返回指定页面，只能在 h5_url 后拼接 redirect_url 参数，其域名必须是商户已配置的 H5 支付域名，且必须对该值做 urlencode 处理。
正确应该怎么做：① 确认 redirect_url 的域名已在商户平台配置为 H5 支付域名；② 对 redirect_url 的取值做 urlencode；③ 将其拼接在 h5_url 参数之后、放在链接最后，不再追加其他参数；④ 在回跳页面中增设确认支付情况的按钮，用户点击后触发查单，以便确认订单状态。
典型反例：把 redirect_url 拼在 h5_url 中间或在其后继续追加其他参数；未做 urlencode 直接拼接带查询串的回跳地址。
见 4012791835-H5调起支付、4012791831-H5支付开发指引、4012791845-H5支付常见问题 

 提示「商家存在未配置的参数，请联系商家解决」，或 iOS 提示「签名验证失败」、安卓提示「系统繁忙，请稍后再试」；支付完成后不会跳转到指定页面，用户被带回发起支付的页面。

 不得以是否跳转 redirect_url 判定支付结果，须以查单结果为准

 说明：H5 支付中，用户在收银台完成支付后点击「完成」或中途取消支付，页面会返回拉起支付前的 H5 页面（若拼接了 redirect_url 则返回指定页面）。该跳转的判定时机由外部浏览器与 H5 支付中间页决定，不由微信客户端控制，在支付完成前返回浏览器的场景同样会触发页面重定向并访问 redirect_url。
正确应该怎么做：① 在回跳的商户页面（或 redirect_url 指定页面）中增设「确认支付情况」按钮，用户点击后由服务端调用查询订单接口确认订单状态；② 服务端以支付成功回调通知为准更新订单，未收到回调时主动调用查询订单接口轮询确认，不以页面跳转事件作为支付成功或失败的判定依据。
典型反例：把 redirect_url 被访问直接等同于支付成功并发货；或把支付完成前的回跳当作支付失败而关闭订单。
见 4012791835-H5调起支付、4012791838-商户订单号查询订单、4012791836-支付成功回调通知、4012791831-H5支付开发指引 

 订单已实际支付而前端展示为未支付（或反之），导致重复下单、重复扣款、漏发货或误关单等资损与客诉。

 前端下单按钮须做防抖，服务端须对同一业务单据做幂等控制

 说明：若前端未限制重复触发且服务端未做幂等校验，用户在网络卡顿或误触下快速连点，会生成多笔不同 out_trade_no 的订单并拉起多次支付；H5 场景下拉起微信客户端存在耗时，若该耗时超过前端设定的防抖时间，用户在结果未确认前的再次点击仍会触发第二次拉起。
正确应该怎么做：① 前端在用户点击「下单/支付」按钮后立即置为不可点并提示处理中，待本次下单有明确结果（接口返回或查单确认支付状态）后再恢复；② 服务端以业务订单为幂等粒度，同一业务订单重复发起支付时复用已有的商户订单号与有效期内的支付参数，不得生成第二个商户订单号，原商户订单号确认已关闭或失效后才可换新；③ 未收到支付成功回调时，调用查询订单接口确认订单状态后再展示结果。
典型反例：前端统一防抖时间设为 500ms，但拉起支付的耗时超过该窗口，用户在结果未确认前再次点击购买，触发两次拉起并完成两次付款；仅在前端做防抖，服务端无防重复提交兜底。
见 4012791870-JSAPI支付开发指引、4012791831-H5支付开发指引、4012791834-H5下单。 

 同一笔业务生成多笔订单并被拉起两次付款，用户支付完成返回后可再次输入密码完成第二次付款，造成同一笔业务重复扣款与用户资金损失，商户需承担人工核对与退款成本。

 回调 IP 白名单须按网段配置，且文档所列网段须全部放行

 说明：微信支付回调通知由多个出口网段发出，商户侧若对回调请求做防火墙策略限制，需按微信支付给出的网段配置白名单，按单个 IP 逐个配置无法覆盖全部出口。
正确应该怎么做：① 按回调通知注意事项文档列出的上海电信、上海联通、上海 CAP、深圳电信、深圳联通、深圳 CAP、香港出口网段以及广州腾讯云出口 IP 逐条加入防火墙白名单；② 退款结果通知、分账动账通知与风险订单通知另有独立 IP 清单，接入这些通知时一并放行。
典型反例：仅按历史提供的若干个单点 IP（如 101.226.103.14、101.226.103.15、101.226.103.16）配置白名单，未覆盖完整网段。
见 4012075420-回调通知注意事项 

 微信支付回调请求被商户防火墙拦截，商户收不到「支付结果通知」，订单状态无法及时更新。