Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

alipay.acquire.cancel

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

ParameterDescription
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

ParameterDescription
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.

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:

  1. 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.
  2. 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:

  1. 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.
  2. 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>