cancel

2022-04-07 08:13

POST /v1/payments/cancel

Use this API to cancel the payment if the payment result is not returned after a long time. The cancellation cannot be performed if being out of the cancellable period specified in the contract. Use the same paymentId or paymentRequestId that is used in the payment API to cancel the payment transaction.

Structure

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

Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

If the data type of a field is Integer and its value is 20, set it as "20".
If the data type of a field is Boolean and its value is true, set it as "true".

Request parameters

paymentId String

The original payment ID of the payment request to be canceled, generated by Alipay to uniquely identify the payment when the merchant initiates the original payment. paymentId and paymentRequestId cannot both be null. A one-to-one correspondence between paymentId and paymentRequestId exists.

More information about this field

Maximum length: 64 characters

paymentRequestId String

The original payment request ID of the payment request to be canceled, generated by the merchant to uniquely identify a payment request. paymentRequestId and paymentId cannot both be null. If both paymentRequestId and paymentId are provided, paymentId takes precedence.

More information about this field

Maximum length: 64 characters

Response parameters

result Result object REQUIRED

Indicates whether this API is called successfully. If this API is successfully called, the payment is cancelled successfully.

Show child parameters

paymentId String

The unique ID that is assigned by Alipay to identify a payment.

Note: This field is returned when the cancellation succeeds (the value of result.resultStatus is S).

More information about this field

Maximum length: 64 characters

paymentRequestId String

The unique ID that is assigned by a merchant to identify a payment request.

Note: This field is returned when the cancellation succeeds (the value of result.resultStatus is S).

More information about this field

Maximum length: 64 characters

cancelTime Datetime

The actual execution completion time of the payment cancellation process, which is the date and time when the payment cancellation succeeds.

Note: This field is returned when the cancellation succeeds (the value of result.resultStatus is S).

More information about this field

The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:00".

API Explorer

Sample CodesRun in Sandbox

Request

URL

Request Body

Response

Case

Success

Response Body

Result process logic

For different request results, different actions are to be performed. See the following list for details:

If the value of result.resultStatus is S, the cancellation succeeds.
If the value of result.resultStatus is F, the cancellation fails. See the returned error code and determine further actions.
If the value of result.resultStatus is U, the cancellation result is unknown. Use the same request parameters to retry the cancellation request.
If no response is returned, use the same request parameters to retry the cancellation request.

Result/Error codes

Code	Value	Message	Further action
SUCCESS	S	Success	The order is canceled successfully. Set the order status of receipt to cancel.
ACCESS_DENIED	F	Access is denied.	Contact Alipay Technical Support for detailed reasons.
API_INVALID	F	The API name or API call format is used incorrectly.	Check whether the API name, HTTP method, or request format is correct when sending the request.
CANCEL_WINDOW_EXCEED	F	The cancellation date exceeds the period during which cancellation is supported. The period is agreed upon in the contract.	The transaction cannot be canceled anymore.
CLIENT_INVALID	F	The client ID is invalid. Alipay has restrictions on client ID.	Check whether the client ID is correct, or contact Alipay Technical Support for detailed reasons.
INVALID_CONTRACT	F	The parameter values in the contract do not match those in the current transaction.	Check whether the parameter values in the contract match those in the current transaction. If the values match, contact Alipay Technical Support to troubleshoot the issue.
INVALID_SIGNATURE	F	The signature is not validated. The private key used to sign a request does not match the public key of Alipay Developer Center.	Check whether the private key used to sign a request matches the public key of Alipay Developer Center. The following signature references are useful: The signature field in a request header How to calculate a signature
KEY_NOT_FOUND	F	The private key or public key of Alipay or the merchant is not found.	Check whether the private key or public key exists. If not, upload the private key in Alipay Developer Center.
MEDIA_TYPE_NOT_ACCEPTABLE	F	The server does not implement the media type that is acceptable to the client.	Check whether the media type is correct and use a media type that is accepted by Alipay.
MERCHANT_BALANCE_NOT_ENOUGH	F	The merchant balance is insufficient.	Call the interface again after the merchant has sufficient balance.
MERCHANT_NOT_REGISTERED	F	The merchant is not registered.	Please register the merchant by using the registration interface. Contact Alipay Technical Support if failed to call the registration interface.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method. Only the POST method is supported.	Ensure the HTTP method is POST.
NO_INTERFACE_DEF	F	API is not defined.	Check whether the URL is correct. Please refer to the endpoint in the API documentation.
ORDER_NOT_EXIST	F	The order does not exist.	Check whether paymentId is correct. If correct, contact Alipay Technical Support for specific reasons.
PARAM_ILLEGAL	F	The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong.	Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid.
PROCESS_FAIL	F	A general business failure occurred.	Do not retry. Human intervention is usually needed. It is recommended that you contact Alipay Technical Support to troubleshoot the issue.
SYSTEM_ERROR	F	A system error occurred.	Do not retry, and contact Alipay Technical Support for more details.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	The request traffic exceeds the limit.	Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support.
UNKNOWN_EXCEPTION	U	An API call has failed, which is caused by unknown reasons.	Call the interface again to resolve the issue. If not resolved, contact Alipay Technical Support.