API规则

更新时间：2025.02.19

本章将介绍在开发过程中需要注意的API规则。

请求结果判断逻辑

机构或商户在收到接口请求返回信息后，需要根据对应字段及判断逻辑来确认该次请求的处理结果。否则会导致请求结果判断错误，引起交易状态同步错误的问题。

微信支付采用回包两层判断的逻辑，分别对应的返回字段为return_code和result_code, return_code代表的是该次请求的通信结果，result_code代表该次请求的业务处理结果。

以Submit Quick Pay API为例：

当return_code和result_code均返回SUCCESS，表示通信成功，业务处理成功，即该笔订单扣款成功；
当return_code返回SUCCESS, result_code返回fail，表示通信成功但业务处理失败。但遇到该情况，机构或商户不能直接判定业务处理失败，因为在某些极端情况下，可能出现返回业务处理失败但实际成功的情况，建议机构或商户在该种情况下轮询查单；
当return_code返回fail，则不会有result_code的返回，该次请求通信失败，可直接判定交易失败。

机构和商户在对接微信支付接口时，都需要遵循以上的判断顺序及逻辑。

注意：查询订单接口除了判断return_code和result_code外，最终的订单状态需要根据trade_state字段来确认。即return_code和result_code均返回SUCCESS也仅代表查询订单业务处理成功，但所查订单的状态需要参考trade_state的返回内容。

微信支付的API接口都有一定的调用频率限制，以防止对服务器产生过大压力，影响业务的正常运转。以下为常用接口的调用频率限制，请机构在系统逻辑设计时格外注意：

撤销接口仅可对刷卡支付使用，用于完成刷卡支付异常订单的闭环。

若当前订单已支付成功，撤销操作会对该订单发起退款；若当前订单尚未支付，撤销操作会对该订单进行关闭处理。

撤销接口同样支持重入，在撤销结果不明确的情况下，可重新请求撤销。商户或机构还可根据撤销接口返回的recall字段来判断是否需要重新请求撤销。

不存在的订单请求撤销接口会返回SUCCESS，以保证业务的正常进行。

对于非刷卡支付的场景，需要调用关单接口完成异常订单的闭环。

关单接口仅能对非成功状态的订单调用，支付成功的订单无法进行关单操作。

建议机构或商户在最后一次查单获取交易状态非SUCCESS情况下，立即调用关单接口，中间切勿留有时间差。

机构在调用统一下单接口时，需要将商户app对应的appid传入到sub_appid参数内。

子商户前端调用SDK时，注意参数均为子商户号信息，即appid为子商户APP的appid，partnerid为子商户在机构生成的子商户号sub_mch_id。

子商户在向机构请求发起交易时，需要传输用户的openid给机构。

机构在调用统一下单接口时，需要将子商户小程序的appid传入到sub_appid中，将子商户传输的openid传入到sub_openid参数。

子商户前端拉起支付时，传入参数均为子商户信息，即appid为子商户小程序对应的appid。