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

      alipay.acquire.overseas.query

      Call this interface to query the transaction with partner_trans_id or alipay_trans_id.

      #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.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*********662

      _input_charset

      String

      The charset with which the request data are encoded. UTF-8 is supported.

      Example:UTF-8

      sign

      String Required

      Sign value

      Example:c8il4epm90wyn768fijgqhy8tay37gqa

      sign_type

      String Required

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

      Example:MD5

      Business parameter

      partner_trans_id

      String(64) Required

      The original partner transaction ID given in the payment request

      Example:2010121000000002

      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

      #Response

      #Response parameters

      ParameterDescription

      is_success

      String(1) Required

      Indicates whether the request is accepted by the Alipay gateway.

      T: accepted

      F: rejected

      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, with a value of SUCCESS to indicate the process is successful, or FAIL to indicate 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. For more information, see the Error Code section in this document.

      Example:TRANS_NOT_FOUND

      alipay_trans_status

      String(32)

      Transaction status. See Trade status for details.

      Example:WAIT_BUYER_PAY

      alipay_buyer_login_id

      String(20)

      Alipay login ID of the buyer, which can be an email address or mobile number. The ID is partially masked for privacy.

      Example:caoxxx@126.com or 186xxx22156

      alipay_buyer_user_id

      String(16) Required

      The unique ID for each Alipay account, which starts with 2088. 

      Example:2088102130896433

      partner_trans_id

      String(64) Required

      Equal to the partner_trans_id given in the request

      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

      alipay_pay_time

      String(16)

      The time that the transaction was paid, which is in a format of YYYYMMDDHHMMSS.

      Example:201311212323

      currency

      String(8) Required

      The settlement currency for the transaction

      Example:USD

      trans_amount

      Number(11,2) Required

      The transaction amount in the settlement currency. The value of this field is in the range of 0.01-100000000.00 and with two digits after the decimal point. However, if the settlement currency is JPY, the value is an integer.

      Example:39.25

      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

      trans_amount_cny

      Number(9,2)

      The transaction amount in CNY. It is the exact amount that the buyer has paid

      Example:239.19

      m_discount_forex_amount

      Number(9,2)

      If coupons/vouchers are used in the transaction, the discount amount redeemed in the settlement currency will be returned. Otherwise, no return. 

      Example:2.19

      forex_total_fee

      Number(9,2)

      The transaction amount in the settlement currency.

      Note: This parameter only applies to some Alipay businesses.

      Example:42.19

      trans_forex_rate

      Number(8,6)

      The exchange rate between the price currency and settlement currency.

      Note: This parameter only applies to some Alipay businesses.

      Example:6.0939

      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

      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.

      Example:TRANS_NOT_FOUND

      detail_error_des

      String(48)

      Explanation of the detailed error code. If result_code is SUCCESS, this parameter is not returned.

      #Error codes

      Error code

      Description

      SYSTEM_ERROR

      Alipay system failed to process the request due to temporary internal glitch.

      Action: Retry this request with the exact parameters. Refer to Case 2 in the following section for details.

      ILLEGAL_SIGN

      Illegal signature.

      Action: Please read Digital Signature for details

      INVALID_PARAMETER

      Parameter value error.

      Action: Please check the standard of each request parameter according to the API speficaition

      ILLEGAL_ARGUMENT

      Parameter name error.

      Action: Please check each request parameter according to the API specification, contact Alipay technical support if this error persists

      ILLEGAL_PARTNER

      Incorrect partner ID.

      Action: Please make sure 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: Please make sure service parameters has the same value with the one in API specification, contact Alipay technical support if this error persists

      ILLEGAL_PARTNER_EXTERFACE

      Partner ID do not have access privilege.

      Action: contact Alipay technical support

      ILLEGAL_SIGN_TYPE

      Illegal sign type.

      Action: Please make sure the value of sign_type is amongst MD5,DSA and RSA, contact Alipay technical support if this error persists

      HAS_NO_PRIVILEGE

      Has no privilege.

      Action: Please contact Alipay technical support

      REASON_TRADE_BEEN_FREEZEN

      Corresponding trade is been frozen due to security issues.

      Action: Please contact Alipay technical support

      TRADE_NOT_EXIST

      Cannot find corresponding trade according to inputted partner_trans_id.

      Action: 1. Make sure the partner_trans_id is correct. 2. If the issue persists, please contact Alipay technical support

      #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. 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=FAIL, 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 queried the transaction 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 query the transaction. 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 10 times.
      
          if(retrySuccess){
            doSuccessProcess();
          }
          else{
            //request Alipay tech support.
          }
        }
      
      }catch (Exception ex){ // CASE 1
         
          retrySuccess = retryWithSameParameters(); //Retry every 3 seconds, up to 10 times.
      
          if(retrySuccess){
            doSuccessProcess();
          }
          else{
            //request Alipay tech support.
          }
        }
      }

      #Samples

      #Request

      Request sample with the parter_trans_id field specified

      https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.overseas.query&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&partner_trans_id=out_trade_no_20190904_151744&sign=23473d26d38f2a9b877315a00542f833


      Request sample with the alipay_trans_id field specified

      https://intlmapi.alipay.com/gateway.do?service=alipay.acquire.overseas.query&partner=208xxxxxxxxx8155&_input_charset=UTF-8&sign_type=MD5&alipay_trans_id=2019090422001436530558497325&sign=2bd963c953916b78c2c141f8faea4124


      #Response 

      Request succeeds, and the business processing succeeds:

      copy
      <alipay>
          <is_success>T</is_success>
          <request>
              <param name="partner_trans_id">out_trade_no_20190904_151744</param>
              <param name="partner">208xxxxxxxxx8155</param>
              <param name="_input_charset">UTF-8</param>
              <param name="service">alipay.acquire.overseas.query</param>
              <param name="sign">23473d26d38f2a9b877315a00542f833</param>
              <param name="sign_type">MD5</param>
          </request>
          <response>
              <alipay>
                  <alipay_buyer_login_id>186****9365</alipay_buyer_login_id>
                  <alipay_buyer_user_id>208xxxxxxxxx6535</alipay_buyer_user_id>
                  <alipay_pay_time>201xxxxxxx1805</alipay_pay_time>
                  <alipay_trans_id>201xxxxxxxxxxxxxxxxxxxxxxx7325</alipay_trans_id>
                  <alipay_trans_status>TRADE_CLOSED</alipay_trans_status>
                  <currency>USD</currency>
                  <exchange_rate>7.18041000</exchange_rate>
                  <forex_total_fee>0.01</forex_total_fee>
                  <out_trade_no>out_trade_no_20190904_151744</out_trade_no>
                  <partner_trans_id>out_trade_no_20190904_151744</partner_trans_id>
                  <result_code>SUCCESS</result_code>
                  <trans_amount>0.01</trans_amount>
                  <trans_amount_cny>0.07</trans_amount_cny>
                  <trans_forex_rate>1</trans_forex_rate>
              </alipay>
          </response>
          <sign>787e2affe713f470f7db016cede91c04</sign>
          <sign_type>MD5</sign_type>
      </alipay>


      Request fails:

      PID does not have permission to call this interface.

      copy
      <alipay>
      <is_success>F</is_success>
      <error>ILLEGAL_PARTNER_EXTERFACE</error>
      </alipay>


      PID has the right to call this interface, but the signature is wrong.

      copy
      <alipay>
      <is_success>F</is_success>
      <error>ILLEGAL_SIGN</error>
      </alipay>


      PID has the right to call this interface, and the signature is correct, but no transaction can be found.

      copy
      <alipay>
      <is_success>T</is_success>
      <request>
      <param name="partner_trans_id">TRADE_20210611164347</param>
      <param name="partner">2088************</param>
      <param name="_input_charset">UTF-8</param>
      <param name="service">alipay.acquire.overseas.query</param>
      <param name="sign">*</param>
      <param name="sign_type">MD5</param>
      </request>
      <response>
      <alipay>
      <detail_error_code>TRADE_NOT_EXIST</detail_error_code>
      <detail_error_des>交易不存在</detail_error_des>
      <out_trade_no>TRADE_20210611164347</out_trade_no>
      <partner_trans_id>TRADE_20210611164347</partner_trans_id>
      <result_code>FAIL</result_code>
      </alipay>
      </response>
      <sign>*</sign>
      <sign_type>MD5</sign_type>
      </alipay>