Product Documentation General instructions Access Guidelines FAQs

Close Order

Update Time：2025.03.11

This API needs to be called before a merchant wants to create a new order due to the Payer failing to pay for an order. The original order will be closed in order to avoid repeat payment. After an order is created in the WeChat payment system, if the Payer doesn't pay within the required time, no further operation can be performed in the system. To prevent the Payer from proceeding with their order, this API is called to close the order.

API intro

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

Request Method: POST

Certificate Requirements: No certificate is required.

Applicable Object: Common mode Institutional mode

Request Parameter

Field Name	ID	Type	Required	Description
Official Account ID	appid	String(32)	Yes	Specifies an 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
Merchant Order Number	out_trade_no	String(32)	Yes	Specifies an internal order number created by the Merchant’s system. Example: 1217752501201407033233368018
Random string	nonce_str	String(32)	Yes	32 characters or fewer. For more information, see Random String Algorithm . Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS
Signature	sign	String(64)	Yes	Specifies a signature. 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 field is only required when sign_type is HMAC-SHA256. Example：HMAC-SHA256

Example：

1<xml>
2   <appid>wx2421b1c4370ec43b</appid>  
3   <mch_id>10000100</mch_id>
4   <nonce_str>4ca93f17ddf3443ceabf72f26d64fe0e</nonce_str>
5   <out_trade_no>1415983244</out_trade_no>
6   <sign>59FF1DF214B2D279A0EA7077C54DD95D</sign>
7   <sign_type>HMAC-SHA256</sign_type>
8</xml>

Notes: Parameters are escaped in XML files and CDATA tags are used to illustrate that data is not parsed by XML parser.

Return Data

Field 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:

Field Name	ID	Type	Required	Description
Official Account ID	appid	String(32)	Yes	The Official Account ID submitted when calling the interface Example: wx8888888888888888
Merchant ID	mch_id	String(32)	Yes	The Merchant ID submitted when calling the interface Example：1900000109
Sub Official Account ID	sub_appid	String(32)	No	The Sub Official Account ID submitted when calling the interface 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	The Sub Merchant ID submitted when calling the interface 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	Specifies a signature. For more information, see Signature Algorithm . Example：C380BEC2BFD727A4B6845133519F3AD6
Service Result	result_code	String(16)	Yes	Set to SUCCESS or FAIL Example: SUCCESS
Service Result description	result_msg	String(32)	Yes	Detailed description of service result Example: OK
Error Code	err_code	String(32)	No	Please refer to Error Codes Example：SYSTEMERROR
Error Code Description	err_code_des	String(128)	No	The detailed description of error Example：System error

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[BFK89FC6rxKCOjLX]]></nonce_str>
7   <sign><![CDATA[72B321D92A7BFA0B2509F3D13C7B1631]]></sign>
8   <result_code><![CDATA[SUCCESS]]></result_code>
9</xml>

Error Codes

Name	Description	Reason	Solution
ORDERPAID	Order is paid.	Order is paid and cannot be closed.	Order is already paid and cannot be closed. Treat the transaction as SUCCESS. Or initiate a refund to reverse the order.
SYSTEMERROR	System error	System error	System exception has occurred. Call this API again.
ORDERNOTEXIST	Order does not exist.	This order does not exist in the system.	Don’t attempt to close this order yet as it is still a pending transaction.
ORDERCLOSED	Order is closed.	Order is closed and cannot be done again.	Order is already closed and no further operation is required.
SIGNERROR	Signature error	Incorrect signature result	Check whether signature parameter and method comply with signature algorithm requirements.
REQUIRE_POST_METHOD	Use post method	Data is not transferred by post.	Check whether data is submitted by POST method.
XML_FORMAT_ERROR	INVALID XML FORMAT	INVALID XML FORMAT	Check whether XML parameters are in correct format.