接入易错点

 支付成功订单须退款，不得调用关单撤销

 说明：撤销（reverse）仅适用于付款码支付场景，JSAPI 等其他支付方式不支持撤销；查单应答中的 REVOKED 状态也仅付款码支付会返回，其他支付方式已支付后需通过申请退款接口退款。
正确应该怎么做：① 付款码支付结果不明时，按撤销订单接口说明调用撤销；② JSAPI、APP、Native、H5 等已支付订单需要退回资金时，调用申请退款接口；③ 对账时区分 REVOKED 与 REFUND，按实际交易类型登记。
典型反例：JSAPI 订单被业务方标记为“撤销”，实际却调用了退款接口，导致勾兑文件按退款登记而无法与原交易匹配。
见 4011937361-撤销订单、4012791859-商户订单号查询订单、4011939627-下载交易账单、4012791860-关闭订单、4013071036-申请退款 

 对不支持撤销的支付方式调用撤销无法完成资金退回；把退款登记成撤销会造成对账补登和勾兑差异。

 退款回调地址须至少配置一处并对齐环境

 说明：退款申请可在请求中传入 notify_url，或在商户平台/服务商平台的退款配置中设置回调地址，两处至少配置一处；接口传入 notify_url 后，平台配置的回调地址不再生效。
正确应该怎么做：① 准备可公网访问且不带参数的 HTTPS 回调地址；② 在申请退款时传入 notify_url，或在平台「交易中心-退款管理-退款配置」配置地址；③ 回调接收端完成验签、解密、幂等处理和 HTTP 成功应答；④ 未收到回调时主动调用查询单笔退款接口确认状态。
典型反例：申请时未传 notify_url，平台也未配置退款回调地址，却把回调通知作为唯一退款结果来源。
见 4013071196-退款结果通知、4013071031-订单退款开发指引、4013071041-查询单笔退款、4013071036-申请退款、4013080625-申请退款（服务商）、4013080628-退款结果通知（服务商）、4011935217-申请退款（V2）、4011935223-退款结果通知（V2）、4012082570-回调通知注意事项、4013080623-订单退款开发指引（合作伙伴）、4012791862-退款申请、4012791865-退款结果回调通知 

 两处都未配置时收不到退款结果通知，退款状态只能依赖主动查单；若也没有查单机制，退款单会长期停留在未确认状态。

 启用退款 IP 白名单后须同步生产出口 IP

 说明：退款请求的来源IP必须与退款IP白名单配置一致；不一致时接口返回 NOAUTH，提示「异常IP请求不予受理」。
；该配置按商户号生效，数据中心迁移或新增出口 IP 时须逐个核对实际用于退款的商户号，并保留旧出口 IP 直至迁移完成，见 4013071200-订单退款常见问题。
正确应该怎么做：① 商户号超管登录商户平台或合作伙伴平台，进入「交易中心→退款管理→退款配置→退款IP白名单→开启配置」；② 静态IP场景核对已配置IP列表与生产出口IP一致；③ 动态IP场景按页面能力关闭IP白名单限制；④ 配置后在目标环境验证退款请求来源地址。
典型反例：只把测试服务器出口IP加入白名单，生产切换后仍由另一出口IP调用退款；多实例部署未统一固定退款出口地址。
见 4013080629-订单退款常见问题（合作伙伴）、4013071200-订单退款常见问题、4011936647-APIv2服务商JSAPI申请退款 

 退款接口返回 NOAUTH「异常IP请求不予受理」，退款申请失败。 

 退款请求须按接口频率上限统一限流

 说明：同一商户号下申请退款接口成功请求不超过 150QPS，失败报错请求不超过 6QPS；同一订单的退款请求不超过 1QPM；一个月之前的订单另有独立降频要求，工单确认该类订单限制为 5000 次/分钟。
正确应该怎么做：① 在调用退款接口前按商户号建立统一限流，覆盖全部业务入口；② 同一订单的退款请求串行化并间隔不少于 1 分钟；历史订单使用独立队列按 5000 次/分钟控制并错峰；③ 收到 FREQUENCY_LIMITED/429 或 268448746 时先查询原退款单；④ 确认未受理后再降低频率，使用原退款单号和原参数退避重试。
典型反例：失败后立即并发重试且每次更换退款单号，或历史订单一月前批量补退不设独立限流。
注：一个月以前订单的 5000 次/分钟限制依据为工单结论，官方文档未单独成文。
见 4013071036-申请退款、4013071041-查询单笔退款（通过商户退款单号）、4014959631-微信支付退款最佳实践、4020801246-订单退款错误码、4012791862-退款申请、4013080625-服务商申请退款、4011936647-APIv2服务商JSAPI申请退款、4012476892-平台收付通申请退款、4011935217-申请退款、4011973419-申请退款、4011941447-申请退款 

 返回 HTTP 429 FREQUENCY_LIMITED 或 268448746「单笔订单退款频率限制」，退款申请可能不受理；历史订单集中补退会形成积压，换单高频重试还会增加重复退款风险。 

 须区分商户退款单号与商户订单号

 说明：out_trade_no/transaction_id 用于标识原支付订单，out_refund_no/refund_id 用于标识退款单；两类编号不得混用，同一商户退款单号仅对应一笔退款。
正确应该怎么做：① 建立业务单、原支付订单、退款单的一对多映射并持久化；② 申请退款时用原支付订单标识定位交易，为本次退款生成并保存唯一 out_refund_no；③ 查询与通知处理均以退款单标识归并，不用商户订单号替代退款单号；④ 同一退款重试复用原退款单号，新增独立退款才生成新单号。
典型反例：把商户退款单号当商户订单号查询原交易，或把已支付订单号当作退款单号重试。
见 4013071036-申请退款、4013071041-查询单笔退款（通过商户退款单号）、4013080625-申请退款、4014959631-微信支付退款最佳实践 

 可能返回「支付单号校验不一致，请核实后再试」，或在结果不明时重复退款；新增部分退款可能无法受理。

 退款申请后须完整读取并保存同步响应

 说明：申请退款接口会同步返回退款单信息，返回成功仅表示退款单已受理；HTTP 客户端超时只应覆盖同步受理环节，不应配置为分钟级。
正确应该怎么做：① 设置合理的连接、读取与总超时，完整读取并解析响应体；② 持久化 refund_id、out_refund_no、金额及当前状态；③ 超时或解析失败时按 out_refund_no 查询退款，确认未受理后才使用原单原参数重试；④ 将同步响应、主动查询与退款结果通知归并到同一退款单。
典型反例：网关已收到受理响应但业务未读取，或超时后直接更换退款单号再次提交。
见 4013071031-订单退款开发指引、4013071036-申请退款、4013071041-查询单笔退款、4013071196-退款结果通知 

 退款请求长时间挂起、并发容量被占满；超时后直接换新退款单号重复发起，可能造成重复退款。

 退款关闭后须使用新退款单号重新发起

 说明：退款单处于 PROCESSING 超过 7 天且出资账户余额不足时，状态会流转为 CLOSED（v2 对应 REFUNDCLOSE）；该状态是终态，重新发起须补足资金并生成新的商户退款单号。退款请求若因用户账户受限等原因被明确拒绝、未获受理，限制解除后系统不会自动重试，须由商户在账户恢复正常后重新发起；原单为 CLOSED 的按前一句生成新单号。
正确应该怎么做：① 按商户退款单号查询退款单，确认 status=CLOSED 或 v2 refund_status=REFUNDCLOSE；② 检查并补足出资账户余额；③ 为本次退款生成新的 out_refund_no，重新调用申请退款接口；④ 记录新旧退款单号的关联，不要把旧单号作为新单的幂等键。
典型反例：看到退款关闭后，用原来的 out_refund_no 原参数反复重试，误以为可以继续完成原退款。
见 4013071031-开发指引、4013071200-常见问题、4013071036-申请退款、4011935218-查询退款 

 同一商户退款单号多次请求只退一笔，复用原单号无法生成新的退款，退款单仍保持关闭，用户持续收不到退款。

 商户退款单号须全局唯一，被占用时须换新号重新发起

 说明：商户退款单号 out_refund_no 在同一商户号下必须唯一，已经被占用（存在对应退款单）的单号不能再次用于创建新的退款单；只有原退款单未受理成功、单号尚未被占用的情形，才可以沿用原单号重试。
正确应该怎么做：① 采用全局唯一的规则生成 out_refund_no，不要用「日期+小序号」这类会在并发或跨店场景下重复的规则；② 退款失败先查单确认原单是否已被受理，未受理可沿用原单号重试，已受理或已占用则换用新的退款单号；③ 换新号重新发起前先核对原单状态，避免同一笔退款重复出款；④ 把被占用的单号纳入对账，确认旧单与新单的对应关系。
典型反例：不同订单复用同一个退款单号；或单号已被占用仍反复用同一个号重试，把「单号重复」当成系统故障等待自动恢复。
注：本条与「退款关闭后须使用新退款单号重新发起」相邻，后者针对 REFUNDCLOSE 关单场景，本条强调单号唯一性本身。

 退款请求被拒、退款单创建失败，售后流程卡住；若未核对原单就换新号重发，还可能造成同一笔交易重复退款。