This guide provides an overview of the Third-party Merchant QR Code payment and it’s overall workflow, and then introduces the detailed integration steps.
This guide is intended for developers and testers of Alipay partners who want to integrate Alipay Third-party Merchant QR Code payment solution.
This interface provides the ability to refund a transaction both in whole and in partial. By design, the refund request cannot be reversed, use retry instead.
Environment | HTTPS request URL |
---|---|
Production environment | https://intlmapi.alipay.com/gateway.do |
Test environment | https://mapi.alipaydev.com/gateway.do |
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
Parameter |
Type(Byte) |
Description |
Nullable |
Example |
|
Basic parameter |
|||||
service |
String |
Description |
No |
alipay.acquire.overseas.spot.refund |
|
sign |
String |
Signature value. See “Digital Signature”. |
No |
c8il4epm90wyn768fijgqhy8tay37gqa |
|
sign_type |
String |
The type could be DSA, RSA or MD5;
Capital letters only. |
No |
MD5 |
|
partner |
String |
One Alipay account has only one Alipay ID. Composed of 16-digit number beginning with 2088 |
No |
2088102012343978 |
|
_input_charset |
String |
Character set of parameter code. Default is GBK if not send. |
Yes |
UTF-8 |
|
notify_url |
String |
The url to which Alipay sends payment result in async mode. It is in POST method. Note: For information security, the url must be on https protocol. This URL cannot have extra parameters. For example, “https://xxx.com/foo.php?star=obama” is not allowed. |
Yes |
https://www.test.com/alipay/notify_url.php |
|
Operation parameter |
|||||
partner_trans_id |
String(64) |
The original partner transaction id given in the payment request |
No |
2010121000000002 |
|
alipay_trans_id |
String(64) |
The Alipay transaction ID. |
Yes |
201311221703338463 |
|
partner_refund_id |
String(64) |
The refund order id on partner system. partner_refund_id cannot be same as partner_transaction_id partner_refund_id together with partner identify a refund transaction |
No |
301012133000002 |
|
refund_amount |
Number(9,2) |
Less than or equal to the original transaction amount and the left transaction amount if ever refunded.
|
No |
39.25 |
|
currency |
String(10) |
The refund currency. Use upper case. See Supported Currency List for details. |
No |
USD |
|
refund_reason |
String(128) |
The reason of refund |
Yes |
Refund the good |
|
is_sync |
String(1) |
The refund request is processed synchronously or asynchronously. Value: Y or N. Default value is N, which means an asynchronous response 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. |
Yes |
Y |
https://intlmapi.alipay.com/gateway.do?partner_trans_id=9699196959845722&partner_refund_id=301012133000002&refund_amount=786.09¤cy=USD&sign=30ff71107f6824dc3d28af7619870e26&sign_type=MD5&_input_charset=UTF-8&service=alipay.acquire.overseas.spot.refund&partner=2088102012343978
Parameters accepted by Alipay gateway:
Parameter |
Type (Byte) |
Description |
Nullable |
Example |
is_success |
String(1) |
It indicates that a request is accepted by Alipay gateway. l T for accepted |
No |
T |
sign_type |
String |
The type could be DSA, RSA or MD5;
Capital letters only. |
No |
MD5 |
sign |
String(32) |
See “4 Digital Signature”. |
No |
59c7275cf3c82f038b7c0076f9888926 |
result_code |
String(32) |
To describe the response status of a request: SUCCESS, FAILED, UNKNOW. |
No |
SUCCESS |
error |
String(48) |
To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success. |
Yes |
TRANS_NOT_FOUND |
partner_trans_id |
String(64) |
Equal to the partner_trans_id given in the request |
No |
201311221000000002 |
alipay_trans_id |
String(64) |
On the partner’s payment request, the alipay system creates a transaction id to handle it. The alipay_trans_id has one-one association with partner + partner_trans_id. |
Yes |
201311221703338463 |
partner_refund_id |
String(64) |
The refund order id on partner system.
partner_refund_id together with partner identify a refund transaction |
No |
301012133000002 |
refund_amount |
Number(9,2) |
Less than or equal to the original transaction amount and the left transaction amount if ever refunded.
|
No |
39.25 |
currency |
String(10) |
Refund currency |
No |
USD |
exchange_rate |
Number |
The rate of conversion the currency given in the request to CNY. The conversion happens at the time when Alipay’s trade order is created. |
Yes |
6.0939 |
refund _amount_cny |
Number(9,2) |
Refund amount in CNY. It is the exact amount that the Alipay has refunded. |
Yes |
239.19 |
Parameters rejected by Alipay gateway:
Parameter |
Type (length range) |
Description |
Nullable |
Example |
is_success |
String(1) |
It indicates that a request is rejected by Alipay gateway. l F for rejected |
No |
F |
sign_type |
String |
The type could be DSA, RSA or MD5;
Capital letters only. |
No |
MD5 |
sign |
String(32) |
See “4 Digital Signature”. |
No |
59c7275cf3c82f038b7c0076f9888926 |
error |
String(48) |
To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success. |
Yes |
TRANS_NOT_FOUND |
Normal input:
<?xmlversion="1.0"encoding="UTF-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="_input_charset">UTF-8</param>
<param name="partner_trans_id">2010121000000002</param>
<param name="partner">2088102012343978</param>
<param name="service">alipay.acquire.overseas.pay</param>
<param name="partner_refund_id">301012133000002</param>
<param name="refund_amount">39.25</param>
<param name="currency">USD</param>
<param name="refund_reson">back</param>
<param name="sign">22904adafb1806178b410d2d5c9c02a3</param>
<param name="sign_type">MD5</param>
</request>
<response>
<alipay>
<partner_trans_id>2010121000000002</partner_trans_id>
<alipay_trans_id>201311221703338463</alipay_trans_id>
<partner_refund_id>301012133000002</partner_refund_id>
<refund_amount>39.25</refund_amount>
<currency>USD</currency>
<exchange_rate>6.0939</exchange_rate>
<refund_amount_CNY>239.19</refund _amount_CNY>
<result_code>SUCCESS</result_code>
</alipay>
</response>
<sign>6fb8a322f15cfd0fcfe65301b10f6994</sign>
<sign_type>MD5</sign_type>
</alipay>
Error output:
<?xml version="1.0" encoding="UTF-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>
Error Code |
Description |
Action |
SYSTEM_ERROR |
Alipay system is currently not available. |
Retry this request with the exact parameters. Refer Case 2 at here for detailed instruction. |
ILLEGAL_SIGN |
Illegal signature. |
Please read chapter Digital Signature |
INVALID_PARAMETER |
Parameter error. |
Please check the standard of each request parameter according to the API specification |
ILLEGAL_ARGUMENT |
Parameter error. |
Please check each request parameter according to the API specification, contact Alipay technical support if this error persists |
ILLEGAL_PARTNER |
Incorrect partner ID. |
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. |
Please make sure 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 |
Partner ID do not have access privilege. |
Make sure your agreement with Alipay has been finalized. Contact Alipay technical support if needed. |
ILLEGAL_SIGN_TYPE |
Illegal sign type. |
Please make sure the value of sign_type is among MD5,DSA and RSA, contact Alipay technical support if this error persists |
HAS_NO_PRIVILEGE |
Has no privilege. |
Please contact Alipay technical support |
REASON_TRADE_BEEN_FREEZEN |
Corresponding trade has been frozen due to security issues. |
Please contact Alipay technical support |
TRADE_NOT_EXIST |
Cannot find corresponding trade according to input “partner_trans_id”. |
1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay Technical Support |
TRADE_STATUS_ERROR |
Corresponding trade status is not allowed for current operate. |
1) Make sure the trade status is correct 2)if the issue persists, please contact Alipay technical support |
REFUND_AMT_RESTRICTION |
The input “refund_amount” is more than original trade amount, or total refund amount is more than original trade amount, cannot be processed by Alipay. |
Merchant need to check if the return amount is correct |
REQUEST_AMOUNT_EXCEED |
The same with “REFUND_AMT_RESTRICTION”. |
Merchant need to check if the return amount is correct |
TRADE_HAS_CLOSE |
The transaction is closed and refunds are not allowed anymore. |
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 may have been settled to the merchant bank account. |
Retry the refund after new transactions occur and the merchant's balance is sufficient. |
INVALID_ROUNDED_AMOUNT |
The refund with this amount may have violated the rule that the calculated amount of both CNY and foreign currency should be fully or not fully refunded at the same time. |
Please contact Alipay technical support. |
REASON_TRADE_REFUND_FEE_ERR |
Invalid refund amount. |
Check the request refund amount. |
REFUND_CHARGE_ERROR |
The refund failed because the payment is in progress. |
Please try again later. |
Case 1. When the invocation failed with network issue or request timeouted, so got no response from Alipay
Case 2. Received response from Alipay, but (1) is_success=F and error=SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code=SYSTEM_ERROR, or (3) is_success=T and result_code=UNKNOWN.
Case 3. Received response from Alipay, and is_success=T and result_code=SUCCESS. Mark merchant refund order as processed successfully
Case 4. Received response from Alipay, and (1) is_success=F and error=!SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code!=SYSTEM_ERROR. Mark merchant refund order as failed. Refer specific error code for instrunction
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.
}
}
}
This interface provides the ability to query a transaction with partner_trans_id or alipay_trans_id.
Environment | HTTPS request URL |
---|---|
Production environment | https://intlmapi.alipay.com/gateway.do |
Test environment | https://mapi.alipaydev.com/gateway.do |
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
Parameter |
Type (Byte) |
Description |
Nullable |
Example |
|
Basic parameter |
|||||
service |
String |
Interface name. |
No |
alipay.acquire.overseas.query |
|
sign |
String |
Signature value. See “Digital Signature”. |
No |
c8il4epm90wyn768fijgqhy8tay37gqa |
|
sign_type |
String |
The type could be DSA, RSA or MD5;
Capital letters only. |
No |
MD5 |
|
partner |
String |
One Alipay account has only one Alipay ID. Composed of 16-digit number beginning with 2088 |
No |
2088102012343978 |
|
_input_charset |
String |
Character set of parameter code. Default is GBK if not send. |
Yes |
UTF-8 |
|
Operation parameter |
|||||
partner_trans_id |
String(64) |
The original partner transaction id given in the payment request |
No |
2010121000000002 |
|
alipay_trans_id |
String(64) |
On the partner’s payment request, the alipay system creates a transaction id to handle it. The alipay_trans_id has one-one association with partner + partner_trans_id. |
YES |
201311221703338463 |
https://intlmapi.alipay.com/gateway.do?partner_trans_id=9699196959845722&sign_type=MD5&_input_charset=UTF-8&service=alipay.acquire.overseas.query&partner=2088102012343978
Parameter |
Type (Byte) |
Description |
Nullable |
Example |
is_success |
String(1) |
It indicates that a request is accepted by Alipay gateway. l T for accepted |
No |
T |
sign_type |
String |
The type could be DSA, RSA or MD5;
Capital letters only. |
No |
MD5 |
sign |
String(32) |
See “4 Digital Signature”. |
No |
59c7275cf3c82f038b7c0076f9888926 |
result_code |
String(32) |
To describe the response status of a request: SUCCESS, FAIL |
No |
SUCCESS |
error |
String(48) |
To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success. |
Yes |
TRANS_NOT_FOUND |
alipay_trans _status |
String(32) |
WAIT_BUYER_PAY, TRADE_SUCCESS, TRADE_CLOSED |
Yes |
TRADE_SUCCESS |
alipay_buyer_login_id |
String(20) |
The buyer’s Alipay login Id, the id might be an email or mobile number. The id is partially masked for privacy. |
YES |
cao***@126.com or 186***22156 |
alipay_buyer_user_id |
String(16) |
This ID stands for each Alipay account number ,unique in Alipay system start with “2088” |
No |
2088102130896433 |
partner_trans_id |
String(64) |
Equal to the partner_trans_id given in the request |
No |
201311221000000002 |
alipay_trans_id |
String(64) |
On the partner’s payment request, the alipay system creates a transaction id to handle it. The alipay_trans_id has one-one association with partner + partner_trans_id. |
YES |
201311221703338463 |
alipay_pay_time |
String(16) |
The time of the transaction has been paid. Format:YYYYMMDDHHMMSS |
YES |
201311212323 |
currency |
String(8) |
The currency used for labeling the price of the transaction; |
No |
USD |
trans_amount |
Number(9,2) |
the transaction amount in the currency given above;
Range: 0.01-100000000.00. Two digits after decimal point. |
No |
39.25 |
exchange_rate |
Number(8,6) |
The rate of conversion the currency given in the request to CNY. The conversion happens at the time when Alipay’s trade order is created. |
YES |
6.0939 |
trans _amount_cny |
Number(9,2) |
Transaction amount in CNY. It is the exact amount that the buyer has paid |
YES |
239.19 |
m_discount_forex_amount |
Number(9,2) |
If coupons/vouchers are used in the transaction, the discount amount redeened in the settlement currency will be returned. Otherwise, no return. |
Yes |
2.19 |
forex_total_fee |
Number(9,2) |
Transaction amount in the settlement currency. Note: This parameter only applies to some Alipay businesses. |
YES |
42.19 |
trans_forex_rate |
Number(8,6) |
Exchange rate between the price currency and settlement currency. Note: This parameter only applies to some Alipay businesses. |
YES |
6.0939 |
Parameters rejected by Alipay gateway:
Parameter |
Type (Byte) |
Description |
Nullable |
Example |
is_success |
String(1) |
It indicates that a request is rejected by Alipay gateway. l F for rejected |
No |
F |
sign_type |
String |
The type could be DSA, RSA or MD5;
Capital letters only. |
No |
MD5 |
sign |
String(32) |
See “4 Digital Signature”. |
No |
59c7275cf3c82f038b7c0076f9888926 |
detail_error_code |
String(48) |
To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success. |
Yes |
TRANS_NOT_FOUND |
detail_error_des |
String(48) |
To describe the reason of the result_code when it is failed/unknown, leave it blank when result_code is success. |
Yes |
Please also note that details_error_code and details_error_description parameter value are subject to be newly introduced further; please consider when coding to handle forward compatibility for this further error code introduction.
Normal input:
<?xmlversion="1.0"encoding="UTF-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="_input_charset">UTF-8</param>
<param name="partner_trans_id">2010121000000002</param>
<param name="partner">2088102012343978</param>
<param name="service">alipay.acquire.overseas.query</param>
<param name="sign">22904adafb1806178b410d2d5c9c02a3</param>
<param name="sign">c7d17d40111b8264975a6bfba77962cb</param>
</request>
<response>
<alipay>
<alipay_trans_id>2011091703338463</alipay_trans_id>
<partner_trans_id>201311221000000002</partner_trans_id>
<alipay_buyer_login_id>cao***@126.com</alipay_buyer_login_id>
<alipay_pay_time>20131120155823</alipay_pay_time>
<exchange_rate>6.0939</exchange_rate>
<trans_amount>39.25</trans_amount>
<trans_amount_CNY>239.19</trans_amount_CNY>
<result_code>SUCCESS</result_code>
<alipay_trans _status>TRADE_SUCCESS</alipay_trans _status>
</alipay>
</response>
<sign>6fb8a322f15cfd0fcfe65301b10f6994</sign>
<sign_type>MD5</sign_type>
</alipay>
Error output:
<?xml version="1.0" encoding="UTF-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
<sign>02f6b289c46b8d0c1ea62b4f78637c1a</sign>
<sign_type>MD5</sign_type>
</alipay>
Error Code |
Description |
Action |
SYSTEM_ERROR |
Alipay system failed to process the request due to temporary internal glitch. |
Retry this request with the exact parameters. Refer Case 2 at here for detailed instruction. |
ILLEGAL_SIGN |
Illegal signature. |
Please read chapter Digital Signature |
INVALID_PARAMETER |
Parameter value error. |
Please check the standard of each request parameter according to the API speficaition |
ILLEGAL_ARGUMENT |
Parameter name error. |
Please check each request parameter according to the API specification, contact Alipay technical support if this error persists |
ILLEGAL_PARTNER |
Incorrect partner ID. |
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. |
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. |
contact Alipay technical support |
ILLEGAL_SIGN_TYPE |
Illegal sign type. |
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. |
Please contact Alipay technical support |
REASON_TRADE_BEEN_FREEZEN |
Corresponding trade is been frozen due to security issues. |
Please contact Alipay technical support |
TRADE_NOT_EXIST |
Cannot find corresponding trade according to inputted “partner_trans_id”. 1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay technical support |
1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay technical support |
Case 1. When the invocation failed with network issue or request timeouted, so got no response from Alipay
Case 2. Received response from Alipay, but (1) is_success=F and error=SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code=SYSTEM_ERROR
Case 3. Received response from Alipay, and is_success=T and result_code=SUCCESS. Query succeeded.
Case 4. Received response from Alipay, and (1) is_success=F and error=!SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code!=SYSTEM_ERROR. Query failed. Refer specific error code for instrunction
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.
}
}
}
In the list of request and response parameters, all of them need to be signed except sign and sign_type. (sign_type also needs to be signed in some cases in the list of request parameters)
Use the following code to package the data:
//package the request parameters
Map sParaTemp = new HashMap();
sParaTemp.put("service", AlipayConfig.service);
sParaTemp.put("partner", AlipayConfig.partner);
sParaTemp.put("_input_charset", AlipayConfig.input_charset);
sParaTemp.put("notify_url", AlipayConfig.notify_url);
sParaTemp.put("return_url", AlipayConfig.return_url);
sParaTemp.put("out_trade_no", out_trade_no);
sParaTemp.put("subject", subject);
sParaTemp.put("total_fee", total_fee);
sParaTemp.put("body", body);
sParaTemp.put("currency", currency);
sParaTemp.put("product_code", product_code);
split_fund_info = split_fund_info.replaceAll("\"", "'");
sParaTemp.put("split_fund_info", split_fund_info);
sParaTemp.put("secondary_merchant_id",secondary_merchant_id);
sParaTemp.put("secondary_merchant_name",secondary_merchant_name);
sParaTemp.put("secondary_merchant_industry",secondary_merchant_industry);
Rearrange parameters in the data set alphabetically_input_charset=utf-8&app_pay=Y&body=test¤cy=USD¬ify_url=http://d4779318.ngrok.io/new_create_forex_trade_wap_JAVA-UTF-8-RSA/notify_url.jsp&out_trade_no=test20170901162***&partner=2088101122136***&product_code=NEW_WAP_OVERSEAS_SELLER&return_url=http://d4779318.ngrok.io/new_create_forex_trade_wap_JAVA-UTF-8-RSA/return_url.jsp&service=create_forex_trade_wap&subject=test123&total_fee=0.01
This is the pre-sign string.Private Key is necessary for MD5 signature. The MD5 private key is the 32-byte string which is composed of English letters and numbers. Partner can log on the Merchant Service Center (https://global.alipay.com) to check the private key.
After the partner receives the pre-sign string during requesting, the private key should be appended to the pre-sign string to generate the new string. Then this new string would be calculated with the MD5 signature algorithm by the MD5 signature function. Thus, the result 32-byte string is the signature result string. (the value is given to parameter “sign”)
After receiving the pre-sign string during responding from Alipay system, the next step is the same as the procedure of Sign for request. When the 32-byte signature result string is generated, it should be verified whether the value is equal to the value of the parameter “sign”. If equal, the verification would be passed.
Both private key and public key are necessary for RSA signature. Both private key and public key are generated with OPENSSL by partner. Partner and Alipay need to exchange their own public key. Therefore, partner uses Alipay public key and partner private key.
After the partner receives the pre-sign string during requesting, the partner private key and the pre-sign string are used in the RSA signature algorithm by the RSA signature function to get the result string. (the value is given to parameter “sign”)
After receiving the pre-sign string during responding from Alipay system, the Alipay public key, the pre-sign string and the parameter “sign” are used in the RSA signature asymmetric algorithm by the RSA signature function to accomplish the signature verification.
sudo apt-get install openssl
The developer can download Windows version of OpenSSL from the official site of https://www.openssl.org/source/.
$ openssl
OpenSSL> genrsa -out rsa_private_key.pem 1024 ##generating private key
OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt ##transform private key into PKCS8 format
OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem ##Generate public key
OpenSSL> exit
C:\Users\Hammer>cd C:\OpenSSL-Win32\bin ##enter OpenSSL directory
C:\OpenSSL-Win32\bin>openssl.exe ##enter OpenSSL
OpenSSL> genrsa -out rsa_private_key.pem 1024 ##generating private key
OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt ##transform private key into PKCS8 format
OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem ##Generate public key
OpenSSL> exit
After the above steps, the user could see two files under the current folder (C:\OpenSSL-Win32\bin for Windows), rsaprivatekey.pem and rsapublickey.pem.
The former is the private key while the latter is the public key. The merchant should keep the private key and exchange the public key with Alipay for signature verification. The following are the examples on how to use the key pair.
-----BEGIN RSA PRIVATE KEY-----MIICXQIBAAKBgQC+L0rfjLl3neHleNMOsYTW8r0QXZ5RVb2p/vvY3fJNNugvJ7lo4+fdBz+LN4mDxTz4MTOhi5e2yeAqx+v3nKpNmPzC5LmDjhHZURhwbqFtIpZD51mOfno2c3MDwlrsVi6mTypbNu4uaQzw/TOpwufSLWF7k6p2pLoVmmqJzQiD0QIDAQABAoGAakB1risquv9D4zX7hCv9MTFwGyKSfpJOYhkIjwKAik7wrNeeqFEbisqv35FpjGq3Q1oJpGkem4pxaLVEyZOHONefZ9MGVChT/MNH5b0FJYWl392RZy8KCdq376Vt4gKVlABvaV1DkapL+nLh7LMo/bENudARsxD55IGObMU19lkCQQDwHmzWPMHfc3kdY6AqiLrOss+MVIAhQqZOHhDe0aW2gZtwiWeYK1wB/fRxJ5esk1sScOWgzvCN/oGJLhU3kipHAkEAysNoSdG2oWADxlIt4W9kUiiiqNgimHGMHPwp4JMxupHMTm7D9XtGUIiDijZxunHv3kvktNfWj3Yji0661zHVJwJBAM8TDf077F4NsVc9AXVs8N0sq3xzqwQD/HPFzfq6hdR8tVY5yRMb4X7+SX4EDPORKKsgnYcur5lk8MUi7r072iUCQQC8xQvUne+fcdpRyrR4StJlQvucogwjTKMbYRBDygXkIlTJOIorgudFlrKP/HwJDoY4uQNl8gQJb/1LdrKwIe7FAkBl0TNtfodGrDXBHwBgtN/t3pyi+sz7OpJdUklKE7zMSBuLd1E3O4JMzvWP9wEE7JDb+brjgK4/cxxUHUTkk592-----END RSA PRIVATE KEY-----
-----BEGIN PRIVATE KEY-----MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAN0yqPkLXlnhM+2H/57aHsYHaHXazr9pFQun907TMvmbR04wHChVsKVgGUF1hC0FN9hfeYT5v2SXg1WJSg2tSgk7F29SpsF0I36oSLCIszxdu7ClO7c22mxEVuCjmYpJdqb6XweAZzv4Is661jXP4PdrCTHRdVTU5zR9xUByiLSVAgMBAAECgYEAhznORRonHylm9oKaygEsqQGkYdBXbnsOS6busLi6xA+iovEUdbAVIrTCG9t854z2HAgaISoRUKyztJoOtJfI1wJaQU+XL+U3JIh4jmNx/k5UzJijfvfpT7Cv3ueMtqyAGBJrkLvXjiS7O5ylaCGuB0Qz711bWGkRrVoosPM3N6ECQQD8hVQUgnHEVHZYtvFqfcoq2g/onPbSqyjdrRu35a7PvgDAZx69Mr/XggGNTgT3jJn7+2XmiGkHM1fd1Ob/3uAdAkEA4D7aE3ZgXG/PQqlm3VbE/+4MvNl8xhjqOkByBOY2ZFfWKhlRziLEPSSAh16xEJ79WgY9iti+guLRAMravGrs2QJBAOmKWYeaWKNNxiIoF7/4VDgrcpkcSf3uRB44UjFSn8kLnWBUPo6WV+x1FQBdjqRviZ4NFGIP+KqrJnFHzNgJhVUCQFzCAukMDV4PLfeQJSmna8PFz2UKva8fvTutTryyEYu+PauaX5laDjyQbc4RIEMU0Q29CRX3BA8WDYg7YPGRdTkCQQCG+pjU2FB17ZLuKRlKEdtXNV6zQFTmFc1TKhlsDTtCkWs/xwkoCfZKstuV3Uc5J4BNJDkQOGm38pDRPcUDUh2/-----END PRIVATE KEY-----
-----BEGIN PUBLIC KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQWiDVZ7XYxa4CQsZoB3n7bfxLDkeGKjyQPt2FUtm4TWX9OYrd523iw6UUqnQ+Evfw88JgRnhyXadp+vnPKP7unormYQAfsM/CxzrfMoVdtwSiGtIJB4pfyRXjA+KL8nIa2hdQy5nLfgPVGZN4WidfUY/QpkddCVXnZ4bAUaQjXQIDAQAB-----END PUBLIC KEY-----
Contact Global Merchant Technical Support to upload the public key. Please sign with the matching private key in the key pair.
During the payment process of a transaction, it is possible to encounter issues such as system exception or network accessibility. In such a scenario, you need to reverse the transaction. To implement this reversing, we would like to highlight the notes of below:
Request parameter is the request data provided to Alipay by merchant when conducting data interaction with Alipay so that further process can be conducted by Alipay based on these data.
Environment | HTTPS request URL |
---|---|
Production environment | https://intlmapi.alipay.com/gateway.do |
Test environment | https://mapi.alipaydev.com/gateway.do |
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
Parameter |
Type (Byte) |
Parameter Description |
Nullable |
Example |
|
service |
String |
Interface name |
N |
alipay.acquire.precreate |
|
partner |
String(1 6) |
Unique Alipay user number corresponding to authorized Alipay account number. Composed of 16 numbers beginning with 2088. |
N |
2088101568358171 |
|
_input_charset |
String |
Encoding format used in merchant’s website, such as utf-8, gbk, gb2312, etc |
N |
utf-8 |
|
sign_type |
String |
Three values, namely, DSA, RSA and MD5 can be chose; and must be capitalized |
N |
MD5 |
|
sign |
String |
See Digital Algorithm for details. |
N |
85bf83f78d5cefb804bd 805532fc688e |
|
notify_url |
String(190) |
Alipay server takes the initiative to notify merchant of webpage http path designated by website. |
Y |
http://api.test.alipay.net/atinterface/receive_notify.htm |
|
timestamp |
String |
Time stamp of the merchant server sending request, accurate to the millisecond. |
N |
1456507704121 |
|
terminal_timestamp |
String |
Time stamp of the terminal sending request, accurate to the millisecond. |
Y |
1456507704102 |
|
out_trade_no |
String(64) |
Unique order ID in Alipay’s merchant website |
N |
99003911198989 |
|
subject |
String(256) |
Goods title/trade tile/order subject/order key word etc. The length of this parameter is up to 128 Chinese characters. |
N |
Payment by QR-Code |
|
product_code |
String(32) |
Order placement used to distinguish the business type: |
N |
OVERSEAS_MBARCODE_PAY |
|
total_fee |
number (9,2) |
Total fee of this order. The range of values is [0.01, 100000000], such value can have up to two digits after the decimal point. |
N |
10 |
|
seller_id |
String(28) |
Unique Alipay user ID corresponding to Seller’s Alipay account 16 numbers beginning with 2088. If both sell_id and seller-email are null, the default value of this parameter to be filled out shall be the value of merchant. |
Y |
2088101106499364 |
|
seller_email |
String(100) |
Seller’s Alipay account, may be email or phone number If seller_id is not null, the value of seller_id shall be the seller’s ID and this parameter can be neglected. |
Y |
test@alitest.com |
|
body |
String(400) |
Specific description of the trade. In case of a variety of goods, please accumulate the character strings descrbing the goods, and transmit the same to body. |
Y |
iphone cellphone |
|
show_url |
String(400) |
Hyperlink for the show of goods on the webpage of checkout counter. |
Y |
http://www.taobao.com/product/113714.html |
|
currency |
String(8) |
Settlement currency. Currency and trans_currency cannot be different foreign currency. Use upper case. See Supported Currency List for details. |
N |
CNY |
|
trans_currency |
String(8) |
Pricing currency for the transaction, if it is not CNY, the CNY amount user will be charged will be calculated based on trans_currency and exchange rate. Use upper case. See Supported Currency List for details. |
N |
CNY |
|
price |
Number (9,2) |
Unit price of the goods in the order. If this parameter is transmitted at request, the condition of total_fee=price×quantity must be met. |
Y |
1 |
|
quantity |
String(100) |
Quantity of the goods in the order. If this parameter is transmitted at request, the condition of total_fee=price×quantity must be met. |
Y |
10 |
|
goods_detail |
String |
Description of the details of goods in the format of json The maximum allowable goods number is 50. |
Y |
[{"goodsId":"apple-01","goodsName":"ipad","goodsCategory":"7788230","price":"2000.00","qu antity":"1"}] |
|
extend_params |
String(512) |
This parameter contains extended parameters of the request, and transmits business information of the merchant. Format: JSON. For details, see here |
N |
{"store_id":"BJ_ZZ_001","store_name":"Muku in the Dreieichstrabe","secondary_merchant_id":"A80001","secondary_merchant_name":"Muku","secondary_merchant_industry":"7011"} |
|
it_b_pay |
String(200) |
Set the overtime of non-payment trade, the trade will be closed automatically once the time is up, 3m by default. Range of values: 1m to 15d. m-minute, h-hour, d-day, 1c-current day (Whenever the trade is created, it will be closed at 0:00). Demical point of the numerical value of this parameter is rejected, for example, 1.5h can be tansformed to 90m. To realize this function, Alipay is needed to be advised to set close time. |
Y |
1d |
|
passback_parameters |
String(256) |
If merchant transfer this parameter by the request string, Alipay will feedback this parameter by the asynchronous notify (parameter name: extra_common_param). |
Y |
test |
Parameter | Name | Type | Description | Nullable | Sample |
---|---|---|---|---|---|
secondary_merchant_id | Secondary merchant ID | String | A unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores. | N | A80001 |
secondary_merchant_name | Secondary merchant name | String | A name is shown in the Alipay Wallet and the reconciliation file to identify a secondary merchant. | N | Muku |
secondary_merchant_industry | MCC code of the merchant | String | For MCC code definitions, see MCC list | N | 7011 |
store_name | Store name | String | Store name. Can be null only when the store information is verified. | N | Muku in the Dreieichstrabe |
store_id | Store ID | String | Store ID, must be passed. | N | BJ_ZZ_001 |
terminal_id | Terminal ID | String | Terminal ID | Y | T80001 |
sys_service_provider_id |
The technical provider id |
String(32) |
The technical provider id. This parameter identifies the payment system provider.
|
Y |
R00998889911 |
Goods details parameters shall be in the format of JSON and include the following parameters:
Parameter |
Parameter Name |
Type (Byte Length) |
Parameter Description |
Nullable |
Example |
goodsId |
Goods ID |
String |
Goods ID |
N |
apple-01 |
goodsName |
Goods name |
String |
Goods Name |
N |
ipad |
goodsCategory |
Goods category |
String |
Goods Category |
Y |
34543238 |
showUrl |
Website for the show of goods |
String |
Hyperlink for the show of goods on the webpage of checkout counter. |
Y |
http://www.taobao.com |
quantity |
Goods quatity |
String |
Goods quatity |
N |
1 |
body |
Goods description |
String |
Goods description |
Y |
Cellphone at a sale |
price |
Unit price of goods |
String |
Unit price of goods |
N |
2000 |
The format structure:
[
{Goods_ID: goods ID 1,
goodsname: goods name 1,
goods_category: goods category 1,
Website for the show of goods: website 1 for the show of goods,
goods quantity: goods quantity 1,
goods description: goods description 1,
unit price of goods: unit price 1 of goods
},
{Goods ID: goods ID 2,
goods name: goods name 2,
goods category: goods category 2,
Website for the show of goods: website 2 for the show of goods,
goods quantity: goods quantity 2,
goods description: goods description 2,
unit price of goods: unit price 2 of goods
},
…
]
Example:
Business demand:
goods ID: apple-01,
goods name: ipad,
goods category:
7788230, quantity: 1,
price: RMB 2,000 Yuan;
Parameter assignment:
goods_detail=[
{"goodsId":"apple-01",
"goodsName":"ipad",
"goodsCategory" :"7788230",
"price":"2000.00",
"quantity":"1"}
]
https://intlmapi.alipay.com/gateway.do?_input_charset=UTF-8&body=iphone cellphone¤cy=USD&extend_params={"secondary_merchant_name":"Lotte","secondary_merchant_id":"123","secondary_merchant_industry":"5812","store_id":"A101","store_name":"McDonald in 966 3rd Ave, New York"}¬ify_url=http://api.test.alipay.net/atinterface/receive_notify.htm&out_trade_no=4363476566647440&partner=2088021966388155&passback_parameters=test&price=0.01&product_code=OVERSEAS_MBARCODE_PAY&quantity=1&seller_email= testoverseas1980@alipay.com&seller_id=2088021966388155&sendFormat=normal&service=alipay.acquire.precreate&show_url=http://www.taobao.com/product/113714.html&subject=Payment by QR-Code&total_fee=0.01&trans_currency=USD&sign=2127020ad640f41eec725c639f1de294
Alipay processes the request data provided by merchant and then returns result data to merchant to enable merchant to conduct further processing based on these data.
The result returned can be divided into two types, one is the result of normal business acceptance and process, the other is system-level abnormity or transmitted data error. For the normal business acceptance and process, merchant is required to analyze response code to judge whether business is processed successfully.
Parameter |
Type (Byte) |
Parameter Description |
Nullable |
Example |
||||||
Basic Parameter |
||||||||||
is_success |
String |
Request succeeds or not. Successful request does not mean the business is accepted and processed successfully. T means success F means failure |
N |
T |
||||||
sign_type |
String |
Three values, namely, DSA, RSA and MD5 can be chose; and must be capitalized |
Y |
MD5 |
||||||
sign |
String |
See Digital signature for details. |
Y |
ea489fc31da63253ba b52ed77fb45eb7 |
||||||
error |
String |
This parameter does not exist if request succeeds; This parameter is error coade if request fails; please refer to “10.3 System Error Code” |
Y |
ILLEGAL_SIGN |
||||||
Result Code |
||||||||||
result_code |
String(32) |
Response code of the processing result of order placement and payment; please refer to “10.1 Business Response Code” |
N |
SUCCESS |
||||||
out_trade_no |
String(64) |
Unique order ID in order system in corresponding merchant’s website other than Alipay trade number. Uniqueness of this parameter in merchant’s website shall be guaranteed. This is a parameter transmitted upon corresponding request, which shall be returned in its original shape. |
Y |
99003911198989 |
||||||
voucher_type |
String(10) |
Voucher type, currently qrcode is the only supported value |
Y |
qrcode |
||||||
qr_code |
String(128) |
Value of the QR code |
Y |
https://qr.alipay.com/pmxqwqka1ts5grar29 |
||||||
big_pic_url |
String |
QR code big picture URL |
Y |
http://mobilecodec. alipay.com/show.htm?code=baxga4hjmcal5rl8fa&picSize=L |
||||||
pic_url |
String |
QR code normal size URL |
Y |
http://mobilecodec. alipay.com/show.htm?code=baxga4hjmcal5rl8fa&picSize=M |
||||||
small_pic_url |
String |
QR code big size URL |
Y |
http://mobilecodec. alipay.com /show.htm?code=baxga4hjmcal5rl8fa&picSize=S |
||||||
detail_er ror_code |
String(48) |
Describes the returned response code. If the response code of result_code is ORDER_SUCCESS_PAY_S UCCESS, this parameter shall not be returned. |
Y |
REASON_ILLEGAL_STATUS |
||||||
detail_er ror_des |
String(64) |
Give literal statement as to the detailed error code. If the response code of result_code is ORDER_SUCCESS_PAY_S UCCESS, this parameter shall not be returned. |
Y |
Trade does not match with buyer |
Business is accepted and processed normally, and acquiring is created successfully:
<?xml version="1.0" encoding="UTF-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="body">bodyyy</param>
<param name="operator_id">1232</param>
<param name="subject">dddd</param>
<param name="sign_type">RSA</param>
<param name="store_id">123</param>
<param name="out_trade_no">3177578879372734</param>
<param name="sendFormat">normal</param>
<param name="currency">GBP</param>
<param name="timestamp">1456507704121</param>
<param name="sign">T/9olfnp/rGwmSV0dCkJVvcMuJM2pbstsSFVH54FdN9AbWRbGKNzXwbELbLSJgNZWQej8QqHJauQztG/nC9McWSbeaNsmOrrLnZ+T5XQjCJHilBbupFBsLgF1vzSHe02bICumIjw8r81ysyTHXFmqROaG9hqs0TvFkDpA7O4Ft4=</param>
<param name="_input_charset">UTF-8</param>
<param name="trans_currency">GBP</param>
<param name="total_fee">8.8</param>
<param name="product_code">OVERSEAS_MBARCODE_PAY</param>
<param name="service">alipay.acquire.precreate</param>
<param name="partner">2088101181776059</param>
<param name="seller_id">2088101181776059</param>
<param name="alipay_ca_request">2</param>
<param name="extend_params">{"store_id":"BJ_ZZ_001","store_name":"Muku in the Dreieichstrabe","secondary_merchant_id":"A80001","secondary_merchant_name":"Muku","secondary_merchant_industry":"7011"}</param>
</request>
<response>
<alipay>
<big_pic_url>http://mobilecodec.daily.alipaydev.com/show.htm?code=bax009917nmpivmndisb00e6&picSize=L</big_pic_url>
<out_trade_no>3177578879372734</out_trade_no>
<pic_url>http://mobilecodec.daily.alipaydev.com/show.htm?code=bax009917nmpivmndisb00e6&picSize=M</pic_url>
<qr_code>https://qr.alipay.com/bax009917nmpivmndisb00e6</qr_code>
<result_code>SUCCESS</result_code>
<small_pic_url>http://mobilecodec.daily.alipaydev.com/show.htm?code=bax009917nmpivmndisb00e6&picSize=S</small_pic_url>
<voucher_type>qrcode</voucher_type>
</alipay>
</response>
<sign>ZDWE75ZB0YptqcxKC09g2dSuHEDnWbZ3j+tdpfAt1Il2FmJgJ7Mz9MX/QY0UxZXLP+bYjjC27OJgbhHljVUfrSYN/Ls4vvV/yg6I2/wetK/4Etdt/RJ2og7yRXhE+XzKaG7Q9rYhwnMq3lxukWZA2gep5T69P8yQS8Lz5KZrgjU=</sign>
<sign_type>RSA</sign_type>
</alipay>
Request succeeds, business processing fails:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="body">face-to-face-payment</param>
<param name="subject">iphone</param>
<param name="sign_type">MD5</param>
<param name="out_trade_no">99003911198989</param>
<param name="total_fee">10</param>
<param name="partner">2088101106499364</param>
<param name="quantity">10</param>
<param name="sign">a1cb41a4019351965d4418c9cb933f0f</param>
<param name="_input_charset">UTF-8</param>
<param name="price">1</param>
<param name="it_b_pay">1d</param>
<param name="product_code">OVERSEAS_MBARCODE_PAY</param>
<param name="service">alipay.acquire.precreate</param>
<param name="seller_id">2088101106499364</param>
</request>
<response>
<alipay>
<result_code>FAIL</result_code>
<detail_error_code>INVALID_PARAMETER</detail_error_code>
<detail_error_des>request paramter invalid</detail_error_des>
</alipay>
</response>
<sign>ea489fc31da63253bab52ed77fb45eb7</sign>
<sign_type>MD5</sign_type>
</alipay>
Output when Request fails or the data accessed is wrong:
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>
Alipay will notify merchant’s website of the result data it processed through initiative notification from server after it completes the processing of request data of merchant. These result data are asynchronous notify parameters from server.
http://address_defined_by_merchant/alipay/notify_url.php?notify_id=ac05099524730693a8b330c5ecf72da978&seller_email=zhuzhanghu%40alitest.com¬ify_type=trade_status_sync&buyer_em ail=13882390011&sign=601510b7970e52cc63db0f44997cf70e&trade_no=2013 112711001004940000394507&buyer_id=2088102105236945&quantity=10&tota l_fee=10.00&price=1.00&gmt_create=2013-11-27+15%3A45%3A57&out_trade_ no=5431395578198135&seller_id=2088101106499364¬ify_time=2013-11-2 7+15%3A45%3A58&subject=%E5%A3%B0%E6%B3%A2%E6%94%AF%E4% BB%98-%E5%88%86%E8%B4%A6-sky&trade_status=WAIT_BUYER_PAY&sign_type=MD5
Response Code |
Description |
SUCCESS |
The ordering succeed. |
FAIL |
The ordering fails. |
Error Code |
Description |
Action |
SYSTEM_ERROR |
Alipay system is currently not available. |
Retry this request with the exact parameters. Refer Case 2 at here for detailed instruction. |
CONTEXT_INCONSISTENT |
You were retrying a request identified by the same out_trade_no, but not all other request parameters were same. |
Retry this request with the exact parameters. Or use a fresh out_trade_no. |
TRADE_HAS_SUCCESS |
The payment of trade has been made successfully. |
Mark this transaction as paid in your merchant system. |
TRADE_HAS_CLOSE |
The trade has expired. |
Start a new transaction. |
TRADE_HAS_FINISHED |
The trade has been finished. |
Start a new transaction. |
REASON_ILLEGAL_STATUS |
The trade status is illegal. |
Start a new transaction. |
EXIST_FORBIDDEN_WORD |
Banned words are included in order information. |
Delete concerning words. |
ACCESS_FORBIDDEN |
Has no right to use the product. |
Make sure your agreement with Alipay still valid. |
SELLER_NOT_EXIST |
The seller does not exist. |
Check the seller parameter value. |
SELLER_BEEN_BLOCKED |
The seller's account has been Frozen. |
Contact Alipay tech support for help. |
INVALID_PARAMETER |
Parameter error. |
Please check the standard of each request parameter according to the API specification |
CURRENCY_NOT_SUPPORT |
This currency is not supported. |
Check the value of parameter currency. |
RESTRICTED_MERCHANT_INDUSTRY |
The transaction value cannot be greater than 5000 US dollars. |
Check your value of secondary_merchant_industry and contact Alipay technical support if needed. |
PRODUCT_AMOUNT_LIMIT_ERROR |
The transaction amount exceeded the limit. |
User change other payment method like cash or credit card |
EXCHANGE_AMOUNT_OR_CURRENCY_ERROR |
The exchange amount or currency is incorrect. |
Please contact Alipay technical support for help. |
ILLEGAL_MERCHANT_INDUSTRY |
Illegal MCC format. |
Make sure the value of secondary_merchant_industry be defined at MCC list |
FORBIDDEN_MERCHANT_INDUSTRY |
This transaction type is not allowed. |
Check your value of secondary_merchant_industry and contact Alipay technical support if needed. |
INVALID_RECEIVE_ACCOUNT |
The seller is not in the payee list. |
Please contact Alipay technical support for help. |
Error Code |
Description |
Action |
ILLEGAL_SIGN |
Illegal signature. |
Please read chapter Digital Signature |
INVALID_PARAMETER |
Parameter error. |
Please check the standard of each request parameter according to the API specification |
ILLEGAL_ARGUMENT |
Parameter error. |
Please check each request parameter according to the API specification, contact Alipay technical support if this error persists |
ILLEGAL_PARTNER |
Incorrect partner ID. |
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. |
Please make sure 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 |
Partner ID do not have access privilege. |
Make sure your agreement with Alipay has been finalized. Contact Alipay technical support if needed. |
ILLEGAL_SIGN_TYPE |
Illegal sign type. |
Please make sure the value of sign_type is among MD5,DSA and RSA, contact Alipay technical support if this error persists |
HAS_NO_PRIVILEGE |
Has no privilege. |
Please contact Alipay technical support. |
ILLEGAL_EXTERFACE_FOR_CA_VERIFY |
The interface is not allowed to use Certificate Verification Service. |
Please contact Alipay technical support for help. |
ILLEGAL_CERT_IS_OVERDUE |
Certificate verification failed due to the expired certificate. |
Check the status of your certificate. |
ILLEGAL_CA_SIGN |
Certificate verification failed. |
Check the status of your certificate. |
Enumeration Name |
Description |
WAIT_BUYER_PAY |
The trade has been established and is waiting for the buyer to make payment. |
TRADE_CLOSED |
Trade closed whose payment has not been completed within specified time; Trades closed whose payment has been fully returned when the trade completes. |
TRADE_SUCCESS |
The trade succeeds and is operable, such as multi-level royalty distribution, refund, etc. |
TRADE_FINISHED |
The trade succeeds and finishes and is not operable. |
Case 1. When the invocation failed with network issue or request timeouted, so got no response from Alipay
Case 2. Received response from Alipay, but (1) is_success=F and error=SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code=SYSTEM_ERROR
Case 3. Received response from Alipay, and is_success=T and result_code=SUCCESS. Continue the business process by rendering the QR code
Case 4. Received response from Alipay, and (1) is_success=F and error=!SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code!=SYSTEM_ERROR. Refer specific error code for instrunction
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.
}
}
}
Alipay will notify merchant’s website of the result data it processed through initiative notification from server after it completes the processing of request data of merchant. These result data are asynchronous notify parameters from server.
Parameter | Name | Type | Description | Nullable | Sample |
---|---|---|---|---|---|
Basic parameter | |||||
notify_time | Notification time | Date | The time when the notification is sent. The time format is yyyy-MM-dd HHss。 | N | 2013/11/27 15:45 |
notify_type | Notification type | String | Notification type | N | trade_status_sync |
notify_id | Notification ID | String | Notification ID | N | ac05099524730693a8b330c5ecf72da978 |
sign_type | Sign type | String | The value can be one of DSA, RSA, or MD5. Uppercase must be used | N | MD5 |
sign | Signature | String | Refer to “8 Signature Mechanism”. | N | 601510b7970e52cc63db0f44997cf70e |
notify_action_type | Notification action type | String | Notification action type: creat:createDirectPayTradeByBuyerAction Pay:payByAccountAction Refund:refundFPAction Reverse:reverseAction Close trade:closeTradeAction Finish:finishFPAction | Y | payByAccountAction |
Business parameter | |||||
out_trade_no | The unique order number on the merchant's webpage | String | The merchant order number instead of the Alipay trade number. The number must be unique in merchant’s system and will be returned as is. | Y | 5431395578198135 |
subject | Title of the goods | String | Title of the goods/ Title of the trade/ Title of the order/Key words of the order and so on. The subject is in the first row of the Alipay transaction details and is very important for reconciliation. The subject will be returned as is. | Y | test subject |
trade_no | Alipay trade number | String | The serial number of the trade in Alipay system. The range of the length value: 16-64 | Y | 2013112711001004940000394507 |
trade_status | Trade status | String | Current status of the trade. | Y | WAIT_BUYER_PAY |
gmt_create | Trade creating time | Date | The time when the trade transaction is created. Format: yyyy-MM-dd HHss。 | Y | 2013/11/27 15:45 |
gmt_payment | Trade payment time | Date | The time when the payment is done. Format: yyyy-MM-dd HHss | Y | 2013/11/27 15:45 |
seller_email | Seller’s Alipay ID | String | Seller’s Alipay ID, can be email or phone number | Y | zhuzhanghu@alitest.com |
buyer_email | Buyer’s Alipay ID | String | Buyer’s Alipay ID, can be email or phone number | Y | 13882390011 |
seller_id | Seller’s Alipay ID | String | Seller's unique Alipay user ID consists of 16 numbers that begin with 2088. | Y | 2088101106499364 |
buyer_id | Buyer’s Alipay ID | String | Buyer's unique Alipay user ID consists of 16 numbers that begin with 2088. | Y | 2088102105236945 |
price | Unit price of the goods | Number | Corresponding to the price in the request parameter and will be returned as is. | Y | 1 |
quantity | Quantity of the goods | Number | Corresponding to the quantity in the request parameter and will be returned as is. | Y | 10 |
total_fee | Money amount of the trade transaction. | Number | Money amount of the trade transaction. Corresponding to the request parameter and will be returned as is. | Y | 10 |
body | Description of the goods | String | The detail description of the trade transaction, including notes, description, details and so on. Corresponding to the request parameter and will be returned as is. | Y | Hello |
refund_fee | Refund amount | Number | The refund amount. The unit is Yuan. | Y | 1 |
out_biz_no | Merchant’s business serial number | String | Merchant’s business Id. In most cases is the serial number of the refund request in the refund notification. | Y | HZRF001 |
paytools_pay_amount | Payment amount | String | Payment amount information of all successful payments in various channels. | Y | [{"MCARD":"7.94"},{"TMPOINT":"1.69"},{"BANKCARD":"5.55"}] |
extra_common_param | Business passback parameter | String | The passback_parameters is returned as is. | Y | I'm a passback parameter |
m_discount_forex_amount | the discount amount redeemed | Number | If coupons/vouchers are used in the transaction, the discount amount redeemed in the settlement currency will be returned. Otherwise, no return. | Y | 2.19 |
Parameter | Name | Type | Description | Nullable | Sample |
---|---|---|---|---|---|
ALIPAYACCOUNT | Alipay account | String | The money amount paid by the balance of Alipay account. The unit is Yuan. | Y | 1.23 |
MCARD | Merchant's prepaid card | String | The money amount paid by the merchant's prepaid card. The unit is Yuan. | Y | 7.94 |
MDISCOUNT | Merhant's discount coupon | String | The money amount paid by the merchant's discount coupon. The unit is Yuan. | Y | 1.23 |
TMPOINT | Tmall points | String | The money amount paid by the Tmall points. The unit is Yuan. | Y | 1.69 |
COUPON | Coupon | String | The money amount paid by coupons. The unit is Yuan. | Y | 1.23 |
POINT | Taobao points | String | The money amount paid by points. The unit is Yuan. | Y | 1.23 |
DISCOUNT | Discount | String | The money amount paid by the discount. The unit is Yuan. | Y | 1.23 |
BANKCARD | Bank card | String | The money amount paid by the money fund. The unit is Yuan. | Y | 5.55 |
MONEYFUND | Money fund | String | The money amount paid by the money fund. The unit is Yuan. | Y | 1.23 |
BAITIAO | Baitiao | String | The money amount paid by BAITIAO. The unit is Yuan. | Y | 1.23 |
PCARD | Alipay card | String | The money amount paid by the Alipay card. The unit is Yuan. | Y | 2.13 |
PCREDIT | Credit payment(Consumption credit) | String | The money amount paid by the consumption credit card The unit is Yuan. | Y | 1.23 |
MCOUPON | Merchants issued coupon | String | The money amount paid by the merchants issued coupons. The unit is Yuan. | Y | 2.21 |
Data structure:
[
{"<pay_tool_type_1>":"<amount_1>"}
,
{"<pay_tool_type_2>":"<amount_2>"}
,
…
]
Sample:
paytools_pay_amount=[{"MCARD":"7.94"},{"TMPOINT":"1.69"},{"BANKCARD":"5.55"}]
http://some_domain/alipay/notify_url.php?notify_id=ac05099524730693a8b330c5ecf72da978&seller_email=zhuzhanghu%40alitest.com¬ify_type=trade_status_sync&buyer_email=13882390011&sign=601510b7970e52cc63db0f44997cf70e&trade_no=2013112711001004940000394507&buyer_id=2088102105236945&quantity=10&total_fee=10.00&price=1.00&gmt_create=2013-11-27+15%3A45%3A57&out_trade_no=5431395578198135&seller_id=2088101106499364¬ify_time=2013-11-27+15%3A45%3A58&subject=%E5%A3%B0%E6%B3%A2%E6%94%AF%E4%BB%98-%E5%88%86%E8%B4%A6-sky&trade_status=WAIT_BUYER_PAY&sign_type=MD5
Error Code |
Description |
Action |
SYSTEM_ERROR |
Alipay system is currently not available. |
Retry this request with the exact parameters. Refer Case 2 at here for detailed instruction. |
ILLEGAL_SIGN |
Illegal signature. |
Please read chapter Digital Signature |
INVALID_PARAMETER |
Parameter error. |
Please check the standard of each request parameter according to the API specification |
ILLEGAL_ARGUMENT |
Parameter error. |
Please check each request parameter according to the API specification, contact Alipay technical support if this error persists |
ILLEGAL_PARTNER |
Incorrect partner ID. |
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. |
Please make sure 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 |
Partner ID do not have access privilege. |
Make sure your agreement with Alipay has been finalized. Contact Alipay technical support if needed. |
ILLEGAL_SIGN_TYPE |
Illegal sign type. |
Please make sure the value of sign_type is among MD5,DSA and RSA, contact Alipay technical support if this error persists |
HAS_NO_PRIVILEGE |
Has no privilege. |
Please contact Alipay technical support |
REASON_TRADE_BEEN_FREEZEN |
Corresponding trade has been frozen due to security issues. |
Please contact Alipay technical support |
TRADE_NOT_EXIST |
Cannot find corresponding trade according to input “partner_trans_id”. |
1) Make sure the partner_trans_id is correct 2)if the issue persists, please contact Alipay Technical Support |
TRADE_STATUS_ERROR |
Corresponding trade status is not allowed for current operate. |
1) Make sure the trade status is correct 2)if the issue persists, please contact Alipay technical support |
BUYER_ERROR |
The buyer does not exist. |
Please contact Alipay technical support. |
BUYER_ENABLE_STATUS_FORBID |
Buyer account status prohibits the refund. |
Please contact Alipay technical support. |
SELLER_ERROR |
The seller does not exist. |
Please contact Alipay technical support. |
MERCHANT_BALANCE_NOT_ENOUGH |
Merchant balance is not enough for refund. |
Try again later after new transactions occurred. |
TRADE_CANCEL_TIME_OUT |
The cancellation request is beyond the opening hours. |
Please use the refund interface instead. |
SELLER_BALANCE_NOT_ENOUGH |
Insufficient balance of seller. |
Try again later after new transactions occurred. |
REASON_TRADE_REFUND_FEE_ERR |
Invalid refund amount. |
Please contact Alipay technical support for help. |
TRADE_HAS_FINISHED |
Transaction completed. |
Please use the refund interface instead. |
REFUND_CHARGE_ERROR |
The refund failed because the payment is in progress. |
Please try again later. |
Case 1. When the invocation failed with network issue or request timeouted, so got no response from Alipay
Case 2. Received response from Alipay, but (1) is_success=F and error=SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code=SYSTEM_ERROR, or (3) is_success=T and result_code=UNKNOWN.
Case 3. Received response from Alipay, and is_success=T and result_code=SUCCESS. Mark merchant cancel order as processed successfully
Case 4. Received response from Alipay, and (1) is_success=F and error=!SYSTEM_ERROR, or (2) is_success=T and result_code=FAIL and detail_error_code!=SYSTEM_ERROR. Mark merchant cancel order as failed. Refer specific error code for instrunction
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.
}
}
}
Alipay provide reconciliation files to merchant using cross-border in-store payment services. Merchants can fetch the reconciliation files to view details of their balance. Reconciliation files consist of settlement files and transaction files. The settlement file of a T day is only generated if there is any settlement on that day. If you download settlement files from SFTP sites or Alipay global site, a summary file of the settlement is also available.
Note:
The file naming rule is:
You can obtain the reconciliation files from SFTP sites or Alipay global site. However, the files obtained by using these channels vary in their names and contents, which is further explained in the following sections.
To obtain your reconciliation files through SFTP, complete the following steps:
After integration with Alipay, submit your PID and the IP address with which you visit SFTP site to Alipay Overseas Support. The IP address must not be an intranet IP. After receiving your request, Alipay will send you the login credentials in 5 working days.
Download and install Winscp. Use the following settings to log in and obtain files:
Login to Global portal (Alipay global site), go to My Alipay – My Transaction to view and download your transaction files and settlement files. You can also download the files at the Download Files tab.
Watch the video to learn the procedure:
Files can only be downloaded after the file is generated.
Call this interface to register offline secondary merchants information into Alipay system.
Environment | HTTPS request URL |
---|---|
Production environment | https://intlmapi.alipay.com/gateway.do |
Test environment | https://mapi.alipaydev.com/gateway.do |
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
Parameter |
Type (bytes) |
Description |
Optional |
Example |
|
Basic Parameter |
|||||
service |
String |
Service Name |
N |
alipay.overseas.secmerchant.offline.maintain |
|
partner |
String(16) |
A unique partner ID to identify a contracted Alipay Account. A 16 digit number starts with 2088. |
N |
2088*********662 |
|
_input_charset |
String |
The charset with which the request data is encoded. For example, UTF-8, GBK, GB2312 etc. |
N |
gbk |
|
sign_type |
String |
DSA, RSA, or MD5, use upper case |
N |
MD5 |
|
sign |
String |
The value of sign |
N |
2118ac8fad6bc1d9e88a6cd017c18d37 |
|
timestamp |
String |
The time when the merchant server sends request, in GMT + 8, format: yyyy-MM-dd HH:mm:ss. By default, the request expires in 30 minutes. |
N |
2012-12-21 17:11:16 |
|
Business Parameter |
|||||
secondary_merchant_name |
String(128) |
Registration legal name of the secondary merchant, which is shown in the wallet and reconciliation file to identify a secondary merchant. Note: If the secondary merchant type is INDIVIDUAL, specify the full legal name of the business owner to this field. |
N |
Alipay.com Co.,Ltd |
|
secondary_merchant_id |
String(64) |
The unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores. |
N |
63472327348 |
|
store_id |
String(64) |
Store ID. For taxicabs and limousines (MCC 4121), use the license plate number. |
N |
23372327348 |
|
store_name |
String(256) |
Store name. For taxicabs and limousines (MCC 4121), use the license plate number. |
N |
StoreName |
|
store_country |
String(2) |
Store registration country. A 2-letter code defined in ISO 3166. |
N |
HK |
|
store_address |
String(330) |
Registered store address. Use mailing address format. |
N |
Store address |
|
store_industry |
String(4) |
A 4-digit MCC code of the store. See MCC list for details. |
N |
4121 |
|
internal_store_photo |
String(256) |
URL of the store interior photo. |
Y |
URL |
|
external_storefront_photo |
String(256) |
URL of the store exterior photo. |
Y |
URL |
|
extend_params |
String(1024) |
Taxi driver information in JSON format. JSON keys are fixed as operation_id, contact_way, and contact_person. Up to 10 drivers can be passed. Note: The value of each operation_id must be unique. This field cannot be updated incrementally. Pass this field the first time you register a driver; otherwise you cannot add it later when you update the driver information. |
Y |
[{"operation_id": "1000332", "contact_way": "138xxxx1232", "contact_person": "driverName1"}, {"operation_id": "1082943492", "contact_way": "158xxxx2232", "contact_person": "driverName2"}] |
|
secondary_merchant_type |
String |
Secondary merchant type, the value can be INDIVIDUAL for the sole proprietorship or ENTERPRISE for the limited company, private company, partnership, limited liability partnership (LLP), limited liability company (LLC), S corporation (S Corp), C corporation (C Corp), trust, or nonprofit organization (NPO) |
N |
INDIVIDUAL |
|
registration_no |
String(128) |
Business registration number specified on the business registration document. Note: This field is not required when the secondary merchant type is INDIVIDUAL and no registration number exists. |
N |
012345678 |
|
register_country |
String(2) |
Registration country of the secondary merchant, specified by a 2-letter code defined in ISO 3166. For more details about the 2-letter country code, see ISO 3166. |
N |
HK |
|
register_address |
String(256) |
Business registration address specified on the business registration document. Use mailing address format. | N |
No.277, Road YinCheng, Shanghai, China |
|
shareholder_name |
String(128) |
Legal name of the primary shareholder of the secondary merchant. Specify this field only when the secondary merchant type is ENTERPRISE. |
Y |
Jack Li (if the shareholder is an individual), Alipay.com Co.,Ltd (if the shareholder is an enterprise) |
|
shareholder_id |
String(128) |
ID or passport number, or business registration number of the primary shareholder of the secondary merchant. Specify this field only when the secondary merchant type is ENTERPRISE. |
Y |
G53453888 (if the shareholder is an individual), 012345678 (if the shareholder is an enterprise) |
|
representative_name |
String(128) |
Full legal name of the business owner. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE. |
N |
Tom Li |
|
representative_id |
String(128) |
ID or passport number of the business owner. Specify this field only when the secondary merchant type is INDIVIDUAL. This field is optional if the secondary merchant type is ENTERPRISE. |
N |
123456789 |
|
settlement_no |
String(64) |
Settlement bank account number of the secondary merchant, letters and numbers only |
N |
2600100000 |
|
contact_no |
String(64) |
Contact phone number of the secondary merchant, numbers and special characters +-() only |
N |
186xxxx0000 |
|
contact_email |
String(128) |
Contact email address of the secondary merchant |
N |
tomli@gmail.com |
|
cs_no |
String(64) |
Customer service phone number of the secondary merchant, numbers and special characters +-() only |
Y |
952xx |
|
cs_email |
String(128) |
Customer service email address of the secondary merchant |
Y |
customerservice@xxxcompany.com |
Parameter |
Type (bytes) |
Description |
Optional |
Example |
operation_id |
String(64) |
Taxi driver ID. Use only numbers and letters. |
N |
1082943492 |
contact_way |
String(256) |
Phone number of the taxi driver. Use “+”, numbers, spaces, and “-“. |
Y |
158xxxx2232 |
contact_person |
String(64) |
Taxi driver name |
N |
driverName2 |
Some parameters of String type have no length limit and the system will not check their length.
The response is in XML format.
Parameter |
Type (bytes) |
Description |
Optional |
Example |
|
Basic Parameter |
|||||
is_success |
String |
Request succeeds or not. Successful request does not mean the business request is accepted and processed successfully. |
N |
T |
|
sign_type |
String |
The value can be one of DSA, RSA, or MD5. Uppercase must be used. |
Y |
MD5 |
|
sign |
String |
The value of sign |
Y |
3afc92ac4708425ab74ecb2c4e58ef56 |
|
error |
String |
|
Y |
PARAM_ILLEGAL |
|
result_code |
String |
Request result code. This field is returned only when the is_success field is T. |
Y |
SUCCESS |
The synchronous response may have more parameters due to the upgrade on the Alipay server side. You can ignore parameters that are not included in this API document.
The sample is for reference only. Alipay gateway is https://mapi.alipay.com/gateway.do?_input_charset=UTF-8.
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="service">alipay.overseas.secmerchant.offline.maintain</param>
<param name="partner">2088101142878662</param>
<param name="_input_charset">UTF-8</param>
<param name="sign_type">MD5</param>
<param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
<param name="timestamp">2018-08-03 00:28:32</param>
<param name="secondary_merchant_name">hanguo</param>
<param name="secondary_merchant_id">2015051446800462</param>
<param name="store_id">23372327348</param>
<param name="store_name">LV</param>
<param name="store_country">HK</param>
<param name="store_address">store address</param>
<param name="store_industry">4121</param>
<param name="secondary_merchant_type">INDIVIDUAL</param>
<param name="registration_no">012345678</param>
<param name="register_country">HK</param>
<param name="register_address">No.277, Road YinCheng, Shanghai, China</param>
<param name=“representative_name”>Tom Li</param>
<param name=“representative_id”>123456789</param>
<param name="settlement_no">2600100000</param>
<param name="contact_no">186xxxx0000 </param>
<param name="contact_email">support@xcompany.com </param>
</request>
<response>
<alipay>
<result_code>SUCCESS</result_code>
</alipay>
</response>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>ILLEGAL_SIGN</error>
</alipay>
Returned result |
Description |
Solution |
MCC_CAN_NOT_MODIFY |
The MCC passed in cannot match the original MCC. |
Please ensure that the passed MCC is the same as the original MCC. |
MCC_TYPE_ILLEGAL |
The MCC is invalid. |
Modify the MCC type and then try again. |
PARAM_ILLEGAL |
The parameter is illegal. The parameter is too long, parameter format is wrong, or a required parameter is not passed. |
Please check and rectify the parameter according to the API document. |
SYSTEM_ERROR |
Alipay system error |
Please try again later. |
LBS_GEOGRAPHIC_INFORMATION_INVALID |
The address cannot match the country/region, or the address cannot be located. |
Please ensure that the address is valid and use the address that can be located in Google map. |
CATEGORY_NOT_SUPPORT_DRIVER |
When store_industry is 4121 and extend_params is not passed when you request in the first time, then this error occurs when you update the store information and pass the driver information. |
Please remove the driver information from the extend_param. |
DUPLICATE_REQUEST |
Duplicate request submitted. The previous registration request is still in process. |
Please wait until the previous registration request completes. |
MERCHANT_TYPE_ILLEGAL |
Illegal secondary merchant type. The value of the secondary_merchant_type field can only be ENTERPRISE or INDIVIDUAL. |
Enter the correct value for the secondary_merchant_type field. |
Returned result |
Description |
ILLEGAL_SIGN |
Illegal signature |
ILLEGAL_DYN_MD5_KEY |
Dynamic key information is incorrect |
ILLEGAL_ENCRYPT |
Encryption is incorrect |
ILLEGAL_ARGUMENT |
Incorrect parameter |
ILLEGAL_SERVICE |
Service parameter is incorrect |
ILLEGAL_USER |
User ID is incorrect |
ILLEGAL_PARTNER |
Incorrect Partner ID |
ILLEGAL_EXTERFACE |
Interface configuration is incorrect |
ILLEGAL_PARTNER_EXTERFACE |
Partner's interface information is incorrect |
ILLEGAL_SECURITY_PROFILE |
Matching private key configuration is not 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 |
Has no right to visit |
INVALID_CHARACTER_SET |
The character set is invalid |
When system error occurs, please contact Global Merchant Technical Support .
Returned result |
Description |
SYSTEM_ERROR |
Alipay system error |
SESSION_TIMEOUT |
Session timeout |
ILLEGAL_TARGET_SERVICE |
Wrong target service |
ILLEGAL_ACCESS_SWITCH_SYSTEM |
Merchant is not allowed to visit system of this type |
EXTERFACE_IS_CLOSED |
The interface is closed |
Date |
Modifications |
2019.02.18 |
|
2019.02.28 |
|
Environment | HTTPS request URL |
---|---|
Production environment | https://intlmapi.alipay.com/gateway.do |
Test environment | https://mapi.alipaydev.com/gateway.do |
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
Call this interface to query the registration status of secondary merchants.
Environment | HTTPS request URL |
---|---|
Production environment | https://intlmapi.alipay.com/gateway.do |
Test environment | https://mapi.alipaydev.com/gateway.do |
If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.
Parameter |
Type (length in bytes) |
Description |
Optional |
Example |
|
Basic Parameter |
|||||
service |
String |
Service Name |
N |
alipay.overseas.secmerchant.maintain.queryStatus |
|
partner |
String(16) |
A unique partner ID to identify a contracted Alipay Account. A 16 digit number starts with 2088. |
N |
2088101142878662 |
|
_input_charset |
String |
The charset on partner website, such as utf-8, gbk, gb2312 etc. |
N |
gbk |
|
sign_type |
String |
DSA, RSA, or MD5, capital letter |
N |
MD5 |
|
sign |
String |
The value of sign |
N |
2118ac8fad6bc1d9e88a6cd017c18d37 |
|
timestamp |
String |
The time when the merchant server sends request, in GMT + 8, format: yyyy-MM-dd HH:mm:ss. By default, the request expires in 30 minutes. |
N |
2012-12-21 17:11:16 |
|
Business Parameter |
|||||
secondary_merchant_id |
String(64) |
Secondary merchant ID, need to be unique for each PID |
N |
MERCHANT_ID_0003 |
|
store_id |
String(64) |
Store ID, need to be unique for each group of PID and MID This field is required when the value of payment_method is INSTORE_PAYMENT. |
N |
STORE_ID_0003 |
|
payment_method |
String |
Payment method of the secondary merchant, the value is INSTORE_PAYMENT for offline payments. |
N |
INSTORE_PAYMENT |
The response is in XML format.
Parameter |
Type (bytes) |
Description |
Optional |
Example |
sign |
String |
The value of sign |
Y |
2118ac8fad6bc1d9e88a6cd017c18d37 |
sign_type |
String |
DSA, RSA, or MD5, capital letter |
Y |
MD5 |
secondary_merchant_id |
String |
Secondary merchant ID, need to be unique for each PID |
N |
MERCHANT_ID_0003 |
store_id |
String |
Store ID, need to be unique for each group of PID and MID This field is required when the value of payment_method is INSTORE_PAYMENT. |
N |
STORE_ID_0003 |
status |
String |
Registration status of the secondary merchant, the value can be SUCCESS if the merchant is successfully registered, UNDER_REVIEW if the application for registration is in process, and FAILED if the merchant is not registered. |
N |
SUCCESS |
reject_reason |
String |
The reason that the merchant is not registered successfully. |
Y |
High risk merchant, registration reject. |
Returned result |
Description |
Solution |
PARAM_ILLEGAL |
Required parameters are not entered or illegal parameters entered. The illegal parameter might be too long, or with incorrect format. |
Enter the correct parameters and send the request again. |
DATA_NOT_EXIST |
No data exists for the queried secondary merchant because the merchant is not registered. |
Register the secondary merchant to Alipay system before you query the registration status. |
SYSTEM_ERROR |
Alipay system error |
Please try again later. |
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
<param name="store_id">STORE_ID_0003</param>
<param name="partner">2088101131367863</param>
<param name="service">alipay.overseas.secmerchant.maintain.queryStatus</param>
<param name="sign">9c4643447830d870b56c8181643da9e4</param>
<param name="sign_type">MD5</param>
<param name="_input_charset ">gbk</param>
<param name="timestamp ">2012-12-21 17:11:16</param>
<param name="_input_charset ">gbk</param>
<param name="payment_method">INSTORE_PAYMENT</param>
<param name="secondary_merchant_id">MERCHANT_ID_0003</param>
</request>
<response>
<alipay>
<secondary_merchant_id>MERCHANT_ID_0003</secondary_merchant_id>
<status>UNDER_REVIEW</status>
<store_id>STORE_ID_0003</store_id>
</alipay>
</response>
<sign>a109ce66ba5b825759927c00be3259fa</sign>
<sign_type>MD5</sign_type>
</alipay>
<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>DATA_NOT_EXIST</error>
<sign>6dff2d017f284ca0147fc8f6891b4cb2</sign>
<sign_type>MD5</sign_type>
</alipay>