Introduction

Generate Pre-sign string

Parameters to sign

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)

Generate Pre-sign string

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);
  

_input_charset=utf-8&app_pay=Y&body=test&currency=USD&notify_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

Signature Generation

MD5 Signature

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.

• Sign for request

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”)  

• Signature Verification for response

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.

RSA, RSA2 Signature

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.

• Sign for request

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”)

• Signature Verification for response

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.

With the growing number of Chinese consumers purchasing merchandise on the oversea merchants’ site direct, the merchant could integrate with Alipay Standard Payment solution to offer the users the familiar user experience that they comfortable with, along the convenience provided for both the merchants and the consumers on the payment, FX exchange and settlement.

Once integrated, the merchant’s site will present an Alipay payment button when the consumer completes the payment and checks out.

• The user clicks the payment/checkout button, to make payment with Alipay
• The user would be redirected to Alipay site. He/she could log in, and complete the payment on Alipay.
• Once the payment is completed, the user will be redirected back to the merchant site with the payment result. The merchant could check the result and make decision on how to move forward.
• In the meantime, an asynchronous notification will be sent to the merchant with the payment result. The notification is reliable with build-in retry mechanism.

When the buyer needs to pay, the checkout page is presented as below. Choose Alipay:

The buyer is redirected to the login page. Use the Alipay account to log in.

After login, the payment page is shown. Confirm to pay.

The payment password might be needed:

With the correct password entered, the page with the information of payment success is shown and the buyer is redirected back to the merchant website after this page.

Merchants can reference the following Alipay demo code to do quick integration or directly check the API document and construct the http request to make the payment.

Demo Code Download

For a full list of demo codes, see Demo code list.

Deploy/Run in Sandbox

Take JAVA demo code using MD5 signature algorithm as an example. Import the demo code project into your IDE tool, like Eclipse, then run: Click payment button to pay: Login to Alipay: Input payment password to pay: Payment success: Buyer is brought back to the merchant's website after payment according to parameter return_url.

Integrate/Run in Production

Merchant can integrate the demo code into or write their own code and run in Alipay production. If using demo code, change the following two settings:

1. Change Alipay gateway to production URL:

https://mapi.alipay.com/gateway.do? in AlipaySubmit.java

2. Change the account and key information to the merchant’s real account in AlipayConfig.java. Merchants can check their account and key information in global.alipay.com.

Request Example

https://mapi.alipaydev.com/gateway.do?subject=Beautylish+Order+%23TESTING+-+CHANGE+ME&sign_type=RSA&out_trade_no=8315919735609649&currency=USD&total_fee=100&partner=2088101122136241&notify_url=http%3A%2F%2Fwww.alipay.com& sendFormat=normal&return_url=http%3A%2F%2Fwww.alipay.com&sign=Rbn7JXjgG%2BWt%2FHK8ej1oov8OTDrI7rxH%2FQmfNJ%2FyASGuayUVvD3NkoP0mLo5rmRNF8qNrzH0lQ68U0EFcU4Z6pCVavHI%2BML3lNUagkFQ3YcS6f9pY1WoyEUt02%2FC2VyzxiEDTM%2FS6o6YiDZaUUdS2EPTHPBgvJLvghcafyMKTIo%3D&_input_charset=UTF-8&secondary_merchant_id=834945&secondary_merchant_industry=3435&secondary_merchant_name=holiday&service=create_forex_trade_wap&trade_information={"business_type":"1","hotel_name":"zlidu, sluhg-987, 889utng","check_in_time":"2018-10-20","check_out_time":"2018-10-22"}

Response Example

http://api.receive.com/receive_notify.htm?sign=6c1fd40533ccb5126aa78778ab10417a&trade_no=2015070800001000100080029361&total_fee=11.00&sign_type=MD5&out_trade_no=2525759240575424&trade_status=TRADE_FINISHED¤cy=USD

For the system API calls, in general, the validations are being done at two levels on Alipay side.

The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

Business Logic Errors

The following are the possible errors related to the business logics.

Access Errors / Common Errors with MAPI Gateway

If there are errors in calling parameters, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

System Errors

When system error occurs, please contact Global Merchant Technical Support to assist the error repair.

The single refund interface allows the partners to refund a transaction.

Request Parameters

Sync Response

The response is in XML format

Samples

Request Example

https://intlmapi.alipay.com/gateway.do?reason=refund+test&return_amount=0.1&sign_type=MD5& out_trade_no=iamdjc456¤cy=HKD&sign=8e9004797d3c7112b907bd184d775662&_input_charset=UTF-8&out_return_no=test005&service=forex_refund&partner=2088701998606387

Sync Response Examples

Success response

<?xml version="1.0" encoding="GBK"?>
<alipay>
    <is_success>T</is_success> 
</alipay>

Error response:

<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_SIGN</error>
</alipay>

For the system API calls, in general, the validations are being done at two levels on Alipay side.

The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

Business Logic Errors

Access Errors / Common errors with MAPI gateway

If the calling parameters have error in it, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

System Errors

When system error occurs, please contact Global Merchant Technical Support to assist the error repair.

The partners can use this API to obtain the information on a particular transaction, such as the transaction’s ID, out_trade_no, item name, transaction status, etc.

The gateway URL:

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

Request Parameters

Sync Response

After Alipay finish processing request data, it will notify partner website by posting response data by the way of redirection. The response data of such procedure are these response parameters.
Synchronous Response Parameters Description

Samples

Request Sample

https://mapi.alipaydev.com/gateway.do?service=single_trade_query&sign=d8ed9f015214e7cd59bfadb6c945a87b&trade_no=2010121502730740&partner=2088721091300630&out_trade_no=2009011803596246&sign_type=MD5

Response Sample

Success response

<alipay>
<is_success>T</is_success>
<request>
<param name="_input_charset">UTF-8</param>
<param name="service">single_trade_query</param>
<param name="partner">2088721091300630</param>
<param name="out_trade_no">2009011803596246</param>
<param name="sendFormat">normal</param>
</request>
<response>
<trade>
<body>hello</body>
<buyer_email>inxxxxt059@service.alipay.com</buyer_email>
<buyer_id>208xxxxxxxxx5555</buyer_id>
<discount>0.00</discount>
<flag_trade_locked>0</flag_trade_locked>
<gmt_create>2017-06-15 16:25:31</gmt_create>
<gmt_last_modified_time>2017-06-15 16:25:58</gmt_last_modified_time>
<gmt_payment>2017-06-15 16:25:58</gmt_payment>
<is_total_fee_adjust>F</is_total_fee_adjust>
<operator_role>B</operator_role>
<out_trade_no>2009011803596246</out_trade_no>
<payment_type>100</payment_type>
<price>0.02</price>
<quantity>1</quantity>
<seller_email>test@126.com</seller_email>
<seller_id>2088721091300630</seller_id>
<subject>world</subject>
<to_buyer_fee>0.00</to_buyer_fee>
<to_seller_fee>0.02</to_seller_fee>
<total_fee>0.02</total_fee>
<trade_no>2017061521001003550204235677</trade_no>
<trade_status>TRADE_FINISHED</trade_status>
<use_coupon>F</use_coupon>
</trade>
</response>
<sign>6283ce0cf5aaa812d9c1d29719d53e8d</sign>
<sign_type>MD5</sign_type>
</alipay>

Error response

<?xml version="1.0"  encoding="utf-8"?>
  <alipay>
  <is_success>F</is_success>
  <error>ILLEGAL_SIGN</error>
  </alipay>

For the system API calls, in general, the validations are being done at two levels on Alipay side.

The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

Business Logic Errors

System Errors

When system error occurs, please contact Alipay Technical Support to assist the error repair..

Payment Type

Transaction Status

Additional Trade Status

From time to time, the merchant needs to reconcile the transactions. This interface enables the merchants to download the transaction list in a specific time span to reconcile the transactions.

The gateway URL:

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

Request Parameters

Sync Response

Response format

The responses could be in different formats for different use cases

• It is in XML format if there is error caught by the Gateway
• It could in plain text error message if it is the error from the biz logic
• It is a file to download if the call is successful.

File Format for the Transaction Report file in the Response

Samples

Request Sample

https://mapi.alipay.com/gateway.do?sign_type=MD5&sign=bb4c92c7cb7fc8a5280fe5f9f7ac309c&_input_charset=UTF-8&end_date=20150524&service=forex_compare_file&partner=2088002007018916&start_date=20150520

Response Sample

Success response

The response is HTTP response with an attached file, which is the reconciliation file with the transactions included.
The sample is for illustration of the browser download.

Error response from the biz logic:

File download failed: Over 10 days to Date period

Error response from the Gateway:

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

A sample of transaction report file:

23342347424|112.11|USD|20070616090001||P|2.24|P|Unliquidated
23342343423|102.32|USD|20070615090001|2007622090001|P|2.04|L|Liquidated

For the system API calls, in general, the validations are being done at two levels on Alipay side.

The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

Business Logic Errors

Access Errors / Common Errors with MAPI Gateway

If the calling parameters have error in it, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

System Errors

When system error occurs, please contact Global Merchant Technical Support to assist the error repair.

This interface enables the merchant reconcile the settled transactions with the settlement of the funds in the previous settlement cycle.

The gateway URL:

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

Request Parameters

Sync Response

Response format

The responses could be in different formats for different use cases

• It is in XML format if there is error caught by the Gateway
• It could in plain text error message if it is the error from the biz logic
• It is a file to download if the call is successful.

File Format for the Settlement file in the Response

Samples

Request Sample

https://mapi.alipay.com/gateway.do?sign_type=MD5&sendFormat=normal&sign=bb4c92c7cb7fc8a5280fe5f9f7ac309c&_input_charset=UTF-8&end_date=20150524&service=forex_liquidation_file&partner=2088002007018916&start_date=20150520

Response Samples

Success response

The response is HTTP response with an attached file, which is the settlement file with the transactions included.
The sample is for illustration of the browser download.

Error response from the biz logic:

File download failed: Over 10 days to Date period

Error response from the Gateway:

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

An example of settlement report file：

23342343423|102.32|USD|20070615090001|2007622090001|P|2.04|L|Liquidated

For the system API calls, in general, the validations are being done at two levels on Alipay side.

The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

Business Logic Errors

Access Errors / Common Errors with MAPI Gateway

If the calling parameters have error in it, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

System Errors

When system error occurs, please contact Global Merchant Technical Support to assist the error repair.

To get the exchange rate from Alipay, the partners can call this API.

The gateway URL:

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

Request Parameters

Sync Response

Response format

The responses could be in different formats for different use cases

• It is in XML format if there is error caught by the Gateway
• It could in plain text error message if it is the error from the biz logic
• It is a file to download if the call is successful.
• This exchange rate is ONLY for reference. The real exchange rate is shown on the payment page for each transaction.

File Format for the Transaction Report file in the Response

Samples

Request Sample

https://mapi.alipay.com/gateway.do?sign_type=MD5&sendFormat=normal&sign=590a9fbbed8a5b9a86b426795445f9f0&service=forex_rate_file&partner=2088101122136241

An example of the rate file：

20160504|100030|CHF|6.829600|
20160504|100030|EUR|7.491500|
20160504|100030|THB|0.185877|
20160504|100030|DKK|1.007800|
20160504|100030|SGD|4.815600|
20160504|100030|GBP|9.476100|
20160504|100030|HKD|0.838800|
20160504|100030|NOK|0.803000|
20160504|100030|CAD|5.124900|
20160504|100030|KRW|0.005814|
20160504|100030|NZD|4.496100|
20160504|100030|JPY|0.060934|
20160504|100030|AUD|4.877600|
20160504|100030|SEK|0.809800|
20160504|090530|USD|6.534600|

Response Samples

Success response

The response is HTTP response with an attached file, which is the FX rate file with the FX included.
The sample is for illustration of the browser download.

Error response from the biz logic:

File download failed: Over 10 days to Date period

Error response from the Gateway:

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

For the system API calls, in general, the validations are being done at two levels on Alipay side.

The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

Business Logic Errors

Access Errors / Common Errors with MAPI Gateway

If the calling parameters have error in it, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

System Errors

When system error occurs, please contact Global Merchant Technical Support to assist the error repair.

• Purpose

  Validate a notification is from Alipay Server, ensure the authenticity of the response data.

• Mechanism

  Acquire the parameter notify ID (notify_id), assemble it into a URL according to Alipay requirement, e.g.:
  

  https://mapi.alipay.com/gateway.do?service=notify_verify&partner=2088002396712354¬ify_id=RqPnCoPT3K9%252Fvwbh3I%252BFioE227%252BPfNMl8jwyZqMIiXQWxhOCmQ5MQO%252FWd93rvCB%252BaiGg

  
  Through this request URL, partner can acquire result data from Alipay server with the method of programming to simulate the http request interacting with Alipay server.
  If returned information is true, verification success, otherwise fail.
  

The gateway URL:

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

Request Parameters

Sync Response

The response is a string with the status.

Response Samples

If the input parameter is invalid, return,

Invalid

If the notification is from Alipay, and inquires in the valid time frame, (1 min)

True

If the notification is not from Alipay, or passes 1 min time frame,

False

Samples

Request Sample

https://intlmapi.alipay.com/gateway.do?service=notify_verify&partner=2088101122136241&notify_id=4465b04e84cb6bacc2bd1b52232c0b8gjg&sign=ciSBXc7gjCfXW8KMBxFiFH2cbMZtFelfTOGKqY2NF7q98RnH3E%2BiF5Cj%2Fu%2Bl8py1D%2FOsE%2FAva1ls8A6Tw1MzhG6ideJSgh4FxWmAjEnlczdfLj%2FqzA6qGzxdKGEXaSDFmTGglOembXUqK8g8ajICD%2BBH7xoxBRY7vtfylEXtojs%3D&sign_type=RSA

For the system API calls, in general, the validations are being done at two levels on Alipay side.

The first level is at the API gateway level, where it does certain sanity checks such as verifying the signature, verifying if the partner ID is valid or whether the partner has permission to call this particular API, etc. If the validation fails, Alipay would return the appropriate error codes which are classified as the 'API Gateway Error Codes' as in the below.

Once it passes the validations at the API gateway level, the API request would be dispatched to the internal system for further processing, which it would be subjected to the validations of the business logic. The corresponding error codes returned are classified as the 'Business Error Codes".

Business Logic Errors

Access Errors / Common Errors with MAPI Gateway

If the calling parameters have error in it, Alipay MAPI gateway will capture it and display the errors. However, the control flow will stay at the Alipay side and will NOT return to the merchant’s site.

System Errors

When system error occurs, please contact Global Merchant Technical Support to assist the error repair.

OpenSSL installation

• Linux（Ubuntu）

  sudo apt-get install openssl

• Windows

  The developer can download Windows version of OpenSSL from the official site of https://www.openssl.org/source/.

RSA key pair generation

• Linux

  $ 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          
    

• Windows operates in cmd window:

  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.

• Standard private key file（PHP,.NET）

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

• Standard private key file in PKCS8 format(Java)

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

• Public key file

  -----BEGIN PUBLIC  KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQWiDVZ7XYxa4CQsZoB3n7bfxLDkeGKjyQPt2FUtm4TWX9OYrd523iw6UUqnQ+Evfw88JgRnhyXadp+vnPKP7unormYQAfsM/CxzrfMoVdtwSiGtIJB4pfyRXjA+KL8nIa2hdQy5nLfgPVGZN4WidfUY/QpkddCVXnZ4bAUaQjXQIDAQAB-----END PUBLIC  KEY-----

Upload the public key

Contact Global Merchant Technical Support to upload the public key. Please sign with the matching private key in the key pair.

Merchants can check PID, Key, do refund, check/download transaction and settlement info on global.alipay.com:

Alipay sandbox gateway URL: https://openapi.alipaydev.com/gateway.do?
Merchant account on Sandbox:
PID：2088101122136241
Email Account：overseas_kgtest@163.com

MD5 KEY

  MD5：760bdzec6y9goq7ctyx96ezkz78287de
  

  MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBAKQ5oPb0bAuwPqeBm01hBCiyAEg6q5hLqaHgVOZliuBsY49H9zupOhvCTPFMqV4IheggNqx1C3b2zik5egn/QdY3Y1SDKnWblVMRpdSxmasR1G6Jh6s2JPrgwAYMAnm+800otolXHIAP8Sryz9z9Kti9rtSNejSef/PEndsWTiCbAgMBAAECgYEAiD1q5RUXAYdgIxSpo0MF8UDibQmHS5wRiUKTDGRXFyG0YqyAVZVpqJfDvzcrFuCZPl5jHSUosrPDin2tWdfSZC6Hn7w+L89EwoekThUkSI6J6GPHSTiGssscBjN0RDjGH87KUmGsoDkgdwBFyG5krJOdCNjlWXnjSag6LFEusLkCQQDpqv4pqGKTSR70NjIFDeXIk8WfMuLFDQTG/Fl3JTt3ptBP0GNyNxZthgSz8+bVYz/udQU0Gx9UaG0guvpfKaKlAkEAs+ufKxFhGSk75+B93D8p6LXug568V3XmgbwsBD4+9zzG9K3PKZDaG+8Y0DCrh0wRXcGEn98xKu+6AOU0uomSPwJBAOQI2HMk/dZI1Kl1PklKb8XX2FNtoHq3IsNiP5kTv74cEEzjzDkJY5zM3kgTrWDvs9NtZf+cvG1uX5lCf9Zg1nUCQCBSGoTFGXlIo/9Sn6l6G1A3poI0eMcJYgA6Snn0qKEHZQI9WvKvl87e08lKhPXIH3KFOgryMEXzTKmugxtjbUcCQDrpXHpYy7MAIcUFpXRWV6BeA/JX3NRugCX6n5NwBrLY+CASViyYctPqnTUKXEz9yRXycuTBdyFr0zJmCxfgKQw=
  

  MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBAI7Xh680MTnfYDxwyzSqKMhKWed3UP64YMaDkHgBtgCk3odFjoMcDTDumZqeiC1hVICVFR94blrq1ZhxQnFS+UqhXkPbyzuiPZQVBGaZ42y8brGuFiGJVjlo7Sf6GMc14a0d+bLD0C13faGK7PV0YQ7A1xaIIn/fn/Uk4qpOWEhhAgMBAAECgYBO2ZkT1RrLWIxWMOlrY/bpQWnJhSrXwU3ip2OLa15dkqUoRPQ7WbPKbBusp5CChHTSGfm0CpXYaEOKSBMmXWgwuz767/EEpaJfep3OPmKGD+kGPdA3qDYfTMCGRXSX1J47kjLa9XQX6iBmUMAzvTrLS9lZlXPKDhmU6bNZdODH1QJBAO1I/TIcjq7Fd0lwmXigbCs52suZP6/JEVpy6dSVPbZubCnJY3JbG044TN/2Ve4PzMNhmt367k46COpN6Oh1gAMCQQCaG6S2+NL9HTPD2RYmLKF8mXwcYD20WH2qsEGSVZwZma1CzbiwgY0MCUyXue0T/RabkU+oj0v679qy5AtkuULLAkEAzuliwJveX9CZYFTrvyBEsrzUac3Ml0DB/RlPhaxOEBLiBt4x9bo0aVT21CU+cUUdzRIDtaXmwBgjRg2CF5K+eQJAHAZW5+dMBzeeSElcG8kV/OC0jzx5PCizgazX39KttoIZ3gInSgHlMoEmapknIfFugQ/l2pNkj9e6f7m00LZYDQJBAOBCfnJmeppAA07ws2FzfvR880+rYc1gI95BSKK4ZLMoO2w+4k/NQ15K6MqlqwFNzTJq0HBf1MryUcuuASx0sQs=
  

Public Key:

  MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCO14evNDE532A8cMs0qijISlnnd1D+uGDGg5B4AbYApN6HRY6DHA0w7pmanogtYVSAlRUfeG5a6tWYcUJxUvlKoV5D28s7oj2UFQRmmeNsvG6xrhYhiVY5aO0n+hjHNeGtHfmyw9Atd32hiuz1dGEOwNcWiCJ/35/1JOKqTlhIYQIDAQAB
   

Buyer Accounts:

1. douyufua@alitest.com
2. alipaytest20091@gmail.com

Captcha Code:  8888
Login Password: 111111
Payment Password on Payment Page:  111111

中文文档

Audience and Purpose

This guide is written for application developers who want to integrate Alipay cross-border WAP payment solution. Implementing this solution requires software development skills. You must write code that uses the API request and reply fields to integrate Alipay cross-border WAP payment solution into your existing order management system.

What is the Alipay cross-border WAP payment solution

Alipay (Chinese: 支付宝) is a third-party mobile and online payment platform. Alipay cross-border WAP (Wireless Application Protocol) payment is a solution designed for mobile payment, which gives your buyers a simplified and secure payment experience that keeps them loyal to your website throughout the payment process. Once integrated the Alipay WAP payment service, you should present an Alipay payment button on your page for the consumer to complete the payment and check out.

Why do you need the Alipay cross-border WAP payment solution

• Offer Chinese consumers a familiar payment experience that they are comfortable with.
• Deduct payment amount from the consumer's Alipay account in real-time in CNY and settle the payment to you in a foreign currency.
• Check/download transaction and settlement information conveniently.
• Support 15 currencies for your convenience. You will provide your worldwide customers with such a professional payment experience. For more information about the supported currency, see Supported Currency List.

Customer Support

The AlipayHK system has implemented the White List mechanism, and the partner needs to notify AlipayHK of its public IPs. Then, we will release a username together with password to the partner to test the accessibility and reconciliation file parsing/cron job. If these testings are successful, the partner can push the system to the production.

The settlement zip file contains multiple settlement files and one settlement batch file.

Alternatively, the partner also can manually access the merchant’s dashboard to download the reconciliation and settlement report. However, there will no indicator of the payment APP used by the buyer.

The file naming rule is:

1. Transaction File: $PID_fptrade_$YYYYMMDD.csv;
2. Settlement Zip File: $PID_$YYYYMMDD.zip
3. Settlement Batch File: $PID_settlebatch_$YYYYMMDD.csv;
4. Settlement File: $PID_settle_$YYYYMMDD_$BatchID.csv;

The transaction file contains a list of the following fields:

Record Detail

An example of file content:

The settlement zip file contains one settlement batch file and multiple settlement files.

The settlement batch file contains a list of the following fields:

Record Detail

An example of file content:

The single settlment file contains a list of the following fields:

Record Detail

An example of file content:

Please contact us to obtain SandBox testing info.

Call this interface to register online secondary merchants information into Alipay system. For frequently asked questions about this interface, see About the alipay.overseas.secmerchant.online.maintain API.

The gateway URL:

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

Request Parameters

Sub-parameter

site_infos

Sync Response

The response is in XML format.

Samples

Request succeeds and the registration succeeds.

<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>T</is_success>
<request>
    <param name="secondary_merchant_industry">5935</param>
    <param name="_input_charset">UTF-8</param>
    <param name="sign">8457f906bf89a5e444a6e5c28f8da499</param>
    <param name="site_infos">
        [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]
    </param>
    <param name="secondary_merchant_id">100510000031</param>
    <param name="register_address">No.278, Road YinCheng, Shanghai, China</param>
    <param name="partner">2088131089302823</param>
    <param name="service">alipay.overseas.secmerchant.online.maintain</param>
    <param name="secondary_merchant_name">test1</param>
    <param name="register_country">HK</param>
    <param name="sign_type">MD5</param>
    <param name="timestamp">2018-10-09 16:04:16</param>
    <param name="secondary_merchant_type">INDIVIDUAL</param>
    <param name="registration_no">012345678</param>
    <param name=“representative_name”>Tom Li</param>
    <param name=“representative_id”>123456789 Li</param>
    <param name="settlement_no">2600100000</param>
    <param name="contact_no">+86139xxxx7893 </param>
    <param name="contact_email">tomli@gmail.com </param>
</request>
<response>
    <alipay>
        <result_code>SUCCESS</result_code>
    </alipay>
</response>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>

Request succeeds but the registration fails:

<alipay>
    <is_success>F</is_success>
    <error>PARAM_ILLEGAL</error>
    <sign>ba101b7ffb43afde9ba63c0de335218e</sign>
    <sign_type>MD5</sign_type>
</alipay>

Request fails or the access data are wrong:

<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>F</is_success>
    <error>ILLEGAL_PARTNER</error>
</alipay>

Error Codes

Business Logic Errors

Access Errors

System Errors

When system error occurs, please contact Global Merchant Technical Support .

Change history

The following business flow shows how an Alipay payment integration works. The process involves the customer, the merchant, and Alipay.

For a transaction that has been successfully paid, the customer can request the merchant for refunding as long as the refunding period is still valid, and you can make use of the refunding interface to complete the refunding, as illustrated.

You can query a transaction by sending a query request.

To generate a digital signature, normally a key is required to sign the data. You must prepare the MD5 private key or the RSA/DSA private and public key pair to generate and verify a digital signature.

MD5 sign type

MD5 private key is required for generating and verifying MD5 signatures. The MD5 secret key is the 32-byte string which is composed of English letters and numbers. You can log in to the Global Portal to view the private key:

1. Log in with your user ID.
2. Click My Technical Service and enter your payment password. If you don't know your payment password, please contact Global Merchant Business Support

3. Check your MD5 Key. For example, the following graphic is an example of an MD5 Key:

RSA/DSA sign type

An RSA/DSA key pair contains the private key and the public key. The private key is required for generating the signature, while the public key is used for verifying the signature. The following steps assume that you are using RSA sign type, similar steps applied for generating and uploading DSA key pair.

Many tools can be used to generate the RSA key pair. The following example illustrates the steps to generate the RSA key pair by using OpenSSL.

1. Install OpenSSL
   
   • For linux system, use the following command:

     sudo apt-get install openssl

   • For windows system, download and then install OpenSSL from OpenSSL site.
2. Generate RSA key pair.
   For linux system, use the following command:

   $ 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          
   

   
   For windows system, use the following command:

   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 that, you can see two files under current folder, rsaprivatekey.pem and rsapublickey.pem. The former is the private key and the latter is the public key.

• For Java developers, remove the header, footer, carriage return, and space from the pkcs8 private key output in the console.
• After creating a private key with openssl, if you use JAVA, you need to transform the private key into PKCS8 format; if you use .NET or PHP, no need to transform the private key into PKCS8 format.

The following are the examples of the key pair:

• Standard private key file（PHP,.NET）

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

• Standard private key file in PKCS8 format(Java)

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

• Public key file

  -----BEGIN PUBLIC  KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQWiDVZ7XYxa4CQsZoB3n7bfxLDkeGKjyQPt2FUtm4TWX9OYrd523iw6UUqnQ+Evfw88JgRnhyXadp+vnPKP7unormYQAfsM/CxzrfMoVdtwSiGtIJB4pfyRXjA+KL8nIa2hdQy5nLfgPVGZN4WidfUY/QpkddCVXnZ4bAUaQjXQIDAQAB-----END PUBLIC  KEY-----

Exchange the public key

This flow only applies for the acquirer. If you are an acquirer, you can use this flow to register online secondary merchants information into AlipayHK system.

Deploy/Run in Sandbox

Take JAVA demo code using MD5 signature algorithm as an example. Import the demo code project into your IDE tool, like Eclipse, then run: Click payment button to pay: Login to Alipay: Input payment password to pay: Payment success: Buyer is brought back to the merchant's website after payment according to parameter return_url.

You can integrate the demo code or write your own code and run in Alipay production environment. If you use demo code, change the following settings:

Change the Gateway

1. Change Alipay gateway to production URL in the AlipaySubmit.java file:
   https://intlmapi.alipay.com/gateway.do?

Get the production PID and key

Go to Alipay Merchant Portal and log in with your user ID. Click My Technical Service after login. You can check your PID and MD5 Key.

The MD5 Key can be used when you apply Alipay solutions in your online/offline store. To check this Key, you will need to enter your payment password.

After entering the password, you can get an MD5 Key:

The PID is an identification number that is used frequently when you are using Alipay solutions. This PID is tied to the Email which you used to login merchant portal. You can always check your PID here when you forgot.

The RSA key is not provided on Alipay Merchant Portal and need to be created it by using the OpenSSL tool. After you create the RSA keys, you need to send the RSA public key to overseas_support@service.alibaba.com and Alipay support team will help you upload the key.

Configure the account and key

Change the account and key to your real account and key in the AlipayConfig.java file.

In addition to the API response through the page redirect, the API response might also be sent to the partner asynchronously with the POST method if the merchant set 'notify_url' field in the request with the targeted URL to handle the asynchronous notification. Handling async notification is required for this payment solution.

Alipay would retry the sending asynchronous notification multiple times within a 25-hour window until the partner acknowledges the receipt of the notification by sending a string 'Success' in the response. The merchant needs to respond to avoid the further re-send of the async notification.
When handling the API response through the page redirect and the asynchronous notification, the following aspects should be considered:

• The asynchronous notification might arrive ahead of the page redirect.
• The duplicated asynchronous notifications.

Response Parameters in Async Notifications

Asynchronous Notification Example

https://www.namesilo.com/alipay_ipn.php?notify_id=92c60707dc43a5b2d648b7b4d3c2e1592g&notify_type=trade_status_sync&sign=***&trade_no=2015063000001000080055080394&total_fee=7.99&out_trade_no=9677726c8757aea6d4df81091811b047&currency=HKD&notify_time=2015-06-30 09:56:02&trade_status=TRADE_FINISHED&sign_type=MD5

http://www.namesilo.com/alipay_ipn.php?notify_id=0578bc470961e3b43fb676db616711fd2k&notify_type=trade_status_sync&sign=***&trade_no=2015061700001000100000583330&total_fee=11.00&out_trade_no=2082389608326064&currency=HKD&notify_time=2015-06-17+02%3A37%3A02&trade_status=TRADE_CLOSED&sign_type=RSA

Nofitication trigger condition

Notification Verification

For the interest of system’s healthiness, it is recommended that the partner verifies if the notification is from Alipay.

The partner can only verify the notifications sent within the last 1 minute, and before sending the ‘Success’ acknowledgement back to Alipay.
For example:

https://intlmapi.alipay.com/gateway.do? service=notify_verify&partner=2088101122136241&notify_id=+4465b04e84cb6bacc2bd1b52232c0b8gjg&sign=ciSBXc7gjCfXW8KMBxFiFH2cbMZtFelfTOGKqY2NF7q98RnH3E%2BiF5Cj%2Fu%2Bl8py1D%2FOsE%2FAva1ls8A6Tw1MzhG6ideJSgh4FxWmAjEnlczdfLj%2FqzA6qGzxdKGEXaSDFmTGglOembXUqK8g8ajICD%2BBH7xoxBRY7vtfylEXtojs%3D&sign_type=RSA

When you are dealing with a transaction, you will be in one of the following transaction status:

• WAIT_BUYER_PAY: the system is waiting for the buyer to pay.
• TRADE_FINISHED: means the trade succeeds and refunding is allowed.
• TRADE_CLOSED: means the trade is unpaid or timed out.

Only when your transaction is in the final status of TRADE_FINISHED or TRADE_CLOSED, your system can avoid many problems.

Best practice for you to keep transactions in the final status:

1. Set the time-out value. For example, you can set 3 minutes as the time-out value.
2. Get the payment result with the page redirection caused by the synchronous notification.
3. Confirm the payment result with the asynchronous notification.
4. If no payment result or asynchronous notification is returned, the transaction status must be THE SYSTEM IS CONFIRMING THE PAYMENT RESULT or THE PAYMENT IS WAITING TO BE PAID.
5. Every time the user enters the order system, the query API will be called to confirm the payment result.
6. For all the unpaid transactions over 3 minutes, set the transaction status as TRADE_CLOSED.

The Alipay returned error codes can be divided to the following types:

• Timeout or system error: Mechanisms should be designed in the integration phase to handle this kind of errors. If such error codes appear in production environments, partner’s alarm mechanism should to be triggered, and investigation must be made to help fix the problems.
• Business error codes: Meaning of such error codes should be transformed to messages that the cashiers can easily understand. In addition, the cashiers should be trained to handle these errors or explain the problems to the customers.

Idempotence

Idempotence means that in response to the same requests sent multiple times, Alipay should send back only one unique result.

Alipay checks the idempotence for payments and refunds. See details as below:

• Payments with a same PID: Alipay checks the idempotence of out_trade_no (partner_transaction_id). Transactions with a same out_trade_no are considered as same transactions. Alipay then checks information such as the buyer and amount of the transaction. If the information does not match with that in the Alipay system, errors will be returned. Otherwise, Alipay returns the real status of the transaction.
• Refunds with a same PID: Alipay checks the idempotence of out_trade_no (partner_transaction_id) and partner_refund_id. Refunds with a same out_trade_no AND partner_transaction_id are considered as same transactions. Alipay then checks information such as the amount of the refund. If this information does not match with that in the Alipay system, errors will be returned. Otherwise, Alipay returns the real status of the refund.

Timeout or system error (SYSTEM_ERROR)

Because HTTPS requests depend on network stabilities, timeout might occur on PAY, QUERY, CANCEL and REFUND interface requests. At the same time, Alipay might return SYSTEM_ERROR for internal system problems. In both cases, partners can retry or query to get aligned with the final transaction status in Alipay.

1. For QUERY, CANCEL and REFUND interface:

Retry with the same parameter till get a result. If the retry exceeds the max times allowed, alarms will be triggered to notify the technical support team of the partner to check. If the retry results are always SYSTEM_ERROR, contact Alipay Technical Support for help.

2. For PAY interface:

a) Retry with the same parameter till get a result. If the retry exceeds the max times allowed, alarms will be triggered to notify the technical team of the partner to check. If the retry results are always SYSTEM_ERROR, contact Alipay Technical Support for help.

b) If timeout or SYSTEM_ERROR returned, call the QUERY interface to obtain the status, if QUERY timeout again, call CANCEL to close the transaction.

The following table lists the differences of using method a and method b:

Alipay status	Retry PAY interface	Retry QUERY interface
SYSTEM_ERROR	SYSTEM_ERROR	TRADE_NOT_EXIST
WAIT_BUERY_PAY	UNKNOW	WAIT_BUERY_PAY
TRADE_SUCCESS	TRADE_SUCCESS	TRADE_SUCCESS
TRADE_CLOSED	TRADE_CLOSED	TRADE_CLOSED

Table 1 Differences of using method a and method b

Call this interface to query the registration status of secondary merchants.

The gateway URL:

If you want to use Alipay sandbox to test the integration, see the sandbox handbook for details.

Request Parameters

Sync Response

The response is in XML format.

Business Logic Errors

Response Examples

The request succeeds and the query result is returned:

<?xml version="1.0" encoding="utf-8"?>
<alipay>
    <is_success>T</is_success>
<request>
    <param name="service">alipay.overseas.secmerchant.maintain.queryStatus</param>
    <param name="partner">2088101131367863</param>
    <param name=“_input_charset”>gbk</param>
    <param name="sign_type">MD5</param>
    <param name="sign">2118ac8fad6bc1d9e88a6cd017c18d37</param>
    <param name="timestamp">2019-02-01 08:30:10</param>
    <param name="secondary_merchant_id">MERCHANT_ID_0003</param>
    <param name="payment_method">ONLINE_PAYMENT</param>  
</request>
<response>
    <alipay>
        <secondary_merchant_id>MERCHANT_ID_0003</secondary_merchant_id>
        <status>UNDER_REVIEW</status>
    </alipay>
</response>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>

Failed to get the query result:

<?xml version="1.0" encoding="utf-8"?>
<alipay>
<is_success>F</is_success>
<error>DATA_NOT_EXIST</error>
<sign>744a87f0e3b40e6a8cd8f9705ce61511</sign>
<sign_type>MD5</sign_type>
</alipay>

Change history

1. Identify the parameters to be signed.
   All the parameters in the list of request and response parameters need to be signed except the sign and sign_type. (Sign_type also needs to be signed in some cases in the list of request parameters)
2. Sort the above parameters alphabetically.
   Sort the parameters according to the key value ASCII code of the first character in ascending alphabetical order. For parameters with the same first character, make the sort based on the second character.
3. Create the pre-sign string.
   Combine all the sorted parameters in the format of parameter name = parameter value and link the combinations with the character of &. In this way, you get the pre-sign string.