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

      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>