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 |
Test environment |
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
| Parameter | Description |
| Basic parameter | |
service String | Interface name
|
partner String(16) | 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.
|
_input_charset String | The charset with which the request data are encoded. UTF-8 is supported.
|
sign String | Sign value
|
sign_type String | Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.
|
| Business parameter | |
partner_trans_id String(64) | The original partner transaction ID given in the payment request
Note: Specify at least one of the fields: partner_trans_id and alipay_trans_id. When both of the fields are specified, alipay_trans_id will be verified first. |
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.
Note: Specify at least one of the fields: partner_trans_id and alipay_trans_id. When both of the fields are specified, alipay_trans_id will be verified first. |
Response
Response parameters
| Parameter | Description |
is_success String(1) | Indicates whether the request is accepted by the Alipay gateway. T: accepted F: rejected
|
sign_type String | Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.
|
sign String(32) | Sign value
|
result_code String(32) | Processing result of the request, with a value of SUCCESS to indicate the process is successful, or FAIL to indicate the process is failed.
|
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.
|
alipay_trans_status String(32) | Transaction status. See Trade status for details.
|
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.
|
alipay_buyer_user_id String(16) | The unique ID for each Alipay account, which starts with 2088.
|
partner_trans_id String(64) | Equal to the partner_trans_id given in the request
|
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.
|
alipay_pay_time String(16) | The time that the transaction was paid, which is in a format of YYYYMMDDHHMMSS.
|
currency String(8) | The settlement currency for the transaction
|
trans_amount Number(11,2) | 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.
|
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.
|
trans_amount_cny Number(9,2) | The transaction amount in CNY. It is the exact amount that the buyer has paid
|
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.
|
forex_total_fee Number(9,2) | The transaction amount in the settlement currency. Note: This parameter only applies to some Alipay businesses.
|
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.
|
Parameters rejected by Alipay gateway:
| Parameter | Description |
is_success String(1) | Indicates whether the request is accepted by the Alipay gateway. T: accepted F: rejected
|
sign_type String | Sign type. RSA, RSA2 and MD5 are supported. Use uppercase.
|
sign String(32) | Sign value
|
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.
|
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:
- 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.
- 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:
- Retry (every 3 seconds, up to 5 times.) this request with correct parameters until you get a response from Alipay.
- 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:
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:
<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.
<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.
<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.
<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>