/v2/payments/void

2021-07-06 11:36

POST /v2//payments/void

The void API is used to void a paid order before the payment is captured or the order confirmed by a merchant or payer, and then return money to the payer. There are the following two types of voiding a paid order:

Partially void: To partially void a paid order will return a part of the payment amount to the payer. It will not change the order status. There is a timeout setting for the remaining payment amount. Once the time is out of the setting, the remaining payment amount will be voided or confirmed automatically.
Fully void: To fully void an order will close the order automatically.

The timeout setting is available when the remaining payment amount is voided or confirmed automatically if the session timeout is set.

Message structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see：

Request

Property	Data Type	Required	Description
voidRequestId	String	Yes	The unique ID of a void request generated by a merchant. Max. length: 64 characters.
paymentId	String	Yes	The payment ID of the original authorization to be voided. Max. length: 64 characters.
voidRemainingAmount	boolean	No	Void all of the remaining payment amount after the payment or authorization is completed.
voidAmount	Amount	No	The void payment amount.
extendInfo	String	No	The extension information that wallets and merchants want to describe. Max. length: 4096 characters.

Response

Property	Data Type	Required	Description
result	Result	Yes	The request result, which contains information such as result status and error codes.
voidRequestId	String	No	The unique ID of a void request generated by a merchant. Max. length: 64 characters.
voidId	String	No	The unique ID of a void request generated by the wallet. Max. length: 64 characters.
extendInfo	String	No	The extension information that wallets and merchants want to describe. Max. length: 4096 characters.

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

resultStatus	Description
S	The void is successful. The corresponding `result.resultCode`is "SUCCESS" and the `result.resultMessage` is "Success".
U	The status of the void is unknown. The corresponding `result.resultCode` is `UNKNOWN_EXCEPTION`, and `result.resultMessage` is "An API calling is failed, which is caused by unknown reasons". For details, see the Common error codes section.
F	The void fails. The corresponding `result.resultCode` and `result.resultMessage` may vary based on different situations. For details, see the Error codes section.

Error code

Error codes are usually classified into the following categories:

Common error codes are common across all mini program's APIs.
API-specific error codes: are listed in the following table.

resultCode	resultStatus	resultMessage
ACCEPTED_SUCCESS	A	Accepted successfully.
SYSTEM_ERROR	U	unknown system error
ORDER_NOT_EXISTS	F	The order does not exist.
ORDER_STATUS_INVALID	F	The order status is invalid.
ORDER_IS_FROZEN	F	The order is frozen.
ACCEPTED_IDEMPOTENT_ERROR	A	The request has been submitted and accepted.
CURRENCY_NOT_SAME	F	The currency of a user's payment is not the same as the original payment currency.
AMOUNT_EXCEEDS_LIMIT	F	The payment amount exceeds the limits.
MUTEX_OPERATION_IN_PROCESSING	F	There is another payment void, confirm, or capture in processing.
ORDER_UNSUPPORTED_OPERATION	F	void function is not allowed, e.g. for direct pay product
REPEAT_REQ_INCONSISTENT	F	Repeated submit, and requests are inconsistent.
MERCHANT_NOT_EXIST	F	The merchant does not exist.
USER_NOT_EXISTS	F	The user account does not exist.
USER_STATUS_ABNORMAL	F	The user status is invalid.
MERCHANT_STATUS_ABNORMAL	F	The merchant status is abnormal.

Samples

Request

copy

{
 "voidAmount": {
    "value":"1000",
    "currency":"USD"
 },
 "paymentId":"20191127190741010007013213121",
 "voidRequestId":"201231231313123124"
}

Response

copy

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S"
 },
 "voidId":"20191127190741010007013213190",
 "voidRequestId":"201231231313123124"
}