/v2/payments/cancel

2023-05-31 12:13

POST /v2/payments/cancel

With this API call, a merchant can cancel a payment in the following states:

The payment that is authorized but not captured.
The payment that is not confirmed by a user.

Structure

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

Request header

Field	Data type	Required	Description	Example
Agent-Token	String	No	An agent token that is issued by the merchant to authorize its ISV for API calls. Specify this parameter if an ISV calls the API in behalf of a merchant.

Request parameters

Field	Data type	Required	Description	Example
paymentId	String	No	Indicates the unique ID assigned by the super app to identify the payment to be canceled. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? Can be`Null`. Note: This field is required when the value of paymentRequestId is `Null`.	"20190612184010800100188820200355884"
paymentRequestId	String	No	Indicates the unique ID assigned by the merchant to identify a payment request. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? Can be`Null`. Note: This field is required when the value of paymentId is `Null`.	"pay_2089760038715669_202775745075669"
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 4096 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	{ "memo": "memo" }

Response parameters

Field	Data type	Required	AMS	Description	Example
result	Result	Yes	一致	Indicates the request result such as result status and error codes.	{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }
paymentId	String	No	一致	Indicates the unique ID assigned by the super app to identify the payment to be canceled. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	"20190612184010800100188820200355884"
paymentRequestId	String	No	一致	Indicates the unique ID assigned by the merchant to identify a payment request. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	"pay_2089760038715669_202775745075669"
cancelTime	Datetime	No	一致	Indicates the actual date and time when the payment cancellation is successful. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30". Note: This field is returned when this API call is successful (the value of result.resultStatus is `S`).	"2019-06-12T14:11:35+08:00"

Result process logic

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

Result status	Description
S	The cancellation is successful. No further action is needed. The corresponding result.resultCode is `SUCCESS`and result.resultMessage is `SUCCESS`.
U	The status of the cancellation 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 cancellation is failed. The corresponding result.resultCode and result.resultMessage are various based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

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

Error code	Result status	Error message	Further action
CANCEL_WINDOW_EXCEED	F	The cancellation date exceeds the period during which cancellation is supported.	The transaction cannot be canceled anymore.
ORDER_NOT_EXIST	F	The order does not exist.	Use a valid paymentId or paymentRequestId.

Samples

The data flow of payment cancellation is illustrated as below:

The merchant server calls this API to request the super app server to cancel the payment.
The super app server returns the cancellation result to the merchant server.

Request

copy
{
    "paymentId":"20191127190741010007013213123",
    "paymentRequestId":"201231231313123123",
}

Response

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S"
 },
 "paymentId":"20191127190741010007013213123",
 "paymentRequestId":"201231231313123123",
 "cancelTime":"2021-06-08T12:12:12+08:00"
}

The payment (20191127190741010007013213123) is canceled successfully at the cancelTime(2021-06-08T12:12:12+08:00).