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>