接入易错点

 开通 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。 

 下单传入的 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支付产品介绍 

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

 上报场景信息时 scene_info.payer_client_ip 必传，不传 scene_info 则可不传

 说明：Native 下单接口中 scene_info 整体为非必填参数，只有在业务场景需要上报场景信息（门店、设备等）时，其中的 payer_client_ip 才是必填项。
正确应该怎么做：① 先判断该笔下单是否需要上报场景信息；② 需要上报时组装 scene_info 对象，并必填其中的 payer_client_ip（用户终端 IP，支持 IPv4 与 IPv6）；③ 不需要上报场景信息时，不传 scene_info，也不必单独传 payer_client_ip。
典型反例：看到接口文档中 payer_client_ip 标记为必填，就在未传 scene_info 的报文中单独补传该字段。
见 4012791877-Native下单 

 需要上报场景信息却漏传 payer_client_ip 时，下单接口的参数校验不通过，无法获取 code_url；不需要上报场景信息时单独传该字段，也不符合接口的参数结构要求。 

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

 说明：申请退款接口返回成功仅表示退款单已被受理，不代表退款已成功。
正确应该怎么做：① 以退款结果通知或查询单笔退款接口返回的状态作为退款终态依据；② 提交退款申请后按建议每间隔 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下单 

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