alipay.acquire.cancel

2020-10-18 12:42

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	https://intlmapi.alipay.com/gateway.do
Test environment	https://mapi.alipaydev.com/gateway.do

Note:

If you use POST method, please specify the _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 is encoded. UTF-8, GBK, and GB2312 are 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, which is accurate to 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 transaction ID that is assigned by the merchant. If the ID is duplicated with out_trade_no of a previous transaction, the payment fails and an error message is returned to indicate the payment is duplicated.

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

Notes:

If the length range of the field is not specified, the Alipay system will not check the length of the field.
Do not use the halfwidth quotation mark (") in the value of the field.

#Synchronous response

Parameter Description

Basic parameter

is_success

String Required

Indicates whether the request succeeds or not, with a value of T for success or 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

Processing result of the cancel request, with a value of SUCCESS to indicate the cancellation is successful, FAIL to indicate the cancellation is failed, or UNKNOWN to indicate an unknown result.

Example:SUCCESS

trade_no

String(64)

Example:2013112011001004330000121536

out_trade_no

String(64)

The unique transaction ID that is assigned by the merchant. This parameter is transmitted by the corresponding request and needs to be returned with the original value.

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 or N for a non-retryable error.

Example:Y

action

String(10)

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

close: the transaction is to be closed.
refund: a refund is to be initiated for the transaction.

Example:close

detail_error_code

String(48)

Detailed error code, which describes the reason for not receiving a result_code of SUCCESS. If the response code of result_code is SUCCESS, this parameter is not returned.

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.

Note:

The synchronous response might have more parameters due to the upgrade on the Alipay server side. You can ignore parameters that are not included in this API document.

#Error codes

Error code	Description
SYSTEM_ERROR	Alipay system is not available in this moment. Action: Retry this request with the exact parameters. See Case 2 for detailed instruction.
ILLEGAL_SIGN	Illegal signature. Action: Retry to send the request with a legal signature.
INVALID_PARAMETER	Invalid parameter entered. Action: Check the value of requirements of each parameter according to the API document and enter valid parameters to try again.
ILLEGAL_ARGUMENT	Illegal argument. Action: Check each request parameter according to the API document. Contact Alipay technical support if this error persists.
ILLEGAL_PARTNER	Incorrect partner ID. Action: Ensure the value of the partner field matches the value provided by Alipay. Contact Alipay technical support if this error persists.
ILLEGAL_EXTERFACE	Interface configuration error. Action: Ensure that service parameters are entered correctly according to the API document. Contact Alipay technical support if this error persists.
ILLEGAL_PARTNER_EXTERFACE	Partner ID does not have the access privilege. Action: Ensure that your agreement with Alipay has been finalized. Contact Alipay technical support if this error persists.
ILLEGAL_SIGN_TYPE	Illegal sign type. Action: Ensure that the value of sign_type is MD5, RSA, or RSA2. Contact Alipay technical support if this error persists.
HAS_NO_PRIVILEGE	No privilege. Action: Contact Alipay technical support for help.
REASON_TRADE_BEEN_FREEZEN	Corresponding trade was frozen due to security issues. Action: Contact Alipay technical support for help.
TRADE_NOT_EXIST	The corresponding trade specified by the value of partner_trans_id doesn't exist. Action: Ensure that the value of partner_trans_id is correct. Contact Alipay technical support if this error persists.
TRADE_STATUS_ERROR	The trade status is not allowed for the current operation. Action: Ensure that the trade status is correct. Contact Alipay technical support if this error persists.
BUYER_ERROR	The buyer does not exist. Action: Contact Alipay technical support for help.
BUYER_ENABLE_STATUS_FORBID	Buyer account status prohibits the refund. Action: Contact Alipay technical support for help.
SELLER_ERROR	The seller does not exist. Action: Contact Alipay technical support for help.
MERCHANT_BALANCE_NOT_ENOUGH	Merchant balance is not enough for refund. Action: Try again later after new transactions occur.
TRADE_CANCEL_TIME_OUT	The cancellation request is beyond the opening hours. Action: Call the refund interface instead.
SELLER_BALANCE_NOT_ENOUGH	Insufficient balance of seller. Action: Try again later after new transactions occur.
REASON_TRADE_REFUND_FEE_ERR	Invalid refund amount. Action: Contact Alipay technical support for help.
TRADE_HAS_FINISHED	Transaction completed. Action: Use the refund interface to initiate a refund request instead.
REFUND_CHARGE_ERROR	The refund was failed because the payment is in progress. Action: Try again later.

#Result handling

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. Retry (every 3 seconds, up to 5 times.) this request with correct parameters until you get a response from Alipay.
If you still cannot get any response from Alipay, contact Alipay technical support for help.

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

is_success=F and error=SYSTEM_ERROR
is_success=T, result_code=FAIL, and detail_error_code=SYSTEM_ERROR
is_success=T and result_code=UNKNOWN.

Take the following actions:

Retry (every 3 seconds, up to 5 times.) this request with correct parameters until you get a response from Alipay.
If you still cannot get any response from Alipay, contact Alipay technical support for help.

Case 3. If you received the 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

Business is accepted and processed normally, and 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>

Request succeeds, but the business processing fails:

copy

<?xml version="1.0" encoding="utf-8"?> 
 <alipay> 
   <is_success>T</is_success> 
   <request> 
     <param name="sign">66b3a14ec95846f01d42564e6953c81b</param> 
     <param name="_input_charset">UTF-8</param> 
     <param name="sign_type">MD5</param> 
     <param name="service">alipay.acquire.cancel</param> 
     <param name="partner">2088101126765726</param> 
     <param name="out_trade_no">99003911198989</param> 
     <param name="timestamp">1456507705033</param> 
   </request> 
   <response> 
     <alipay> 
      <result_code>FAIL</result_code> 
      <detail_error_code>TRADE_STATUS_ERROR</detail_error_code> 
      <detail_error_des>illegal trade status</detail_error_des> 
     </alipay> 
    </response> 
    <sign>fc209d86b57b2adb23254a897ebaa7d9</sign> 
    <sign_type>RSA</sign_type> 
 </alipay>

Request 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>