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

      alipay.acquire.refund.query

      Call this interface to query the refund status.


      #Request

      #Request parameters

      ParameterDescription
      Basic parameter

      service

      String Required

      Interface name

      Example:alipay.acquire.refund.query

      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*********364

      _input_charset

      String Required


      The charset with which the request data are encoded. For example, GBK, GB2312, and UTF-8.

      Example:UTF-8

      sign_type

      String Required

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

      Example:MD5

      sign

      String Required

      The signature value

      Example:b7baf9af3c91b37bef4261849aa76281

      Business parameter

      out_trade_no

      String(64) Required

      The unique ID that is assigned by the merchant to identify a transaction

      Example:1234567890

      out_return_no

      String(128) Required

      The unique ID of the refund that is sent in the original refund request

      Example:0987654321


      #Response

      #Synchronous response

      ParameterDescription
      Basic parameter

      is_success

      String Required

      This parameter indicates whether the request succeeds, with a value of T for success and F for failure. A successful request does not mean the business is accepted and processed successfully.

      Example:T

      sign_type

      String Required

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

      Example:MD5

      sign

      String Required

      The signature value

      Example:59c7275cf3c82f038b7c0076f9888926

      error

      String

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

      Example:ILLEGAL_SIGN

      Business parameter

      response_code

      String(64) Required

      The result of the inquiry request. Possible values are:

      • SUCCESS: The request is successful.
      • ACCESS_FORBIDDEN: You are not permitted to use this service.
      • NOT_FOUND: No refund is found.
      • QUERY_FAILED: The inquiry is failed.
      • TRADE_NOT_EXIST: The transaction does not exist.

      Example:SUCCESS

      refund_result_code

      String(64)

      The refund status. Possible values are:

      • SUCCESS: The refund is successful.
      • FAILEDThe refund is failed.
      • CANCELED: The refund is canceled.
      • PROCESSING: The refund is being processed in Alipay system.

      Example:SUCCESS

      refund_error_code

      String(64)

      Error code returned for the refund. Only returned when the refund status is FAILED or PROCESSING. For more information, see the Business Code section in this document.

      Example:MERCHANT_BALANCE_NOT_ENOUGH

      out_return_no

      String(128)

      The unique ID of the refund that is sent in the original refund request

      Example:0123456789

      out_trade_no

      String(64)

      The unique ID that is assigned by the merchant to identify a transaction

      Example:123123123

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

      gmt_create

      Date

      The time when the refund request is accepted. Format: yyyy-MM-dd HH24:mm:ss. Use GMT+8.

      Example:2020-12-25 15:45:57

      gmt_finished

      Date

      The time when the refund succeeds. Format: yyyy-MM-dd HH24:mm:ss. Use GMT+8.

      Example:2020-12-25 15:45:58

      refund_rmb_amount

      Money

      The refund amount in CNY. The value is in the range of 0.01 - 1000000.00, with at most 2 digits after the decimal point.

      Example:12.56

      refund_foreign_amount

      Money

      The amount to refund in the settlement currency. The value is in the range of 0.01 – 1000000.00, with at most 2 digits after the decimal point. 

      Example:123.34

      currency

      String

      The settlement currency. The three-character ISO-4217 currency code. For more information, see Supported Currencies.

      Example:USD

      forex_rate

      String

      The exchange rate that is used for the refund, which is the same with the rate used for the original payment. Can have up to eight digits after the decimal point.

      Example:7.09610000

      refund_royaltys

      String(6000)

      Detailed list of the split refunds. Use JSON format. See refund_royaltys for details.

      Example:[{"amount":"0.20","transOut":"2088102149952810"}]


      #refund_royaltys

      ParameterDescription

      amount

      Money Required

      Amount of a split refund. Unit: CNY.

      The value is in the range of 0.01 – 1000000.00, with at most 2 digits after the decimal point.

      Example:0.34

      transOut

      String(32) Required

      The merchant's domestic account in Alipay system where the funds are transferred out.

      Example:2088002007018777


      #Error codes

      #Access errors

      Returned result

      Description

      ILLEGAL_SIGN

      Illegal signature

      ILLEGAL_DYN_MD5_KEY

      Dynamic key information is incorrect.

      ILLEGAL_ENCRYPT

      Encryption is incorrect.

      ILLEGAL_ARGUMENT

      Parameter is incorrect.

      ILLEGAL_SERVICE

      Service parameter is incorrect.

      ILLEGAL_USER

      User ID is incorrect.

      ILLEGAL_PARTNER

      Partner ID is incorrect.

      ILLEGAL_EXTERFACE

      Interface configuration is incorrect.

      ILLEGAL_PARTNER_EXTERFACE

      Partner's interface information is incorrect.

      ILLEGAL_SECURITY_PROFILE

      No matching private key configuration is found.

      ILLEGAL_AGENT

      Agency ID is incorrect.

      ILLEGAL_SIGN_TYPE

      The signature type is incorrect.

      ILLEGAL_CHARSET

      The character set is illegal.

      HAS_NO_PRIVILEGE

      No right to visit.

      INVALID_CHARACTER_SET

      The character set is invalid.


      #Business errors

      Error codes returned when the value of refund_result_code is PROCESSING:

      Returned result

      Description

      SYSTEM_ERROR

      Alipay system error. Please try again later.

      MERCHANT_BALANCE_NOT_ENOUGH

      Merchant balance is not enough for the refund.

      REFUND_CHARGE_ERROR

      Errors exist in the refund fee.

      REFUND_FAIL

      The refund fails.

      SERVICE_REFUSE

      The refund is not available during service downtime.

      SELLER_BALANCE_NOT_ENOUGH

      The balance of seller is not enough.

       

      Error codes returned when the value of refund_result_code is FAILED:

      Returned result

      Description

      SYSTEM_ERROR

      Alipay system error. Please try again later.

      MERCHANT_BALANCE_NOT_ENOUGH

      Merchant balance is not enough for the refund.

      TXN_RESULT_ACCOUNT_BALANCE_NOT_ENOUGH

      The last refund failed because the merchant balance is not enough.

      REFUND_CHARGE_ERROR

      Errors exist in the refund fee.

      TRADE_SETTLE_ERROR

      Settlement error

      REFUND_FAIL

      The refund fails.

      TRADE_STATUS_ERROR

      The trade status is illegal.

      TRADE_HAS_CLOSE

      The trade is closed and cannot be refunded.

      SERVICE_REFUSE

      The refund is not available during service downtime.

      SELLER_BALANCE_NOT_ENOUGH

      The balance of seller is not enough.

      CURRENCY_NOT_MATCH

      The refund currency and the settlement currency do not match.

      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.


      #Samples

      #Request

      https://mapi.alipay.com/gateway.do?out_trade_no=00220170124b4df6c6&partner=2088xxxxxxxx6931&service=alipay.acquire.refund.query&_input_charset=UTF-8&out_return_no=00220170124b4df6c6r&sign=51f9207497c4d2fc59c5912e7982d2d2&sign_type=MD5


      #Response

      The request fails:

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


      The request succeeds but no refund result is found:

      copy
      <?xml version="1.0" encoding="UTF-8"?>
      <alipay>
          <is_success>T</is_success>
          <request>
              <param name="out_trade_no">202005148394958330292_02</param>
              <param name="partner">2088xxxxxx6931</param>
              <param name="service">alipay.acquire.refund.query</param>
              <param name="_input_charset">UTF-8</param>
              <param name="sign">c97372146992e9099401c36223d88054</param>
              <param name="out_return_no">2020051484990500595995_1</param>
              <param name="sign_type">MD5</param>
          </request>
          <response>
              <alipay>
                  <response_code>NOT_FOUND</response_code>
              </alipay>
          </response>
          <sign>b77f097d603ef6c8ae041e159c16086d</sign>
          <sign_type>MD5</sign_type>
      </alipay>


      The refund fails:

      copy
      <?xml version="1.0" encoding="UTF-8"?>
      <alipay>
          <is_success>T</is_success>
          <request>
              <param name="out_trade_no">00220170124b4df6c6</param>
              <param name="partner">2088xxxxxxxx6931</param>
              <param name="service">alipay.acquire.refund.query</param>
              <param name="_input_charset">UTF-8</param>
              <param name="sign">a4c9ffdefbfd93dd7a3bd057755c05f9</param>
              <param name="out_return_no">00220170124b4df6c6r</param>
              <param name="sign_type">MD5</param>
          </request>
          <response>
              <alipay>
                  <gmt_create>2017-02-05 01:25:48</gmt_create>
                  <out_return_no>00220170124b4df6c6r</out_return_no>
                  <out_trade_no>00220170124b4df6c6</out_trade_no>
                  <refund_error_code>SYSTEM_ERROR</refund_error_code>
                  <refund_foreign_amount>0.01</refund_foreign_amount>
                  <refund_result_code>FAILED</refund_result_code>
                  <refund_rmb_amount>0.01</refund_rmb_amount>
                  <response_code>SUCCESS</response_code>
                  <trade_no>2017012421001003270252363402</trade_no>
              </alipay>
          </response>
          <sign>b46585009f4098a86b289fe48a88be84</sign>
          <sign_type>MD5</sign_type>
      </alipay>


      The refund succeeds:

      copy
      <?xml version="1.0" encoding="UTF-8"?>
      <alipay>
          <is_success>T</is_success>
          <request>
              <param name="out_trade_no">3941721012815833</param>
              <param name="partner">2088xxxxxxxx6931</param>
              <param name="service">alipay.acquire.refund.query</param>
              <param name="_input_charset">UTF-8</param>
              <param name="sign">df9f58640736d49f7993e7eb6eaae5f6</param>
              <param name="out_return_no">YNTK20150624002</param>
              <param name="sign_type">MD5</param>
          </request>
          <response>
              <alipay>
                  <currency>USD</currency>
                  <forex_rate>6.22945000</forex_rate>
                  <gmt_create>2015-06-24 21:43:56</gmt_create>
                  <gmt_finished>2015-06-24 21:43:57</gmt_finished>
                  <out_return_no>YNTK20150624002</out_return_no>
                  <out_trade_no>3941721012815833</out_trade_no>
                  <refund_foreign_amount>0.10</refund_foreign_amount>
                  <refund_result_code>SUCCESS</refund_result_code>
                  <refund_rmb_amount>0.62</refund_rmb_amount>
                  <response_code>SUCCESS</response_code>
                  <trade_no>2015062421001003430021738264</trade_no>
              </alipay>
          </response>
          <sign>d4ca93db8660180a61b828b3e0604d2c</sign>
          <sign_type>MD5</sign_type>
      </alipay>


      The refund succeeds (spilt refunds exist):

      copy
      <alipay>
          <is_success>T</is_success>
          <request>
              <param name="out_trade_no">202005148394958330292_02</param>
              <param name="partner">2088xxxxxxxx6931</param>
              <param name="service">alipay.acquire.refund.query</param>
              <param name="_input_charset">UTF-8</param>
              <param name="sign">4d3671ab713adb24c0ae81e5970c5474</param>
              <param name="out_return_no">2020051484990500595995</param>
              <param name="sign_type">MD5</param>
          </request>
          <response>
              <alipay>
                  <currency>USD</currency>
                  <forex_rate>7.14389000</forex_rate>
                  <gmt_create>2020-05-14 13:25:08</gmt_create>
                  <gmt_finished>2020-05-14 13:25:10</gmt_finished>
                  <out_return_no>2020051484990500595995</out_return_no>
                  <out_trade_no>202005148394958330292_02</out_trade_no>
                  <refund_foreign_amount>4.20</refund_foreign_amount>
                  <refund_result_code>SUCCESS</refund_result_code>
                  <refund_rmb_amount>30.00</refund_rmb_amount>
                  <refund_royaltys>[{"amount":"20.00","transOut":"2088801766902304"}]</refund_royaltys>
                  <response_code>SUCCESS</response_code>
                  <trade_no>2020051422001395451410092226</trade_no>
              </alipay>
          </response>
          <sign>b5b94e230ee244d031baeb225a749871</sign>
          <sign_type>MD5</sign_type>
      </alipay>