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.

If you integrate successfully with Alipay payment solution, you will see a merchant checkout page as below:

If the buyer selects Alipay for payment, the following QR code for payment will be shown:

The buyer can log in the payment system with their username and password:

After login, the buyer will see exchange rate, account balance, payment account, and some other information. If the buyer confirms the payment, the payment result will be returned afterwards:

For example, if the payment is successful, a page as below will be returned:

After several seconds, the page is redirected to the merchant homepage according to the value of the return_url parameter.

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:

Buyer can check the exchange rate here. Login to finish the payment:

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

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=USD&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=USD&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

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.

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

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

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

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.

You can obtain the reconciliation files by using APIs, or from Alipay global site or SFTP sites. However, the files obtained by using these channels vary in their names and contents, which is further explained in the following sections.

API

To acquire reconciliation files, first integrate Alipay online payment APIs with your system, and call the following two APIs.

forex_compare_file is for acquiring transaction files.

forex_liquidation_file is for acquiring settlement files.

Alipay global site (global.alipay.com)

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:

SFTP

To obtain your reconciliation files through SFTP, complete the following steps:

1. Apply for an SFTP account

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.

2. Connect to SFTP sites

Download and install Winscp. Use the following settings to log in and obtain files:

• Port: 22
• Host Name: sftp.alipay.com (China) / isftp.alipay.com (U.S.)
• Username and password

Reconciliation files consist of transaction files and settlement files. Settlement files from SFTP and Alipay global site also contain a summary file. Files form API, SFTP and Alipay global site varies in naming convention and contents.

Transaction file

Transaction files contain transaction record of the selected time period.

Depending on where you download the file, the file name might consist of different parts. See the following table for details.

The contents of transaction files that you download from API, website and SFTP are different. See the following table for details:

Settlement file

Settlement files contain the settlement record of the selected time period.

Note:

Settlement summary file

Only settlement files obtained through SFTP or from Alipay global site at Download Files contain a settlement summary file, namely settlebatch file. The name of a settlebatch file contains the following parts:

Settlement file

Settlement files contain the settlement details of the selected time period.

Depending on where you download the file from, the file name might consist of different parts. See the following table for details.

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.

If you need to reconcile the transactions, you can follow the reconciliation flow to start your reconciliation.

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

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

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

Sandbox is an environment where you can mimic the characteristics of the production environment and create simulated responses from all APIs the application relies on before going live. You can make API tests based on your own requirements including making a transaction, cancel, or refund a transaction, and so on.

Before going live in the production environment, it is very helpful to verify whether all API requests and responses are correctly handled, and whether user experiences are as expected. You can test Alipay payment features integrated with your applications in sandbox environment before going live.

To access the Alipay sandbox portal to start the test, you need to make some preparations. See Prerequisites for details.

Alipay merchant account

To test Alipay payment features in sandbox, you must have an Alipay merchant account. If you don’t have one, watch the video below and get yourself an Alipay merchant account.

Create an Alipay merchant account:

1. Go to the Alipay for Business website: https://global.alipay.com
2. In the top-right corner of the homepage, click Sign Up.
3. Enter your email, enter the code displayed, and then click Continue.
4. Follow the instructions to complete the account creation.

Demo code

Use Alipay demo code to start your test in Sandbox. To get the demo code, see Downloading demo code.

Use your merchant account to log in to the Alipay sandbox portal. The Alipay sandbox portal contains the information and tools you need to test in the Alipay sandbox environment, which include the test accounts information and the Alipay sandbox app. If you don’t have the account, see Prerequisites. After you enter the sandbox, an application is created for you automatically. You will need the following related information for the application:

Alipay sandbox gateway

Alipay sandbox test accounts

Alipay sandbox provides you test accounts of both the merchant and buyer. You can use the merchant account to realize application authorization, and you can use the buyer account to make a payment.

Merchant test accounts

See the merchant test account information in the Alipay sandbox portal under Sandbox Accounts > Merchant. To test the Alipay cross-border website payment, use the account information provided under New Cross-border Online Payment(PC/WAP). You can use the login password to login to the Alipay for Business website in the sandbox environment.

Buyer test account

See the buyer test account information in the Alipay sandbox portal under Sandbox Accounts > Buyer. Use the buyer test account to login to the Alipay sandbox app. And you can click Top Up to increase the account balance of the buyer test account.

Create and upload the RSA key

Create an RSA signature key and upload it in the section of cross-border online payment in Sandbox. For more information about creating the RSA key, see Preparing keys.

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://mapi.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 refund solution if the value of the is_sync field is N.

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

http://www.merchant.com/alipay/notify_url.php?sign=327fed8c8d07be26e2790e 216266f5a8¬ify_time=2015-06-16 19:27:27&out_return_no=YNTK20150616 008&return_amount=10.00&sign_type=MD5&refund_status=REFUND_SUCCE SS¬ify_type=refund_status_sync¬ify_id=179ed48796486c67af63836465f 7733m6a&out_trade_no=2332688563037664¤cy=USD

Notification Verification

It is recommended to verify if the notification is from Alipay.

You 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

For more details, please refer to the API document of notify_verify

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.