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

      alipay.acquire.overseas.spot.refund

      Call this interface to issue a full or partial refund for a transaction. The refund request cannot be cancelled.

      #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.overseas.spot.refund

      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

      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:RSA

      sign

      String Required

      Sign value

      Example:e5815a4556db338ed237f7d3fd222184

      notify_url

      URL(200) Required

      The URL for receiving asynchronous notifications after the payment is completed.

      Example:https://www.test.com/alipay/notify_url.php

      Business parameter

      partner_trans_id

      String(64) Required

      The original partner transaction ID given in the payment request, which is:

      • the value of out_trade_no in the alipay.acquire.precreate interface.
      • the value of partner_trans_id in the alipay.acquire.overseas.spot.pay interface.

      Example:2010121000000002

      alipay_trans_id

      String(64)

      The Alipay transaction ID

      Example:201311221703338463

      partner_refund_id

      String(64) Required

      The refund order ID in the partner system. The value of partner_refund_id cannot be the same as that of partner_transaction_id. The partner_refund_id field plus the partner field identifies a refund transaction.

      Example:301012133000002

      refund_amount

      Number(9,2) Required

      Refund amount, which must be less than or equal to the original transaction amount or the left transaction amount if ever refunded.

      Example:39.25

      currency

      String(10) Required

      The refund currency. Use upper case. For more information about supported currencies, see Supported Currencies.

      Example:USD

      refund_reason

      String(128)

      Reason for the refund 

      Example:Refund the good

      is_sync

      String(1)

      Indicates that the refund request is processed synchronously or asynchronously with a value of Y or N. The default value is N, which means an asynchronous notification from Alipay is returned to the merchant if the merchant has set the value of the notify_url field when sending the refund request. If the value is set as Y, it means only a synchronous response is returned to the merchant. 

      Example:Y


      Note:

      The decimal place accuracy of amounts, such as the values of refund_amount, depend on the value of currency. If the value of currency isJPY, then the amount must be an integer. For example, 100 JPY. For other currencies, the amount is of two decimal place accuracy. For example, 100.00 USD. Amounts in other formats will cause error, for example, 100.999 USD.

      #Response

      #Synchronous response parameters

      #Parameters accepted by Alipay gateway:

      ParameterDescription

      is_success

      String(1) Required

      Indicate 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 Required

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

      Example:MD5

      sign

      String(32) Required

      Sign value 

      Example:59c7275cf3c82f038b7c0076f9888926

      result_code

      String(32) Required

      Processing result of the request. Possible values are:

      • SUCCESS: when the refund is synchronous, this field indicates that the refund is successful, the value of is_sync is Y. When the refund is asynchronous, this field indicates that the processing is accepted successfully, which does not mean the refund is processed successfully.
      • FAILED: indicates that the process is failed.

      Example:SUCCESS

      error

      String(48)

      Error code that is returned when the request is not successful, to describe the request failure reason. This field is not returned when the result_code is SUCCESS. For more information, see the Error Code section in this document.

      Example:TRANS_NOT_FOUND

      partner_trans_id

      String(64) Required

      The original partner transaction ID given in the payment request. This parameter is transmitted by the corresponding request and needs to be returned with its original value.

      Example:201311221000000002

      alipay_trans_id

      String(64)

      The transaction ID assigned by Alipay for the partner's payment request, which follows a mapping relation with the partner field plus the partner_trans_id field.

      Example:201311221703338463

      partner_refund_id

      String(64) Required

      The refund order ID in the partner system. The partner_refund_id field plus the partner field identifies a refund transaction. 

      Example:301012133000002

      refund_amount

      Number(9,2) Required

      Refund amount, which must be less than or equal to the original transaction amount or the left transaction amount if ever refunded. 

      Example:39.25

      currency

      String(10) Required

      The refund currency 

      Example:USD

      exchange_rate

      Number(8,6)

      The exchange rate between the currency given in the request to CNY. The exchange occurs when the Alipay trade order is created. 

      Example:6.0939

      refund_amount_cny

      Number(9,2)

      Refund amount in CNY. It is the exact amount that Alipay refunded. 

      Example:239.19

      #Parameters rejected by Alipay gateway:

      ParameterDescription

      is_success

      String(1) Required

      Indicates whether the request is accepted by the Alipay gateway.

      T: accepted

      F: rejected

      Example:F

      sign_type

      String Required

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

      Example:MD5

      sign

      String(32) Required

      Sign value

      Example:59c7275cf3c82f038b7c0076f9888926

      error

      String(48)

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

      Example:TRANS_NOT_FOUND

      #Asynchronous notification parameters

      Alipay notifies the merchant website of the result data processed through an initiative notification from the server after completing the processing of request data of merchant. These result data are asynchronous notification parameters from the server.

      ParameterDescription
      Basic parameter

      notify_time

      Timestamp Required

      The time when the notification is sent. The time format is yyyy-MM-dd HH:mm:ss. 

      Example:2013-11-27 15:45:58

      notify_type

      String Required

      Notification type 

      Example:refund_status_sync

      notify_id

      String Required

      Notification ID, used by the partner system to verify the notification 

      Example:ac05099524730693a8b 330c5ecf72da978

      sign_type

      String Required

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

      Example:MD5

      sign

      String Required

      Sign value

      Example:601510b7970e52cc63d b0f44997cf70e

      Business parameter

      out_trade_no

      String(64)

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

      Example:990xxxxxxx8989

      out_return_no

      String(64) Required

      The refund order ID in the partner system. If the merchant initiates the refund request on the Alipay website, this parameter is to be filled with an automatically generated number by Alipay. 

      Example:301012133000002

      refund_status

      String(64) Required

      The refund status. The value can be REFUND_SUCCESS for a successful refund or REFUND_FAIL for a failed refund.

      Example:REFUND_SUCCESS

      currency

      String(8)

      The refund currency

      Example:USD

      return_amount

      Number(9,2)

      The refund amount in the refund currency

      Example:1.00

      trans_refund_fee

      Number(9,2)

      The estimated refund amount in the original transaction currency, for reference only.

      Example:1.00

      error_code

      String

      The reason for a refund with status of REFUND_FAIL. This field is nulll when the refund_status is REFUND_SUCCESS.

      Example:ILLEGAL_SIGN

      #Error codes

      Error code

      Description

      SYSTEM_ERROR

      Alipay system is not available.

      Action: Retry this request with the exact parameters. Refer to Case 2 for detailed instruction.

      ILLEGAL_SIGN

      Illegal signature.

      Action: Use a legal signature and try again.

      INVALID_PARAMETER

      Parameter error.

      Action: Check the standard of 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 the 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 parameters 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 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 the value of partner_trans_id.

      Action: 1. Ensure that the value of 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. Ensure that the trade status is correct. 2. If the issue persists, contact Alipay technical support.

      REFUND_AMT_RESTRICTION

      The value of refund_amount is more than the original trade amount, or total refund amount is more than the original trade amount, which cannot be processed by Alipay.

      Action: Merchant needs to check if the returned amount is correct.

      REQUEST_AMOUNT_EXCEED

      Same as the REFUND_AMT_RESTRICTION error code.

      Action: Merchant needs to check if the returned amount is correct.

      TRADE_HAS_CLOSE

      The transaction is closed and refunds are not allowed anymore.

      Action: Check the status of this transaction and the refund time window setting.

      MERCHANT_BALANCE_NOT_ENOUGH

      Insufficient balance of the merchant to process this refund request. The previous transactions might have been settled to the merchant bank account.

      Action: Retry the refund after new transactions occur and the merchant's balance is sufficient.

      INVALID_ROUNDED_AMOUNT

      The refund with this amount might have violated the rule that the calculated amount of both CNY and foreign currency must be fully or not fully refunded at the same time.

      Take a transaction with 0.07 CNY (0.01 USD) as an example. A refund with 0.06 CNY is not to be accepted because 0.01 CNY (0 USD) is left for this transaction.

      Action: Contact Alipay technical support.

      REASON_TRADE_REFUND_FEE_ERR

      Invalid refund amount.

      Action: Check the request refund amount.

      REFUND_CHARGE_ERROR

      The refund is failed because the payment is in progress.

      Action: Try again later.

      BUYER_NOT_EXIST

      The buyer does not exist.

      Action: Contact Alipay technical support.

      #Handling result

      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. Retry (every 3 seconds, up to 5 times.) this request with correct parameters until you get a response from Alipay.
      2. 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=FAILED, and detail_error_code=SYSTEM_ERROR

      Take the following actions:

      1. Retry (every 3 seconds, up to 5 times.) this request with correct parameters until you get a response from Alipay.
      2. 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 refund request is accepted successfully, but it does not necessarily mean that the refund is executed 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=FAILED and detail_error_code!=SYSTEM_ERROR.

      The merchant failed to refund 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

      Asynchronous refund process:

      https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.overseas.spot.refund&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=USD&partner_trans_id=out_trade_no_20190904_160450&partner_refund_id=partner_refund_id_20190904_160211&refund_amount=0.01&refund_reason=%E4%B9%B0%E5%AE%B6%E4%B8%BB%E5%8A%A8%E8%A6%81%E6%B1%82%E9%80%80%E6%AC%BE&sign=b0d81ca4ecc6f14d149626233c727ef2


      Synchronous refund process:

      https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.overseas.spot.refund&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&notify_url=https%3A%2F%2Fwww.mikascoffee.com%2Fnotify&currency=USD&partner_trans_id=out_trade_no_20190904_160450&partner_refund_id=partner_refund_id_20190904_160211&refund_amount=0.01&refund_reason=%E4%B9%B0%E5%AE%B6%E4%B8%BB%E5%8A%A8%E8%A6%81%E6%B1%82%E9%80%80%E6%AC%BE&is_sync=Y&sign=45f7af56d72cae12f1c74868873c47b8


      #Response

      Synchronous sample

      Business is accepted and processed normally:

      copy
      <alipay>
          <is_success>T</is_success>
          <request>
              <param name="partner_trans_id">out_trade_no_20190904_160450</param>
              <param name="partner">208xxxxxxxxx8155</param>
              <param name="service">alipay.acquire.overseas.spot.refund</param>
              <param name="_input_charset">UTF-8</param>
              <param name="sign">b0d81ca4ecc6f14d149626233c727ef2</param>
              <param name="refund_amount">0.01</param>
              <param name="currency">USD</param>
              <param name="refund_reason">The buyer wants to initiate a refund.</param>
              <param name="notify_url">https://www.mikascoffee.com/notify</param>
              <param name="sign_type">MD5</param>
              <param name="partner_refund_id">partner_refund_id_20190904_160211</param>
          </request>
          <response>
          <alipay>
              <alipay_trans_id>201xxxxxxxxxxxxxxxxxxxxx3346</alipay_trans_id>
              <currency>USD</currency>
              <exchange_rate>7.18041000</exchange_rate>
              <partner_refund_id>partner_refund_id_20190904_160211</partner_refund_id>
              <partner_trans_id>out_trade_no_20190904_160450</partner_trans_id>
              <refund_amount>0.01</refund_amount>
              <refund_amount_cny>0.07</refund_amount_cny>
              <result_code>SUCCESS</result_code>
          </alipay>
          </response>
          <sign>fde68b2f3b82a599fd33eb84e250a220</sign>
          <sign_type>MD5</sign_type>
      </alipay>


      Request fails or the data accessed are wrong:

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


      Asynchronous sample

      copy
      https://www.mikascoffee.com/notify
      trans_refund_fee=0.01
      notify_type=refund_status_sync
      return_amount=0.01
      notify_time=2019-09-11 19:24:30
      out_trade_no=out_trade_no_20190904_163949
      refund_status=REFUND_SUCCESS
      sign=$$
      out_return_no=partner_refund_id_20190904_160211
      currency=USD
      sign_type=MD5
      notify_id=201xxxxxxxxxxxxxxxxxxxxxxxxxxx3785


      Note:

      For more information about asynchronous notification, synchronous notification, and digital signature, see API specification.