/v2/payments/void

2021-07-21 11:23

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 payer or a merchant, and then return money to the payer.

There are 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.

Note: 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	Example
voidRequestId	String	Yes	The unique ID of a void request generated by a merchant. Max. length: 64 characters.	void_capture_2089760038715669_202775745075671
paymentId	String	Yes	The payment ID of the original authorization to be voided. Max. length: 64 characters.	20190612114010800100188820200355883
voidRemainingAmount	boolean	No	Void all of the remaining payment amount after the payment or authorization is completed.	false
voidAmount	Amount	No	The void payment amount.	copy `{ "currency": "USD", "value": "50" }`
extendInfo	String	No	The extension information that wallets and merchants want to describe. Max. length: 4096 characters.	copy `{ "memo": "memo"}`

Response

Property	Data Type	Required	Description	Example
result	Result	Yes	The request result, which contains information such as result status and error codes.	copy `{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }`
voidRequestId	String	No	The unique ID of a void request generated by a merchant. Max. length: 64 characters.	void_capture_2089760038715669_202775745075671
voidId	String	No	The unique ID of a void request is generated by the wallet. Max. length: 64 characters.	void_2089760038715669_202775745075671
extendInfo	String	No	The extension information that wallets and merchants want to describe. Max. length: 4096 characters.	copy `{ "memo": "memo"}`

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 open APIs.
API-specific error codes are listed in the following table.

resultCode	resultStatus	resultMessage
ACCEPTED_SUCCESS	A	The void request has been accepted successfully, which means the void request is under review.
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 payment that has been captured is not consistent with the refund 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	The payment void function is only available when the payment is captured. Direct payment cannot be voided.
REPEAT_REQ_INCONSISTENT	F	The submitted request is not consistent with the last one.
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"
}