alipay.acquire.cancel

2023-12-27 07:01

Call this interface to cancel a transaction. If the transaction is unpaid, the transaction will be closed. If the transaction is paid, the transaction will be refunded.

Request

Service address

Environment

HTTPS request URL

Production environment

Priority: https://globalmapi.alipay.com/gateway.do

Backup: https://intlmapi.alipay.com/gateway.do

Test environment

https://mapi.alipaydev.com/gateway.do

Note:

If you use POST method, please specify _input_charset in the request URL.

For example: https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8

Request parameters

Parameter Description

Basic parameter

service

String Required

Interface name

Example:alipay.acquire.cancel

partner

String(16) Required

The partner ID that is assigned by Alipay to identify an Alipay account. The partner ID is composed of 16 digits and begins with 2088.

Example:2088*********662

_input_charset

String Required

The charset with which the request data are encoded. UTF-8 is supported.

Example:UTF-8

sign_type

String Required

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

Example:MD5

sign

String Required

Sign value

Example:363a752668ee2b3b8f124c623bd028ad

timestamp

String Required

The time when the merchant server sends the request. The value is accurate to the millisecond.

Example:1456507704121

terminal_timestamp

String

The time when the terminal sends the request. The value is accurate to the millisecond.

Example:1456507704102

Business parameter

out_trade_no

String(64) Required

The unique order number in the merchant system

Example:990xxxxxxx8989

trade_no

String(64)

The serial number assigned by Alipay to identify a trade in the Alipay system, with a length in the range 16 - 64 bits. If out_trade_no and trade_no appear at the same time, trade_no takes precedence.

Example:2013112611001004680073956707

Synchronous response

Parameter Description

Basic parameter

is_success

String Required

Indicates whether the request succeeds or not, with a value of T for success and F for failure.

Note: a successful request does not mean the business is accepted and processed successfully.

Example:T

sign_type

String

Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.

Example:MD5

sign

String

Sign value

Example:fc209d86b57b2adb23254a897ebaa7d9

error

String

Error code that is returned when the request is failed to describe the request failure reason. For more information, see the Error Code section in this document.

Example:ILLEGAL_SIGN

Business parameter

result_code

String(32) Required

Response code of cancellation processing result, with a value of SUCCESS or FAIL.

SUCCESS: successful refund

FAIL: unsuccessful refund

Example:SUCCESS

trade_no

String(64)

The serial number assigned by Alipay to identify a trade in the Alipay system, with a length in the range 16 - 64 bits.

Example:2013112011001004330000121536

out_trade_no

String(64)

Unique order ID in order system in corresponding merchant’s website other than Alipay trade number. Uniqueness of this parameter in merchant’s website shall be guaranteed. This is a parameter transmitted upon corresponding request, which shall be returned in its original shape.

Example:990xxxxxxx8989

retry_flag

String(1)

Indicates whether the failed cancellation is caused by a retryable error. The value can be Y for a retryable error and N for a non-retriable error.

Example:Y

action

String(10)

Indicates how to perform the cancellation. The value can be one of the following items:

close: close the transaction
refund: make a refund for the transaction

Example:close

detail_error_code

String(48)

Detailed error code, which describes the reason for the returned response code. If the response code of result_code is SUCCESS, this parameter is not returned. For more information about the value of detail_error_code, see the Error Code section.

Example:TRADE_STATUS_ERROR

detail_error_des

String(64)

Explanation of the detailed error code. If result_code is SUCCESS, this parameter is not returned.

Example:Trade status is illegal.

Error codes

Error code	Description
SYSTEM_ERROR	Alipay system is not available. Action: Retry this request with the exact parameters. Refer to Case 2 in the following section for details.
ILLEGAL_SIGN	Illegal signature. Action: Use a legal signature and try again.
INVALID_PARAMETER	Parameter error. Action: Check each request parameter according to the API specification
ILLEGAL_ARGUMENT	Parameter error. Action: Check each request parameter according to the API specification. Contact Alipay technical support if this error persists.
ILLEGAL_PARTNER	Incorrect partner ID. Action: Ensure that the value of partner parameter matches the partner value provided by Alipay. Contact Alipay technical support if this error persists.
ILLEGAL_EXTERFACE	Interface configure error. Action: Ensure that the service parameter has the same value with the one in API specification. Contact Alipay technical support if this error persists.
ILLEGAL_PARTNER_EXTERFACE	The partner ID does not have access privilege. Action: Ensure that your agreement with Alipay has been finalized. Contact Alipay technical support if needed.
ILLEGAL_SIGN_TYPE	Illegal sign type. Action: Ensure that the value of sign_type is among MD5,RSA and RSA2. Contact Alipay technical support if this error persists.
HAS_NO_PRIVILEGE	Has no privilege. Action: Contact Alipay technical support.
REASON_TRADE_BEEN_FREEZEN	Corresponding trade has been frozen due to security issues. Action: Contact Alipay technical support.
TRADE_NOT_EXIST	Cannot find corresponding trade according to input partner_trans_id. Action: 1. Make sure the partner_trans_id is correct. 2. If the issue persists, contact Alipay Technical Support
TRADE_STATUS_ERROR	Corresponding trade status is not allowed for the current operation. Action: 1. Make sure the trade status is correct. 2. If the issue persists, contact Alipay technical support
BUYER_ERROR	The buyer does not exist. Action: Contact Alipay technical support.
BUYER_ENABLE_STATUS_FORBID	Buyer account status prohibits the refund. Action: Contact Alipay technical support.
SELLER_ERROR	The seller does not exist. Action: Contact Alipay technical support.
MERCHANT_BALANCE_NOT_ENOUGH	Merchant balance is not enough for the refund. Action: Try again later after new transactions occurred.
TRADE_CANCEL_TIME_OUT	The cancellation request is beyond the opening hours. Action: Use the refund interface instead.
SELLER_BALANCE_NOT_ENOUGH	Insufficient balance of the seller. Action: Try again later after new transactions occurred.
REASON_TRADE_REFUND_FEE_ERR	Invalid refund amount. Action: Contact Alipay technical support for help.
TRADE_HAS_FINISHED	The transaction is completed. Action: Use the refund interface instead.
REFUND_CHARGE_ERROR	The refund is failed because the payment is in progress. Action: Try again later.
FREQUENCY_LIMITED	The request's frequecy reaches the system limitation. Action: Try again later.

Handling errors

Case 1. When the invocation is failed due to network issue or request timeout, no response is returned from Alipay. Take the following actions:

Check your network connectivity to Alipay gateway and retry to cancel the request with the exact parameters until you get a response from Alipay. You need to retry the cancel request multiple times. It is recommended to retry the cancel request with incremental intervals of, such as 2s, 4s, 8s, 16s, 32s. The optimised number of retries and retry intervals are subject to solutions and network conditions, you can check with the Alipay technical support for details.
If the previous action doesn't work, you can turn to Alipay technical support for help.

Case 2. If you can receive the response from Alipay, check whether the returned parameters belong to one of the following situations:

is_success=F and error=SYSTEM_ERROR
is_success=T and result_code=FAIL and detail_error_code=SYSTEM_ERROR

If the returned parameters belong to one of the above situations, take the following actions:

Retry the cancel request multiple times. It is recommended to retry the cancel request with incremental intervals of, such as 2s, 4s, 8s, 16s, 32s. The optimised number of retries and retry intervals are subject to solutions and network conditions, you can check with the Alipay technical support for details.
If the previous action doesn't work, you can turn to the Alipay technical support for help.

Case 3. If you received response from Alipay, and is_success=T and result_code=SUCCESS, the merchant cancelled the order successfully.

Case 4. If you received the response from Alipay, and one of the following results is returned:

is_success=F and error=!SYSTEM_ERROR
is_success=T and result_code=FAIL and detail_error_code!=SYSTEM_ERROR.

The merchant failed to cancel the order. Refer to specific error code for instruction.

Pseudo code

copy
try{
  if(isCase3){ //CASE 3
    doSuccessProcess();
  }
  else if(isCase4){ //CASE 4
    doFailureProcess();
  }
  else{ //CASE 2
   
    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }

}catch (Exception ex){ // CASE 1

    retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 5 times.

    if(retrySuccess){
      doSuccessProcess();
    }
    else{
      //request Alipay tech support.
    }
  }
}

Samples

Request

Request sample with the out_trade_no field specified

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.cancel&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&out_trade_no=out_trade_no_20190904_151404&sign=fa57cabdbc0fc5bd583a66afdf2df62c

Request sample with the trade_no field specified

https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.cancel&partner=2088021966388155&_input_charset=UTF-8&sign_type=MD5&trade_no=2019090422001436530558497325&sign=7288cd48af8091b31c3c4cdc768ef5bd

Response

When a transaction is created and the Alipay transaction QR code is scanned by the customer, then the payment is successful and the cancellation is conducted successfully:

copy
<alipay>
    <is_success>T</is_success>
    <request>
        <param name="partner">208xxxxxxxxx8155</param>
        <param name="service">alipay.acquire.cancel</param>
        <param name="_input_charset">UTF-8</param>
        <param name="sign">7288cd48af8091b31c3c4cdc768ef5bd</param>
        <param name="trade_no">201xxxxxxxxxxxxxxxxxxxxx7325</param>
        <param name="sign_type">MD5</param>
    </request>
    <response>
        <alipay>
            <action>refund</action>
            <out_trade_no>out_trade_no_20190904_151744</out_trade_no>
            <result_code>SUCCESS</result_code>
            <retry_flag>N</retry_flag>
            <trade_no>201xxxxxxxxxxxxxxxxxxxxx7325</trade_no>
        </alipay>
    </response>
    <sign>69ac0fcec5f9b0b2e64c7dec82249feb</sign>
    <sign_type>MD5</sign_type>
</alipay>

When a transaction is created and the Alipay Transaction QR code is scanned by the customer, but the customer does not pay the transaction and the cancellation is conducted successfully:

copy
<alipay>
<is_success>T</is_success>
<request>
<param name="out_trade_no">TRADE_20220223021436</param>
<param name="partner">2088021966388155</param>
<param name="_input_charset">UTF-8</param>
<param name="service">alipay.acquire.cancel</param>
<param name="sign">94db99962f264473231296f4d042bd34</param>
<param name="sign_type">MD5</param>
<param name="timestamp">2022-02-23 02:15:57</param>
</request>
<response>
<alipay>
<action>close</action>
<out_trade_no>TRADE_20220223021436</out_trade_no>
<result_code>SUCCESS</result_code>
<retry_flag>N</retry_flag>
<trade_no>2022022322001400071445804662</trade_no>
</alipay>
</response>
<sign>71eb00f1c1a2fb7e0c6744d65275c7f0</sign>
<sign_type>MD5</sign_type>
</alipay>

When a transaction is created and the Alipay Transaction QR code has not been scanned by the customer, and the cancellation is conducted successfully:

copy
<alipay>
<is_success>T</is_success>
<request>
<param name="out_trade_no">TRADE_20220223021630</param>
<param name="partner">2088021966388155</param>
<param name="_input_charset">UTF-8</param>
<param name="service">alipay.acquire.cancel</param>
<param name="sign">ba98813e9fb59c48e4e97e3354d09f5d</param>
<param name="sign_type">MD5</param>
<param name="timestamp">2022-02-23 02:16:50</param>
</request>
<response>
<alipay>
<out_trade_no>TRADE_20220223021630</out_trade_no>
<result_code>SUCCESS</result_code>
<retry_flag>N</retry_flag>
</alipay>
</response>
<sign>f42abe0d6066814d6385d989388e3aed</sign>
<sign_type>MD5</sign_type>
</alipay>

When the request of pre-create endpoint fails or the data accessed are incorrect:

copy
<?xml version="1.0" encoding="utf-8"?> 
 <alipay> 
     <is_success>F</is_success> 
     <error>ILLEGAL_SIGN</error> 
 </alipay>