About This Guide

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.

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.

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:

For example：

• Business requirement：sequentially execute two spilt action

split_fund_info=[{"transIn":"2088101126708402","amount":"0.10","currency":"USD","desc":"  Split _test1"},{"transIn":"2088101126707869","amount":"0.10","currency":"USD","desc":"SampleInsuranceFee=10usd|RelevantTax=10usd|DeliveryFee=10usd|AnyOtherFees=10usd"}]

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.

Refund split detail parameter format is JSON, include follow parameters:

Example：

• Business requirement：sequentially execute two spilt refund actions

Format Structure ：

split_fund_info=[{"transOut":"2088101126708402",  "amount":"0.10", "currency":"USD",  "desc":"test1"},   {" transOut  ":"2088101126708402", "amount":"0.30",  "currency":"USD", "desc":"test2"}]

Watch the video below to have a quick overview of Alipay sandbox portal, and the preparations that are required before you access the portal.

Creating an Alipay merchant account

Complete the following steps to 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.

Alipay sandbox portal

Sign in to the Alipay sandbox portal

What is a mock service

The mock service provides simulations of different payment results to get you familiarized with the possible payment scenarios beforehand. With the simulated scenarios provided in a sandbox environment, you can test failed payment processes with different types of responses and learn to handle exception scenarios. The mock service aims to optimize your exception and error handling abilities and therefore, improve your Alipay integration quality with lower integration cost and better user experience.

Previously, many exception scenarios are difficult or even impossible to be simulated. With the mock service, you can run test cases for all the scenarios and see whether the response is as designed. Besides the default mock rules, you can also customize mock rules for exception scenarios based on your business requirements. By now, the mock service supports the process of payment, cancel, refund, and query.

How to use a mock service

Before using a mock service, you need to have an Alipay merchant account. See Creating an Alipay merchant account

Watch the following video to have a quick overview of how to use a Mock service:

1. Log in your sandbox and go to the mock service part. By now, the mock service supports the following 4 APIs:

• alipay.acquire.oversears.spot.pay
• alipay.acquire.cancel
• alipay.acquire.overseas.spot.refund
• alipay.acquire.overseas.query

2. Configure mock rules by specifying mock API requests and corresponding responses.
Two types of mock rules exist for each API: default rules and custom rules.

• Default rules apply for all the sandbox test accounts. You don't need to make any configuration to make the default rules work.
• Custom rules are rules where you can specify conditions and expected responses based on your business requirements.

3. Send an API request that matches the specified mock rules. You will receive a corresponding mock response and then process it. For example, you can send an alipay.acquire.overseas.spot.pay request with the following mock rule. See the below sample code and a corresponding mock response for details. The default mock rule:

Samples

Sample request:

http://mapi.alipaydev.com/gateway.do?client_info=%7B%22client_ip%22%3A%2210.20.30.40%22%7D&identity_code_type=barcode&memo=nomemo&trans_amount=9901&sign_type=MD5&trans_name=xxxzgl&buyer_identity_code=288888888888888888&partner_trans_id=8567745904202380&password=SJV88po0XvIptqWGM4rxP5EQ&sendFormat=normal¤cy=USD&sign=6030aea30c96e01c6e5c709c9f66a7df&agreement_info=%7B%22agreement_no%22%3A%22123%22%7D&trans_currency=USD&biz_product=OVERSEAS_MBARCODE_PAY&service=alipay.acquire.overseas.spot.pay&format_type=xml&quantity=1&partner=2088621880270354

Sample response:

<?xml version="1.0" encoding="GBK"?>
<alipay>
     <is_success>T</is_success>
     <request>
        <param name="client_info">{"client_ip":"10.20.30.40"}</param>
        <param name="quantity">1</param>
        <param name="biz_product">OVERSEAS_MBARCODE_PAY</param>
        <param name="identity_code_type">barcode</param>
        <param name="sign">6030aea30c96e01c6e5c709c9f66a7df</param>
        <param name="memo">nomemo</param>
        <param name="trans_name">xxxzgl</param>
        <param name="trans_amount">9901</param>
        <param name="sendFormat">normal</param>
        <param name="partner_trans_id">8567745904202380</param>
        <param name="password">SJV88po0XvIptqWGM4rxP5EQ</param>
        <param name="format_type">xml</param>
        <param name="trans_currency">USD</param>
        <param name="partner">2088621880270354</param>
        <param name="agreement_info">{"agreement_no":"123"}</param>
        <param name="service">alipay.acquire.overseas.spot.pay</param>
        <param name="currency">USD</param>
        <param name="sign_type">MD5</param>
        <param name="buyer_identity_code">288888888888888888</param>
     </request>
     <response>
     	<alipay>
     		<error>SYSTEM_ERROR</error>
     		<result_code>FAILED</result_code>
     	</alipay>
     </response>
     <sign>d0117413cdf375ab667329892ab7f890</sign>
     <sign_type>MD5</sign_type>
</alipay>

Alipay provide reconciliation files to merchant using cross-border online payment and cross-border in-store payment services. Merchants can fetch the reconciliation files to view details of their balance. Reconciliation files consist of settlement files and transaction files. The settlement file of a T day is only generated if there is any settlement on that day. If you download settlement files from SFTP sites or Alipay global site, a summary file of the settlement is also available.

Settlement time

• Balance settlement day: T + 1 (T is the transaction day)
• Settlement end time: 23:59:59 Beijing (GMT + 8)
• The transaction is settled once per settlement cycle.

Transaction file generation time

• The transaction file is generated at as early as 00:00 on T + 1.
• A transaction file contains all transaction details of the corresponding T day, including records of transactions and refunds.
• The transaction file is generated once per day.

Settlement file generation time

• The settlement file is generated during 09:00 to 11:00 on S + 1. (S is the settlement day)
• A settlement file contains all transaction details within the settlement period.
• The settlement file is generated once per settlement cycle.

Note:

• Reconciliation files during 00:00 Friday to 23:59 Sunday are generated next Monday.
• Reconciliation files during holidays and the day before are generated on the first working day after the holidays.

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

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 gateway URL:

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

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

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