接入易错点

 开通 Native 支付前须完成已认证应用的 APPID 授权绑定

 说明：Native 支付支持的应用类型为已认证的服务号、已认证的政府或媒体类型的公众号、已认证的小程序、已认证的移动应用，须将其中至少一个已认证应用的 APPID 与商户号完成授权绑定；仅持有微信商户号、未绑定任何已认证应用 APPID 时无法开通 Native 支付收款能力。
正确应该怎么做：① 注册公众平台账号（服务号、政府或媒体类型的公众号、小程序）或开放平台账号（移动应用），并完成该账号的认证，未认证的账号无法绑定商户号；② 已有商户号的，由超级管理员登录商户平台申请 Native 支付产品权限，并发起与 APPID 的授权绑定申请；尚无商户号的，在申请商户号时同步申请 Native 支付权限，申请时填写服务号或公众号类型的 APPID，系统会在申请完成后自动对该 APPID 发起授权绑定申请；③ 登录公众平台或开放平台确认授权绑定的商户号，完成 APPID 与商户号绑定；④ 绑定完成后获取开发参数，进入开发流程。
典型反例：仅持有微信商户号、未申请并认证任何公众平台或开放平台应用就直接申请 Native 支付，认为有商户号即可收款；误以为服务号是唯一可选类型，未使用已完成认证的小程序或移动应用。
见 4012791874-Native支付产品介绍、4015614538-Native支付开发接入准备 

 无法开通 Native 支付产品权限并完成 APPID 授权绑定，商户不能生成收款二维码，用户扫码后无法完成付款。

 迁移或新增商户号后，APIv2 与 APIv3 须分别使用各自的密钥与证书签名，不得混用

 说明：同一商户号可同时支持 APIv2（XML 报文，签名算法为 MD5/HMAC-SHA256）与 APIv3（JSON 报文，使用商户 API 证书私钥生成签名）两种接入方式，两者使用的密钥不是同一套，需分别设置与保管。
正确应该怎么做：① 登录商户平台查看新商户号 API 安全页是否仍有 API 密钥配置，有则表示仍支持 APIv2（XML）模式；② 走 APIv3 时使用商户 API 证书私钥按 APIv3 签名规则生成签名；③ 走 APIv2 时按协议规则使用商户平台设置的 API 密钥做 MD5/HMAC-SHA256 签名；④ 迁移商户号时分别配置 APIv2 密钥与 APIv3 密钥，不得将两者设为相同值。
典型反例：迁移新商户号时把 APIv2 密钥设置成与 APIv3 密钥相同的值，或用 APIv3 密钥去签 APIv2 的 XML 报文。
见 4012365342-总述-APIv3如何签名和验签、4011986605-APIv2 Native支付协议规则 

 请求签名校验不通过，下单接口调用失败，无法获取 code_url。 

 签名所用商户 API 证书私钥须与请求头中声明的证书序列号一一对应

 说明：商户号、商户 API 证书、商户 API 证书序列号三者一一对应，请求 Authorization 头中的 serial_no 必须是本次用于签名的那张商户 API 证书（apiclient_cert.pem）的序列号，不能用平台证书，也不能混用不同商户的证书。
正确应该怎么做：① 用 openssl x509 -in apiclient_cert.pem -noout -serial 查询当前用于签名的商户 API 证书序列号，并核对证书对应的商户号与请求中的商户号一致；② 将该序列号填入请求头 serial_no，签名使用同一张证书配套的私钥 apiclient_key.pem；③ 测试商户号的商户 API 证书随开通邮件附件下发，须使用邮件中的证书与配套私钥。
典型反例：更换商户 API 证书后只在请求头填入新证书序列号，签名仍使用旧证书的私钥（或调试脚本里配置的私钥与序列号不配套）。
见 4012365345-报错：商户证书序列号有误。请使用签名私钥匹配的证书序列号、4012072428-申请商户API证书 

 签名校验不通过，请求被拒；工单中境外 Native 下单返回 HTTP 500、响应体为 {"code":"SYSTEM_ERROR","message":"系统繁忙, 请稍后重试"}，且不返回 request-id，无法获取该笔请求的处理结果。

 下单传入的 notify_url 不得携带查询参数

 说明：回调地址需按回调通知注意事项规范填写，notify_url 不能携带参数。
正确应该怎么做：① 使用不含 ? 及查询串的纯路径回调地址；② 需要区分业务类型时，用商户订单号 out_trade_no 或 attach 传递，或在回调处理时按订单号回查商户系统。
典型反例：把形如 https://xxx/notify.php?type=type2 的带查询串地址作为 notify_url 传入。
见 4012075420-回调通知注意事项、4012082570-回调通知注意事项 

 回调地址不符合官方填写规范，商户可能无法正常接收支付结果通知。

 二维码图片须由商户自行将 code_url 转换生成，微信侧不返回二维码图片

 说明：Native 下单接口只返回 code_url（二维码链接），不返回二维码图片，也不提供码值转换服务；code_url 并非固定值，重新下单会返回新的 code_url，原 code_url 随之失效。
正确应该怎么做：① 后端调用 Native 下单接口获取 code_url 并传给前端；② 使用二维码生成库按 URL 格式将 code_url 原样转换为二维码图片并展示；③ 需要刷新二维码时用原参数重入下单获取新的 code_url，再重新生成二维码图片。
典型反例：等待微信侧返回二维码图片，或在生成二维码前对 code_url 做转义、截断、拼接等二次加工。
见 4012791891-Native支付开发指引、4012791877-Native下单、4012791878-Native调起支付、4012791890-Native支付常见问题 

 无法生成可被微信识别的支付二维码，用户扫码后不能拉起收银台，交易无法发起。

 code_url 有效期为 2 小时，超时须用原下单参数重新下单获取新的 code_url 

 说明：Native 下单返回的 code_url（二维码链接）有效期为 2 小时，超过后需使用原下单参数重新请求下单接口获取新的 code_url；订单可支付的截止时间由 time_expire 控制，商户可按需传入该参数限定最晚支付时间。
正确应该怎么做：① 下单成功后记录下单时间，并将 code_url 转换为二维码图片展示给用户；② 展示页在 code_url 超过 2 小时或用户主动刷新时，用同一 out_trade_no 与原下单参数重新调用 Native 下单接口，获取新的 code_url 后刷新二维码；③ 需要限制用户支付时间时，在下单请求中传入 time_expire。
典型反例：一次性生成二维码后长期展示（页面缓存、物料复用同一张二维码图片），超过 2 小时后用户扫码失效。
见 4012791891-Native支付开发指引、4012791877-Native下单 

 用户扫描已超过有效期的二维码时无法拉起支付，订单停留在未支付状态，商户需重新下单才能继续收款。

 支付二维码须由用户使用微信“扫一扫”识别，不支持长按识别或从相册识别

 说明：Native 支付由商户将下单接口返回的 code_url 转换为二维码展示给用户，用户须使用微信“扫一扫”扫描该二维码调起收银台，通过长按识别或从相册识别二维码的方式均不支持完成支付；若业务要求用户在同一台设备上完成付款，该场景不属于 Native 支付，应选用 H5 支付或 APP 支付。
正确应该怎么做：① 商户后端调用 Native 下单接口获取 code_url 并下发给前端；② 前端将 code_url 转换为二维码图片展示，并在页面或物料上提示用户使用微信“扫一扫”扫码；③ 二维码超过 2 小时未支付时，用原下单参数重新调用下单接口并刷新展示的二维码；④ 用户需在当前设备内直接付款的场景，改用 H5 支付或 APP 支付承接。
典型反例：将支付二维码以图片形式发给用户，或投放到社群、公众号图文、下载页，引导用户长按图片识别或从相册选图识别后付款。
见 4012791891-Native支付开发指引、4012791878-Native调起支付、4012791874-Native支付产品介绍、4012791890-Native支付常见问题、4012791832-H5支付产品介绍、4013070158-APP支付产品介绍 

 用户长按识别时提示「该商户暂不支持通过长按识别二维码完成支付」，从相册识别时提示「为保障支付安全，暂不支持通过从相册识别二维码完成支付」，用户无法进入支付确认页；单设备场景下整笔交易无法完成，商户侧表现为该类订单支付成功率下跌。

 退款结果须以退款回调或查询退款为准，不得以申请退款同步响应判定成功

 说明：申请退款接口返回成功仅表示退款单已被受理，不代表退款已成功。
正确应该怎么做：① 以退款结果通知或查询单笔退款接口返回的状态作为退款终态依据；② 提交退款申请后按建议每间隔 1 分钟调用查询退款接口查询一次，若超过 5 分钟仍为处理中，再逐步衰减查询频率。
典型反例：把申请退款接口同步返回无错误码直接当作退款已到账，并据此结清商户侧订单状态。
见 4012791883-退款申请、4012791884-查询单笔退款（通过商户退款单号） 

 退款仍在处理中或后续失败时商户侧已按退款成功处理，出现用户实际未收到退款而商户订单已关闭的对账差异，引发客诉并带来重复退款风险。

 APIv3 未支付订单不会自动关闭，须主动查单并在超时后调用 /v3/pay/transactions/out-trade-no/{out_trade_no}/close 关单

 说明：支付成功回调通知仅在用户支付成功时下发，用户取消或放弃支付不会收到回调通知；订单未在支付截止时间前完成支付时，调用查询订单接口返回的交易状态仍为 NOTPAY，需由商户调用关单接口关闭订单，订单状态才会变为 CLOSED。
正确应该怎么做：① 下单时按业务需要传入 time_expire；② 商户后端在等待支付结果期间轮询调用查询订单接口获取交易状态，不以回调通知作为订单状态机的唯一驱动；③ 确认订单已超过支付截止时间仍为未支付状态时，调用关闭订单接口 POST /v3/pay/transactions/out-trade-no/{out_trade_no}/close 关单，再推进释放库存、关闭交易入口等后续处理。
典型反例：订单状态机只依赖回调通知驱动，未实现查单与关单兜底；仅以查询订单接口返回的状态判断订单是否已关闭，未主动调用关单接口。
见 4012791882-支付成功回调通知、4012791880-商户订单号查询订单、4012791881-关闭订单、4012791877-Native下单、4012791891-Native支付开发指引 

 不会收到任何取消通知，订单在商户系统内长期停留在待支付状态并占用库存或名额；未及时关单时同一业务单据无法重新下单，影响对账与用户重新下单。

 APIv3 主扫交易不使用撤销接口，未支付订单走 /v3/pay/transactions/out-trade-no/{out_trade_no}/close 关单、已支付订单走 /v3/refund/domestic/refunds 退款

 说明：撤销订单接口是付款码支付（B扫C）的专用能力，Native 等主扫交易不支持撤销；订单不再需要用户付款时用关单接口，用户已支付成功需要退回资金时用退款接口。
正确应该怎么做：① 对仍为未支付状态的订单，调用关闭订单接口 POST /v3/pay/transactions/out-trade-no/{out_trade_no}/close 关单；② 对已支付成功的订单，调用申请退款接口 POST /v3/refund/domestic/refunds 发起退款。
典型反例：把已支付成功的主扫订单当作“支付失败”去调用关单接口，或照搬付款码支付的做法对主扫交易调用撤销接口。
见 4011937361-撤销订单、4012791881-关闭订单、4012791883-退款申请 

 关单接口只作用于未支付订单，已支付订单的资金不会退回；照搬付款码支付调用撤销接口时主扫交易不会被撤销，出现用户已扣款但商户侧订单仍挂起的情况，产生客诉与人工退款成本。

 账单与结算文件不区分线上、线下交易，须自行用 out_trade_no 等字段标记区分

 说明：交易账单中的「交易类型」只按支付方式给出英文缩写（如 NATIVE），线上与线下的 Native 交易均归为 NATIVE，账单与结算文件中没有可用于区分线上、线下交易的字段。
正确应该怎么做：① 下单时为不同渠道的订单规划可识别的 out_trade_no 规则（如前缀区分线上商城与线下门店、DQR 场景）；② 需要按渠道对账或统计时，用 out_trade_no 或商户侧自定义字段在自身系统中区分，不依赖账单中的交易类型字段。
典型反例：计划直接按结算文件中的交易类型字段拆分线上与线下业务数据。
见 4013071246-交易账单详细说明、4012791877-Native下单 

 无法按账单或结算文件区分线上与线下交易，分渠道对账与统计需人工逐单核对。

 下单传入的 sub_mchid 须与 mchid 存在受理关系

 说明：服务商/机构模式下单时，请求中的子商户号必须是已在该服务商/机构号（mchid）下完成进件并建立受理（授权产品）关系的子商户号，两者须配套使用同一受理关系下的组合。
正确应该怎么做：① 确认所使用的机构号/服务商号为本机构实际进件主体，避免混用他方或测试用途的机构号；② 子商户号须由服务商为该子商户进件后取得，并在服务商平台「产品中心 → 特约商户授权产品」发起邀请，由子商户在商户平台「我的授权产品」中完成授权，授权后需等待数分钟生效；③ 下单前校验 mchid 与 sub_mchid 的配对关系，避免跨机构、跨主体组合。
典型反例：将测试用途的机构号与实际已进件的子商户号混用，导致请求中 mchid 与 sub_mchid 之间没有受理关系。
见 4020770377-Native支付错误码、4012738659-Native下单（服务商模式） 

 用户扫码支付时提示异常，无法完成付款；接口侧对应错误码 268443701「受理关系不存在（服务商）」。

 下单传入 sub_appid 时，该 sub_appid 须已与 sub_mchid 完成绑定

 说明：appid 是服务商（机构）侧绑定的服务商 APPID，sub_appid 是子商户绑定的子商户 APPID，二者一般不同；sub_appid 为选填，一旦传入就必须与请求中的 sub_mchid 存在绑定关系，未传时仅校验 appid 与 mchid 的绑定关系。
正确应该怎么做：① 先在服务商平台发起 APPID 关联申请、再由子商户侧登录对应平台确认授权，完成 sub_appid 与 sub_mchid 的绑定；② 确认绑定完成后再在下单请求中传入 sub_appid；③ 业务不需要指定子商户 APPID 时不传该字段。
典型反例：把服务商自己的 appid 当作 sub_appid 传入；或子商户尚未绑定该 APPID 就先在下单请求里带上 sub_appid。
见 4012738659-Native下单、4013352075-管理商户号绑定的APPID账号、4013287246-管理商户号绑定的APPID账号 

 下单返回 INVALID_REQUEST，错误描述「sub_mch_id与sub_appid不匹配」，该笔交易无法创建。 

 JSAPI 下单须传该 appid 下的 openid，Native、H5 下单无须传 openid 

 说明：JSAPI/小程序下单的 payer.openid 为用户在商户 appid 下的唯一标识，是必填参数，同一用户在不同 appid 下的 openid 并不相同；Native 下单与 H5 下单均无需传入 openid，下单 appid 只需与 mchid 存在绑定关系即可。
正确应该怎么做：① 使用 JSAPI/小程序支付时，先通过对应 appid 的登录授权获取用户 openid，再以下单所用 appid 对应的 openid 发起下单；② 使用 Native 支付、H5 支付时，直接使用与商户号已建立绑定关系的 appid 下单，无需获取或传入 openid；③ 机构未申请自有公众号或小程序 appid 时，可使用已与商户号建立绑定关系的 appid 开通 Native、H5 支付收款。
典型反例：以为所有支付产品都必须先用自有公众号 appid 换取 openid，进而判断未绑定自有公众号 appid 时线上支付一律不可用、只能做付款码类交易。
见 4012791856-JSAPI/小程序下单、4012791834-H5下单、4012791877-Native下单、4012068676-参数说明 

 JSAPI 下单因缺少必填的 openid 或所用 appid 与商户号无绑定关系而下单失败，用户无法完成付款。