Product Documentation General instructions Access Guidelines FAQs

Revoke Order

Update Time：2025.02.20

When a payment transaction isn't successfully returned or the payment system times out, this API is called to cancel the transaction. After revoking, the successful order will be refunded, while the failed order will be closed.

Tips：

This API can be called to cancel a transaction made within 7 days after an order is created, while the Submit Refund API should be used for transactions paid successfully. After a transaction is submitted, 【Query Order API】 needs to be called. When there is no clear query result, 【Revoke Order API】 needs to be called.
Please notice that Revoke Order API should be called at least 15s later after the order is created.

API intro

Request Url: https://apihk.mch.weixin.qq.com/secapi/pay/reverse

Request method: POST

Certificate Requirements：certificate is required.

Applicable object: Common mode Institutional mode

Parameter Settings

Name	ID	Type	Required	Description
Official Account ID	appid	string(32)	Yes	Specifies Official Account ID assigned by WeChat Example：wx8888888888888888
Merchant ID	mch_id	string(32)	Yes	Specifies merchant ID assigned by WeChat Payment Example：1900000109
Sub Official Account ID	sub_appid	string(32)	No	Specifies an Official Account ID assigned by WeChat Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note:Only for Institutional mode Example：wx8888888888888888
Sub Merchant ID	sub_mch_id	string(32)	Yes	Specifies merchant ID assigned by WeChat Payment Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note:Only for Institutional mode Example：1900000109
WeChat Order Number	transaction_id	string(32)	No	WeChat order number is preferred Example：1217752501201407033233368018
Merchant Order Number	out_trade_no	string(32)	Yes	out_trade_no is an internal order number within the Merchant’s system. transaction_id will be used over out_trade_no if they are both provided by the merchant. Example：1217752501201407033233368018
Random string	nonce_str	string(32)	Yes	32 characters or fewer or fewer. For more information, see Random string Algorithm Example：5K8264ILTKCH16CQ2502SI8ZNMTM67VS
Signature	sign	string(64)	Yes	For more information, see Signature Algorithm Example：C380BEC2BFD727A4B6845133519F3AD6
Sign type	sign_type	string(32)	No	Currently HMAC-SHA256 and MD5 are supported, default is MD5. This parameter must be submitted if HMAC-SHA256 is chosen Example：HMAC-SHA256/MD5

Example：

1<xml>
2   <appid>wx2421b1c4370ec43b</appid>
3   <mch_id>10000100</mch_id>
4   <nonce_str>b7ffb16a7150cf08639db472c5f5bdae</nonce_str>
5   <out_trade_no>1415717424</out_trade_no>
6   <sign>9B2EA16C05A5CEF8E53B14D53932D012</sign>
7</xml>

Return Data

Name	ID	Type	Required	Description
Return Status Code	return_code	string(16)	Yes	Set to SUCCESS or FAIL Specifies communicating label instead of transaction label. The status of the transaction is determined by the value of the result_code field. Example：SUCCESS
Return Data	return_msg	string(128)	No	If not empty, this is the error description. If not empty, this is the error description Signature Failure Parameter format checking error Example：Signature Failure

If return_code is SUCCESS, return data will also include the following fields:

Name	ID	Type	Required	Description
Official Account ID	appid	string(32)	Yes	Specifies Official Account ID assigned by WeChat Example：wx8888888888888888
Merchant ID	mch_id	string(32)	Yes	Specifies merchant ID assigned by WeChat Payment Example：1900000109
Sub Official Account ID	sub_appid	string(32)	No	Specifies an Sub Official Account ID assigned by WeChat Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note:Only for Institutional mode Example：wx8888888888888888
Sub Merchant ID	sub_mch_id	string(32)	Yes	Specifies Sub merchant ID assigned by WeChat Payment Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note:Only for Institutional mode Example：1900000109
Random string	nonce_str	string(32)	Yes	32 characters or fewer Example：5K8264ILTKCH16CQ2502SI8ZNMTM67VS
Signature	sign	string(64)	Yes	For more information, see Signature Example：C380BEC2BFD727A4B6845133519F3AD6
Service Result	result_code	string(16)	Yes	SUCCESS or FAIL SUCCESS indicates the order was paid for successfully and cannot be paid for again. If the payment is completed, a refund is initiated. FAIL refers to exceptions that occur in the interface. The recall function should be used to determine whether the order has been canceled or not; Example：SUCCESS
Error Code	err_code	string(32)	No	For more information, please refer to Error Code Example：SYSTEMERROR
Error Code Description	err_code_des	string(128)	No	The detailed description of error returned. Example：System error
Recall Requirement	recall	string(1)	Yes	Specifies whether recalling the Revoke Order API is required or not, Y：means yes while N：means no. Example：Y
Exchange Rate	rate	string(16)	Yes	The value is 10 to the 8th power times of the exchange rate from foreign currency to RMB. For example, the exchange rate from foreign currency to RMB is 6.5, the value will be 650000000 Example：650000000

Example：

1<xml>
2   <return_code><![CDATA[SUCCESS]]></return_code>
3   <return_msg><![CDATA[OK]]></return_msg>
4   <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
5   <mch_id><![CDATA[10000100]]></mch_id>
6   <nonce_str><![CDATA[o5bAKF3o2ypC8hwa]]></nonce_str>
7   <sign><![CDATA[6F5080EDDD196FFCDE53F786BBB93899]]></sign>
8   <result_code><![CDATA[SUCCESS]]></result_code>
9   <recall><![CDATA[N]]></recall>
10</xml>

Error Codes

Name	Description	Reason	Solution
SYSTEMERROR	API return error	System timed out	Try to call the Query Order API again
INVALID_TRANSACTIONID	Invalid transaction_id	Requested parameters are not correct	Parameter error. Check transaction_id again.
PARAM_ERROR	Parameter error	Requested parameters are not correct	Parameter error. Check parameters again.
REQUIRE_POST_METHOD	Use post method	Data is not transferred by post	Check whether data is submitted via POST method
SIGNERROR	Signature error	Incorrect signature result	Check whether signature parameter and method comply with signature algorithm requirements
INVALID_REQUEST	Invalid request	Merchant’s backend system issue	Please check the request parameters, whether the parameters are correct or whether the right certificate is used
REVERSE_EXPIRE	The order is out of reverse limit date	The Revoke API should be called within 7 days	Please check whether the order is in 7 days. If you truly want to revoke the order, please refund it.
USERPAYING	User is paying	Transaction in paying progress cannot be revoked	Please retry it later