Correct request result judgment logic
After receiving information returned from a requested API, the institution/merchant needs to confirm the request result based on corresponding fields and judgment logic. Incorrect judgment will cause errors in transaction status synchronization.
WeChat Pay uses the two-layer judgment logic in its response packet, including return_code and result_code, where return_code indicates the communication result for this request and result_code indicates the business processing result for this request.
For example, when the Submit Quick Pay API is called:
-
1
If both return_code and result_code return with SUCCESS, then both communication and business processing have succeeded, indicating payment success for the order.
-
2
If return_code returns with SUCCESS and result_code returns with FAIL, then communication has succeeded while business processing has failed. Though in this case, the institution/merchant cannot consider business processing to have failed, because an extreme condition may exist where business processing has succeeded but a failure message has been returned. Therefore, polling is required for order query.
-
3
If the return_code returns as FAIL, no result_code will return, because failed communication indicates transaction failure.
The preceding judgment logic and rules must be followed for integrating WeChat Pay APIs.
Note: For the Query Order API, besides return_code and result_code, the final order status must be determined based on the trade_state field. This means even if both return_code and result_code return with SUCCESS, it only means that the order query has been successfully processed, while the order status must be determined based on the returned information of trade_state.
API calling frequency
The frequency of calling WeChat APIs is limited to prevent stressing out the server, which may affect business running. Pay attention to the following API calling frequencies during system logic design:
| Frequency Limit (QPS) |
API |
Frequency |
| Query Order |
1800 |
| Unified Order |
600 |
| Apply for Refund |
150 |
| Query Refund |
300 |
| Quick Pay |
30 |
| Apply for Declaration |
600 |
| Register Sub-merchant |
30 |
Revoke API
The Revoke API is only applicable to Quick Pay, for closed-loop control of abnormal Quick Pay orders.
If the current order has been paid, calling the Revoke API will initiate a refund; if the current order has not been paid, calling the Revoke API will close the order.
If the revocation result is unclear, the API can be called for a second time. Whether a second revocation request is needed can be determined based on the recall field returned by the Revoke API.
SUCCESS will be returned by the Revoke API if the current requested order does not exist, ensuring normal business operation.
Close Order API
For scenarios that do not use Quick Pay, the Close Order API should be called to close abnormal payment orders.
This API can be called only for orders in a non-SUCCESS status. Paid orders cannot be closed.
If the queried transaction status is not SUCCESS in the last order query request, the Close Order API must be called immediately.
In-App Payment (in institution mode)
When calling the Unified Order Placement API, the institution needs to pass the appid of the merchant's app to the sub_appid parameter.
Note that when the sub-merchant calls the SDK on the frontend, all passed parameters are information about the sub-merchant. The appid is the appid of the sub-merchant's app, and partnerid is the sub_mch_id of the sub-merchant generated by the institution.
Mini Program Payment (in institution mode)
The sub-merchant needs to pass the user's openid to the institution when initiating a transaction request.
When calling the Unified Order Placement API, the institution needs to pass the appid of the sub-merchant's Mini Program to the sub_appid parameter and pass the openid passed by the sub-merchant to the sub_openid parameter.
When WeChat Pay is opened on the sub-merchant's frontend, all incoming parameters are information about the sub-merchant. The appid is the appid of sub-merchant's Mini Program.
