接入易错点

 调用 APP 支付（trade_type=APP）前须按商户号单独开通 APP 支付产品权限，该权限不区分终端

 说明：APP 支付是独立的基础支付产品权限，须在商户平台产品中心申请并审核通过；支付产品权限按商户号维度开通，不按 iOS / 安卓 / 鸿蒙等终端分别开通，因此同一商户号下不同终端使用不同 trade_type 时，需要各自对应的产品权限。
正确应该怎么做：① 由超级管理员登录商户平台【产品中心 -> APP支付 -> 申请开通】，填写移动应用 APPID、上传 APP 页面截图、提供 APP 在主流应用市场的上架链接后提交；② 审核通过后发起 APPID 授权绑定申请，并登录开放平台确认授权绑定；③ 在【产品中心 -> APP支付】核实权限开通结果后再按 trade_type=APP 发起下单，未开通前不要以 APP 交易类型下单。
典型反例：以「iOS、安卓端都能正常收款」推断 APP 支付权限已开通，实际上这些端走的是 H5 支付等其他已开通产品，鸿蒙等真正走 APP 交易的终端被拦截。
见 4013070174-申请APP支付权限指引、4015478291-开发接入准备、4013289251-管理商户号绑定的APPID账号 

 下单返回「商户号该产品权限未开通，请前往商户平台>产品中心检查后重试」，该笔订单拿不到 prepay_id，用户在对应终端无法完成支付。 

 用于 APP 支付的 AppID 主体须与商户、渠道商、从业机构三者之一一致

 说明：查询应用 AppID 需填写已通过微信认证的应用 AppID，其微信认证主体须与商户主体、渠道商主体、从业机构主体三者中任一保持一致；服务商、渠道商、从业机构不支持关联主体不一致的 AppID，且异主体绑定暂不支持移动应用类型的 AppID。主体名称中的字符（如中英文括号）状态建议与登记信息保持一致。
正确应该怎么做：① 申请或选用移动应用 AppID 前，先核对其微信认证主体是否与商户/渠道商/从业机构之一一致；② 主体一致时，服务商登录服务商平台【合作伙伴功能 > 商户基础服务 > 开发参数配置 > 对应子商户号“开发配置” > 特约商户 APPID 配置】发起绑定；渠道商不支持登录服务商平台配置，需联系从业机构协助配置；③ 提交后由 APP 管理员登录开放平台【移动应用 - 详情 - 能力专区 - 微信支付 - 查询详情】确认授权绑定的商户号。
典型反例：渠道商登记主体名称使用中文括号，而申请 AppID 时主体填写为英文括号，两处主体名称被判定为不一致。
见 4016329059-管理商户号绑定的APPID账号（服务商）、4013357894-管理商户号绑定的APPID账号 

 AppID 主体与三者均不一致时绑定申请无法通过，移动应用类型 AppID 的异主体绑定暂不支持，商户号与 AppID 无法建立绑定关系，APP 支付无法开通，商户无法按计划上线。

 APP 下单的 appid 须为移动应用类型且已与对应（子）商户号完成绑定

 说明：APP 支付只能使用在开放平台注册的移动应用 appid，不要混用公众号或小程序的 appid；下单时会强校验 appid 与商户号（子商户号 sub_mch_id）的绑定关系，商户号必须与移动应用 appid 建立绑定关系才能正常支付。
正确应该怎么做：① 由超级管理员登录商户平台【账户中心 -> 经营场景管理 -> 添加场景】填写 AppID 并提交授权绑定申请：App 已上架主流应用商店的提供应用市场下载链接，尚在开发未上架的提供 App 首页与商品/服务页截图，仅供内部使用的提供同主体盖章的《APP支付申请承诺函》；② App 主体与商户号主体不一致时，由 App 管理员登录开放平台【移动应用 -> 详情 -> 能力专区 -> 微信支付 -> 详情】在「待关联商户号」中确认授权；③ 多子商户接入时，按每个子商户各自的绑定关系取用 appid 下单，不要按渠道侧统一固定配置。
典型反例：把公众号或小程序的 appid 当作 APP 下单的 sub_appid 使用；多子商户接入时未按每个子商户的绑定关系取 appid，而是按渠道侧统一固定配置同一个 appid 下发全部子商户的交易。
见 4017312501-管理经营场景、4013070174-申请APP支付权限指引、4013289251-管理商户号绑定的APPID账号 

 下单返回「AppID与商家经营场景不匹配，请确认」，取不到 prepay_id，该子商户无法完成支付。 

 鸿蒙应用须在微信开放平台注册鸿蒙应用后再接入

 说明：HarmonyOS（鸿蒙）形态的应用使用微信开放平台能力前，需要在微信开放平台完成鸿蒙应用的注册或创建，不能沿用安卓 APK 侧已注册的应用信息。
正确应该怎么做：① 登录微信开放平台，按鸿蒙应用接入指引创建并注册鸿蒙应用；② 完成开放平台账号与应用认证，再按 APP 支付流程完成 APPID 与商户号绑定、APP 下单与 SDK 拉起。
见 微信开放平台-移动应用鸿蒙接入指引 

 鸿蒙形态的 APP 未注册鸿蒙应用时，无法正常使用开放平台与 APP 支付能力，支付无法拉起。

 开放平台登记的应用包名与应用签名须与 App 工程实际配置一致

 说明：APP 支付在调起支付阶段会校验调起方应用的应用包名与应用签名，是否与开放平台该移动应用 appid 的登记信息一致；安卓登记应用包名（AndroidManifest.xml 中声明的 package 值）与应用签名（由打包 keystore 生成的 32 位 md5 串），鸿蒙对应为 Bundle ID 与 Identifier，iOS 为 Bundle ID，登记值须与最终发布包的工程配置完全一致。
正确应该怎么做：① 在微信开放平台创建移动应用时，按 App 工程配置填写应用包名与应用签名（鸿蒙填 Bundle ID 与 Identifier），用签名生成工具由发布 keystore 生成签名串；② 包名或签名发生变更后，同步到开放平台【管理中心 / 修改应用 / 修改开发信息】中更新；③ 存在多渠道包、马甲包等不同变体时，以实际发起支付的那个包的配置为准登记；④ 接入 OpenSDK 后按官方 Android 接入指引完成工程配置。
典型反例：把调试 keystore 生成的签名登记到开放平台，而线上发布包使用另一套 keystore 打包；安卓应用运行在鸿蒙系统的安卓兼容容器内，SDK 取到的调用方标识是容器而非 App 本身；仅在开放平台创建了移动应用、未补充登记 Android 应用的包名与签名，就在安卓端用该 appid 调起支付。
见 4013070174-申请APP支付权限指引、4013070182-APP支付常见问题、4011936836-APP端开发步骤、4015478291-开发接入准备、创建移动应用APPID（微信开放平台）、Android应用包名和应用签名（微信开放平台）、OpenSDK安卓接入指引 

 调起支付时提示「包名不对，请检查包名是否与开放平台上填写的一致」「签名不对，请检查签名是否与开放平台上填写的一致」，或「暂时无法开通此服务 - 商家服务异常，请联系商家处理」，客户端回调 errCode=-1，无法拉起微信支付收银台；安卓端表现为「苹果可以拉起、安卓拉不起」。

 下单与调起支付须使用实际发起支付 App 自身的 appid 及对应的商户号、证书与密钥

 说明：下单传入的 appid 必须是实际拉起支付的那个 App 自己的 appid，不支持用 A 应用已开通权限的 appid 与商户号在 B 应用中预下单并拉起支付，也不支持通过两个 appid 做关联变相实现；同一商户号接入多个 App 时，各 App 还须使用与其自身绑定的商户号、API 证书与密钥（服务商模式的 sub_appid 取值与 appId/partnerId 配对见服务商分节）。
正确应该怎么做：① 每一个需要收款的对外发布 App 都在开放平台单独创建移动应用 appid，并单独申请 APP 支付权限、与商户号完成绑定；② 服务端用该 App 自己的 appid 调用 APP 下单接口获取 prepay_id；③ 客户端用同一 appid 组装 PayReq 并通过 sendReq 调起支付；④ 新接入的 App 复用原有支付业务代码时，逐项替换 appid、商户号、证书与密钥后再发起下单与调起。
典型反例：把 A 应用已开通权限的 appid 与商户号拿去在 B 应用预下单并拉起支付，或试图通过两个 appid 做关联绕过；商户号新增绑定另一公司的 App 后，仍沿用原 App 的 appid、商户号与密钥发起下单与调起；App 被第三方套壳重签名后仍使用原 appid 拉起支付。
见 4013070182-APP支付常见问题、4013070176-APP支付开发指引、4013070174-申请APP支付权限指引、4013289251-管理商户号绑定的APPID账号 

 调起支付返回「商户传入的APPID参数不正确」，客户端回调 errCode=-1，或提示签名不一致被拦截，用户无法完成付款。

 境外 APP 下单须使用官方 App 下单路径，请求 URL 与下单参数须匹配

 说明：境外（global）APP 支付有独立的下单路径 https://apihk.mch.weixin.qq.com/v3/global/transactions/app，请求 URL 与下单报文中的交易类型（trade_type=APP）必须匹配；此前部分请求可用、部分失败是微信支付侧版本升级灰度所致，正常情况一律要求字段值与请求 URL 匹配。
正确应该怎么做：① 按官方文档给出的 App 路径发起 APP 下单（官方同时确认 hk/v3/transactions/app 亦可用，但建议严格按文档路径请求）；② 不同交易类型（APP / Native 等）使用各自对应的下单 URL，不要复用同一 endpoint 承载不同 trade_type；③ 接入阶段核对下单响应是否返回 prepay_id，未返回时先核对请求 URL 与参数是否匹配。
典型反例：把全部 v3 下单请求统一发往同一 endpoint（如 .../transactions/native），而在报文里传 trade_type=APP。
见 4012356518-境外APP下单（global） 

 下单返回 200 但响应体无 content、拿不到 prepay_id，App 端无法拉起支付，APP 支付场景交易量掉 0。

 子商户 App 端交易须传子商户 App 的 appid 作为 sub_appid，调起支付 appId 与之保持一致

 说明：服务商模式下，用户若在子商户的 App 端下单，须在 sub_appid 传入子商户 App 对应的 appid；在服务商 App 端下单时该参数可以不传。服务商自身没有移动 App 时，无需注册机构自身的 appid。
正确应该怎么做：① 在微信开放平台为子商户 App 创建移动应用并取得 appid（登记正确的应用包名与应用签名）；② 服务端下单时按实际发起支付的 App 归属传参：子商户 App 端发起的传 sub_appid，服务商 App 端发起的可不传；③ 子商户 App 端通过 OpenSDK 使用同一 appid 调起支付。
典型反例：机构/服务商自身没有 App，仍去注册机构 appid 用于下单；或用机构 appid 下单却在子商户 App 端调起支付。
见 4013080246-APP支付开发指引（服务商）、4013080228-开发接入准备（服务商） 

 下单传参与实际调起支付的 App 不匹配，无法唤起微信收银台，用户无法完成付款。

 调起支付的 appId 与 partnerId 须按下单时的 appid 与商户号配对传值

 说明：调起支付的 appId 须为下单时传入的服务商 sp_appid 或子商户 sub_appid，并与实际调起支付的 APP 相对应；partnerId 必须与 appId 同属一方主体：appId 填 sp_appid 时 partnerId 填服务商商户号 sp_mchid，appId 填 sub_appid 时 partnerId 填子商户号 sub_mchid（普通商户模式下对应为 appId 填下单的 appid、partnerId 填下单的 mchid）。下单时 sp_appid 需与 sp_mchid 有绑定关系，sub_appid 需与 sub_mchid 有绑定关系。
正确应该怎么做：① 下单前先确定本次交易在哪个 APP 端调起：在服务商 APP 端调起则下单传 sp_appid，在子商户 APP 端调起则下单传 sub_appid；② 服务端用下单返回的 prepay_id 组装调起支付参数时，按上述配对关系填充 appId 与 partnerId，两者须取自同一笔下单请求中相互对应的 appid 与商户号；③ App 端用这组参数（appId、partnerId、prepayId、package、nonceStr、timeStamp 及对应签名）通过 OpenSDK 的 sendReq 调起收银台。
典型反例：将调起支付的 appId/partnerId 在商户 APP 侧硬编码为一组固定值，未按「在哪一端调起支付」与下单参数对齐，形成 appId 取自一方、partnerId 取自另一方的错配；下单已传 sub_appid，调起时却填写与本次下单无关的第三方 appid；下单传子商户 appid、调起 SDK 仍传服务商 appid。
见 4013080233-APP调起支付（服务商）、4013080246-APP支付开发指引（服务商）、4013080231-APP下单（服务商）、4011941437-APP支付调起支付接口（服务商·APIv2）、4013070351-APP调起支付 

 下单接口返回 APPID_MCHID_NOT_MATCH，提示「appid和mch_id不匹配，请检查后再试」，订单无法创建；下单成功但调起支付传入的 appId 与下单 appid 不一致时，返回 errCode=-1（「注册的APPID与设置的不匹配」）、iOS 端弹出 appid 不一致提示，用户被拒绝拉起微信收银台。

 Android 端调起支付须避免 sendReq 阻塞主线程

 说明：微信 OpenSDK 的 sendReq 内部包含跨进程调用（经 ContentResolver 向微信查询 token），在主线程执行可能长时间阻塞。
正确应该怎么做：① APP 端发起微信支付或授权时，将 IWXAPI.sendReq 放到子线程执行；② 同时按官方 Android 接入指引完成工程配置，实现 WXPayEntryActivity 类，并在 Android 13 及以上去除其 intent-filter。
见 4013070176-APP支付开发指引、微信开放平台 Android 接入指引 

 应用主线程被阻塞触发 ANR，支付或授权界面卡死，用户无法完成付款。

 安卓 App 须按官方 OpenSDK 指引实现 WXPayEntryActivity 回调类

 说明：支付完成后从微信返回商户 App、以及接收支付结果回调，均由商户 App 侧通过微信 OpenSDK 自行实现；安卓端必须在自身应用包内提供 .wxapi.WXPayEntryActivity 并在 AndroidManifest.xml 中按官方写法声明，不能沿用其它自定义写法或只在 SDK 工程中处理。
正确应该怎么做：① 在应用工程（而非 SDK 工程）内实现 public class WXPayEntryActivity extends Activity implements IWXAPIEventHandler，在 onResp 中处理支付结果；② 在 AndroidManifest.xml 中声明该 Activity：android:name=".wxapi.WXPayEntryActivity"、android:exported="true"、android:taskAffinity="填写你的包名"、android:launchMode="singleTask"；③ 面向 Android 13 及以上时，在该 Activity 上去除 intent-filter，否则系统会屏蔽不匹配的 intent；④ 收到 onResp 后由商户后端调用查询订单接口确认最终支付状态，不要仅以回调作为入账依据。
典型反例：在 SDK 模块而非 App 主工程中处理支付回调；沿用非官方写法封装回调类。
见 4013070176-APP支付开发指引、4013070351-APP调起支付、微信开放平台 Android 接入指引 

 支付完成后点击「返回商家」仍停留在微信界面，无法跳回商户 App；onResp 回调不触发，商户 App 前端拿不到本次支付结果，只能依赖后端查单或用户主动返回。

 走国密（SM2）通道时，须确保服务商国密证书已申请配置且未过期

 说明：下单返回中 sign_type 为 SM2 说明该商户走国密通道；国密通道需先为该商户号申请开通国密权限，并在商户平台申请、下载国密 API 证书，证书未配置或已过期会导致验签失败。
正确应该怎么做：① 联系微信支付技术支持并提供商户号，申请开通国密权限；② 由商户号超级管理员登录商户平台【账户中心 - API安全 - 申请API证书 - 管理证书 - 申请新证书】，用证书工具生成公私钥与 CSR，上传后生成并下载国密 API 证书；③ 调用获取平台证书接口时传 algorithm_type=SM2 获取国密平台证书；④ 将国密证书有效期纳入巡检，到期前完成更换。
见 4012082627-国家商用密码简介（服务商）、4012082628-获取国家商用密码证书和密钥（服务商）、4013080245-APP支付常见问题（服务商） 

 下单可正常返回 prepay_id，但在调起支付阶段报「支付验证签名失败」，用户无法完成付款。