1
- [Introduction](./1) - [Payment Flow and User Experience](./3) - [Quick Start](./37) - [Pay Flow](./38) - [Refund Flow](./39) - [Query Flow](./40) - [Reconciliation Flow](./41) - [Secondary Merchant Maintenance Flow](./42) - [Integration](./43) - [Preparing Keys](./44) - [Testing in Sandbox](./45) - [Prerequisites](./46) - [Deploying in Sandbox](./47) - [Running Demo Code in Sandbox](./48) - [Downloading Demo Code](./49) - [Calling APIs](./50) - [Signing the Request and Creating the Request URL](./51) - [Processing Notifications](./52) - [Verifying Asynchronous Notification](./53) - [Verifying Synchronous Notification](./54) - [Going Live](./55) - [API List](./6) - [Create_forex_trade_wap](./6) - [Request Parameters](./6) - [Sync Response](./7) - [Samples](./8) - [Async Notification](./9) - [Error Codes](./10) - [Forex_refund](./11) - [Request Parameters](./11#Request) - [Sync Response](./11#Response) - [Samples](./11#Samples) - [Error Codes](./12#Errors) - [Async Notification](./57) - [Single_trade_query](./13) - [Request Parameters](./13#QueryRequest) - [Sync Response](./13#QueryResponse) - [Samples](./13#QuerySamples) - [Error Codes](./14#Errors) - [Forex_compare_file](./15) - [Request Parameters](./15#Forex_compare_file_Request) - [Sync Response](./15#Forex_compare_file_Response) - [Samples](./15#Forex_compare_file_Samples) - [Error Codes](./16) - [Forex_liquidation_file](./17) - [Request Parameters](./17#Forex_liquidation_file_Request) - [Sync Response](./17#Forex_liquidation_file_Response) - [Samples](./17#Forex_liquidation_file_Samples) - [Error Codes](./18) - [Forex_rate_file](./19) - [Request Parameters](./19#Forex_rate_file_Request) - [Sync Response](./19#Forex_rate_file_Response) - [Samples](./19#Forex_rate_file_Samples) - [Error Codes](./20) - [alipay.overseas.secmerchant.online.maintain](./36) - [Request Parameters](./36#request) - [Sync Response](./36#sync) - [Samples](./36#samples) - [Error Codes](./36#error) - [Digital Signature](./56) - [ Preparing Keys](./44) - [Signing the Request](./51) - [Verifying the Signature of Asynchronous Response](./53) - [Verifying the Signature of Synchronous Response](./54) - [Reconciliation Files](./33) - [About Reconciliation Files](./33) - [Obtaining Reconciliation Files](./34) - [API](./34#API) - [Alipay global site](./34#Global) - [SFTP](./34#SFTP) - [Reconciliation File Contents](./35) - [Transaction file](./35#TransactionFile) - [Settlement file](./35#SettlementFile) - [FAQ](/help/online)
New Cross-border WAP Payment

Introduction

中文文档

Audience and Purpose

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

What is the Alipay cross-border WAP payment solution

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

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

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

Customer Support

For technical questions, please contact Global Merchant Technical Support.
For non-technical questions, like how to sign up with Alipay, please contact Global Merchant Business Support .

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);
  
Rearrange parameters in the data set alphabetically
And connect rearranged parameters with &:

_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

This is the pre-sign string.

  • Parameters without a value, can be excluded from sign;
  • Charset in sign must be consistent with the charset used previously
  • If _input_charset is passed, it also shall be signed.
  • According to HTTP protocol, special character like &,@ needs to do URL encoding, therefore the request receiver can get correct value. In this situation, pre-sign string shall be the original value instead of encoded one. For example: calling a particular API need to sign the parameter email, the pre-sign string shall be email=test@msn.com, rather than email=test%40msn.com.

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.

After the partner receives the pre-sign string during requesting, the private key should be appended to the pre-sign string to generate the new string. Then this new string would be calculated with the MD5 signature algorithm by the MD5 signature function. Thus, the result 32-byte string is the signature result string. (the value is given to parameter “sign”)  

After receiving the pre-sign string during responding from Alipay system, the next step is the same as the procedure of Sign for request. When the 32-byte signature result string is generated, it should be verified whether the value is equal to the value of the parameter “sign”. If equal, the verification would be passed.

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.

After the partner receives the pre-sign string during requesting, the partner private key and the pre-sign string are used in the RSA signature algorithm by the RSA signature function to get the result string. (the value is given to parameter “sign”)

After receiving the pre-sign string during responding from Alipay system, the Alipay public key, the pre-sign string and the parameter “sign” are used in the RSA signature asymmetric algorithm by the RSA signature function to accomplish the signature verification.

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.

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

Language MD5 RSA

JAVA

download

download

PHP

download

download

.Net

download

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:
  2. https://mapi.alipay.com/gateway.do? in AlipaySubmit.java

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

Parameter

Type (length in bytes)

Description

Example

Basic Parameter

sign_type

String

Signature method. The following are supported. Must be uppercase.
DSA, RSA, and MD5.

RSA

sign

String

Signature value.

e5815a4556db338ed237f7d3fd222184

Business Parameter

trade_status

String(32)

The status of Alipay's transaction.
Partner must verify the status be 'TRADE_FINISHED'.
Fixed value:
TRADE_FINISHED

TRADE_FINISHED

trade_no

String(64)

Alipay Transaction ID.

Max length is 64 and min length is 16.

2015070800001000100080029361

out_trade_no

String(64)

out_trade_no passed in by the merchant in the request

2525759240575424

currency

String(3)

Currency code.

USD

total_fee

Number(8,2)

The amount of the payment

11.00

  • After successfully finish the payment, the buyer will see an Alipay trade-sucess page, this page will stay for a few seconds and automatically redirect to the page partner named. (return_url)
  • Parameters in this page can be acquired with GET method, like request.QueryString("out_trade_no")、$_GET['out_trade_no'].
  • Redirection only occurs once right after the buyer finished the payment.
  • In this mode, Alipay will not invoke partner page initiatively, rather using redirecting function of programming to make the user page redirect to the partner page.
  • Not only on sever, this mode can also be tested on local computer.
  • Return URL has a time limit, it would expire after one minute, which will cause verification failure.
  • When partner is configuring return_url, it is wrong to add custom parameters. For example

    Wrong:http://www.alipay.com/alipay/return_url.php?xx=11
    Right:http://www.alipay.com/alipay/return_url.php

  • Due to Alipay will try to validate the return_url, so do not set it on local host. For instance:
    Wrong:
      http://localhost/alipay/return_url.php;
      http://localhost:80/alipay/return_url.php
    Right:
      http://www.test.com/alipay/return_url.php
      http://121.1.1.255/alipay/return_url.php
  • Along with the business growth, Alipay may add new parameters (existing parameters will not change). When doing notification verification, Merchants MUST use all parameters returned from Alipay.

Request Example

https://openapi.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

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:

Response Parameters in Async Notifications

Parameter

Type (length in bytes)

Description

Example

Basic Parameter

sign_type

String

Signature method. The following are supported. Must be uppercase.
DSA, RSA, and MD5.

RSA

sign

String

Signature value.

e5815a4556db338ed237f7d3fd222184

Business Parameter

notify_type

String

Notification type, value: trade_status_sync.

trade_status_sync

notify_id

String(34)

The ID for a particular notification.  It can be used by the partner system to verify the notification

92c60707dc43a5b2d648b7b4d3c2e1592g

notify_time

Timestamp

Time (Alipay’s time zone): YYYY-MM-DD hh:mm:ss

2015-06-30 09:56:02

trade_status

String(32)

One of following two values:
TRADE_FINISHED
TRADE_CLOSED

TRADE_FINISHED

trade_no

String(64)

Alipay Transaction ID.

Max length is 64 and min length is 16.

2015070800001000100080029361

out_trade_no

String(64)

out_trade_no passed in by the merchant in the request

2525759240575424

currency

String(3)

Currency code.

USD

total_fee

Number(8,2)

The amount of the payment

11.00

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


Trigger condition name

Description on trigger condition

Note

TRADE_FINISHED

Trade successfully

true (trigger nofitication)

WAIT_BUYER_PAY

Trade creation

false (does not trigger nofitication)

TRADE_CLOSED

Trade closed

true (trigger nofitication)

  • Make sure the Notification Page (notify_url) is absolutely blank, without space, html tag, or any error message threw from the program system.
  • Parameters in this page can be acquired with GET method, like request.Form("out_trade_no"), $_POST['out_trade_no'].
  • This response will be used, if Alipay initiatively notify.
  • Alipay will notify when there is a real transaction in Alipay system and the status of that transaction has changed.
  • Interaction between servers, unlike interaction between websites which is visible, is usually not displayable.
  • When the first time a transaction status is changed, not only page would redirect to partner website but also would Alipay notify partner system
  • After program is executed, the page must print “success” (without quote). If not, Alipay server would keep re-sending notification, until over 24 hour 22 minutes Generally, there are 8 notifications within 25 hours (Frequency: 2m,10m,15m,1h,2h,6h,15h)
  • After program is executed, there would not be redirection operation on the page, for Alipay would not recognize a “success” string, so it would be regarded as an error, and Alipay system would keep sending notification.
  • Cookies and session would be invalid on this page, which means these data would not be captured.
  • The configuration and testing of this system must be on a server, via internet
  • The main effect of this mood is to present transaction lost, so even redirection failed, the order in partner system still update.
  • As long as the partner receives the sever asynchronous response and prints “success”, the parameter notify_id would be invalid. It means when Alipay sends the same asynchronous notification (include the re-sending notifications because of no “success”), the parameter notify_id would not change.
  • Along with the business growth, Alipay may add new parameters (existing parameters will not change). When doing notification verification, Merchants MUST use all parameters (except sign and sign_type) returned from Alipay.

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 more details, please refer to the API document of notify_verify.

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.

Returned Result Description
FOREX_MERCHANT_NOT_SUPPORT_THIS_CURRENCY Cannot support this currency
ILLEGAL_SECURITY_PROFILE Cannot support this kind of encryption
REPEAT_OUT_TRADE_NO out_trade_no parameter is duplicated
ILLEGAL_CURRENCY Currency parameter is incorrect
ILLEGAL_TIMEOUT_RULE Timeout_rule parameter is incorrect
SYSTEM_EXCEPTION Alipay system error
ILLEGAL_ARGUMENT Incorrect parameter

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.

Returned Result Description
ILLEGAL_SIGN Illegal signature
ILLEGAL_SERVICE Service Parameter is incorrect
ILLEGAL_PARTNER Incorrect Partner ID
ILLEGAL_SIGN_TYPE Signature is of wrong type.
ILLEGAL_PARTNER_EXTERFACE Service is not activated for this account
ILLEGAL_DYN_MD5_KEY Dynamic key information is incorrect
ILLEGAL_ENCRYPT Encryption is incorrect.
ILLEGAL_USER User ID is incorrect.
ILLEGAL_EXTERFACE Interface configuration is incorrect.
ILLEGAL_AGENT Agency ID is incorrect.
HAS_NO_PRIVILEGE Has no right to visit.
INVALID_CHARACTER_SET The character set is invalid.

System Errors

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

Returned result Description
SYSTEM_ERROR Alipay system error
SESSION_TIMEOUT Session timeout
ILLEGAL_TARGET_SERVICE Wrong  target service
ILLEGAL_ACCESS_SWITCH_SYSTEM Merchant is not allowed to visit system of this type.
EXTERFACE_IS_CLOSED The interface has been closed.

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

The gateway URL:

Environment HTTPS request URL
Production environment https://intlmapi.alipay.com/gateway.do
Test environment https://mapi.alipaydev.com/gateway.do

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

If you are still using the previous sandbox gateway https://openapi.alipaydev.com, please use the https://mapi.alipaydev.com/gateway.do gateway instead. This gateway adjustment is caused by a system difference between the Alipay international sandbox test environment and the Alipay domestic sandbox test environment.

Request Parameters

Parameter Type (length in bytes) Description Optional Example
Basic Parameter
service String Service Name N forex_refund
partner String(16) Partner ID.
Composed of 16 digits beginning with 2088.
N 2088001159940003
_input_charset String The charset with which the request data is encoded;
UTF-8 is supported
N UTF-8
sign_type String Signature method. The following are supported. Must be uppercase.
DSA, RSA, and MD5.
N RSA
sign String Signature value. N e5815a4556db338ed237f7d3fd222184
notify_url String(200) The page HTTP path specified in the merchant website for receiving the asynchronous notification sent from the Alipay server. Y http://www.test.com/alipay/notify_url.php
Business Parameter
out_return_no String(64) The unique refund ID for refund request. N 205485121225
out_trade_no String(64) The payment ID for the original payment txn. N 205485121223
return_amount Number(8,2) The amount to refund in settlement currency. The value is between 0.01 – 1000000(max 2 digits after the decimal). Must use one of the two parameters: return_amount and return_rmb_amount Y 100.30
return_rmb_amount Number(15) Use this field to refund in CNY. The value is between 0.01 – 1000000(max 2 digits after the decimal). Must use one of the two parameters: return_amount and return_rmb_amount Y 10.20
currency String(10) Currency code. Even when return_rmb_amount is not null, currency is still foreign currency, not CNY N USD
gmt_return String(14) Refund Transaction time. YYYYMMDDHHMMSS, Beijing Time N  
reason String(100) Reason for the refund. Y out of supply
product_code String(32) NEW_OVERSEAS_SELLER N NEW_OVERSEAS_SELLER  
is_sync String(1) The refund request is processed synchronously or asynchronously.

Value: Y or N.

Default value is N, which means an asynchronous response from Alipay is returned to the merchant if the merchant has set the value of the notify_url field when sending the refund request. If the value is set as Y, it means only a synchronous response is returned to the merchant.

Y N
split_fund_info String(1 600) Split info, JSON format, more detail see Refund Split Detail Info Y [{"transOut":"2088101137935255","amount":"0.10","currency":"USD","desc":"test1"},{"transOut":"2088101126707869","amount":"0.10","currency":"USD","desc":"test2"}]  
  • The total refund amount cannot exceed the original payment amount.
  • The refund must be initiated within a certain time period after the payment, which is specified in the contract. Usually, a 365-day period is specified.

Sync Response

The response is in XML format


Parameter
Type (length in bytes) Description Optional Example
is_success String Status of the API call, ‘T’ or ‘F’ N T
error String Error message Y REPEATED_REFUNDMENT_REQUEST

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

Returned result

Description

REFUNDMENT_VALID_DATE_EXCEED

Could not refund after the specified refund timeframe.

SYSTEM_EXCEPTION

System exception

ILLEGAL_ARGUMENT

Illegal argument

REPEATED_REFUNDMENT_REQUEST

Duplicated refund request

RETURN_AMOUNT_EXCEED

Refund amount is over the payment amount

CURRENCY_NOT_SAME

Different currency from the payment currency

PURCHASE_TRADE_NOT_EXIST

The payment transaction does not exist

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.

Returned result

Description

SYSTEM_EXCEPTION

Alipay system error

ILLEGAL_ARGUMENT

Incorrect parameter

ILLEGAL_SIGN

Illegal signature

ILLEGAL_SERVICE

Service Parameter is incorrect

ILLEGAL_PARTNER

Incorrect Partner ID

ILLEGAL_SIGN_TYPE

Signature is of wrong type.

ILLEGAL_PARTNER_EXTERFACE

Service is not activated for this account

ILLEGAL_DYN_MD5_KEY

Dynamic key information is incorrect

ILLEGAL_ENCRYPT

Encryption is incorrect.

ILLEGAL_USER

User ID is incorrect.

ILLEGAL_EXTERFACE

Interface configuration is incorrect.

ILLEGAL_AGENT

Agency ID is incorrect.

HAS_NO_PRIVILEGE

Has no right to visit.

INVALID_CHARACTER_SET

The character set is invalid.

System Errors

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

Returned result

Description

SYSTEM_ERROR

Alipay system error

SESSION_TIMEOUT

Session timeout

ILLEGAL_TARGET_SERVICE

Wrong  target service

ILLEGAL_ACCESS_SWITCH_SYSTEM

Merchant is not allowed to visit system of this type.

EXTERFACE_IS_CLOSED

The interface has been closed.

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:

Environment HTTPS request URL
Production environment https://intlmapi.alipay.com/gateway.do
Test environment https://mapi.alipaydev.com/gateway.do

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

If you are still using the previous sandbox gateway https://openapi.alipaydev.com, please use the https://mapi.alipaydev.com/gateway.do gateway instead. This gateway adjustment is caused by a system difference between the Alipay international sandbox test environment and the Alipay domestic sandbox test environment.

Request Parameters

Parameter

Type(length)

Description

Optional

Example

Basic Parameters

service

String

API name

N

single_trade_query

partner

String(16)

A unique partner ID to identify a contracted Alipay Account.
A 16 digit number starts with 2088

N

2088101011913539

_input_charset

String

The charset on partner website like utf-8、gbk、gb2312 etc.

N

gbk

sign_type

String

Signature method. The value can be MD5, RSA, or RSA2. RSA2 is preferred. Uppercase must be used.

N

MD5

sign

String

Sign value

N

7d314d22efba4f336fb187697793b9d2

Business Parameters

trade_no

String(64)

The unique trade number in Alipay system.
Length from 16 to 64.

Y

2008102303210710

out_trade_no

String(64)

A unique number to identify a transaction in partner system

Y

6843192280647118

Note:
This API recieve https request only;

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

Parameters

Type(length)

Description

Optional

Example

Basic Parameters

is_success

String

Indicate whether the API has been called successfully, it does not indicate the result of business

  • T for True
  • F for False

N

T

sign_type

String

DSA, RSA or MD5, capital letter

N

MD5

sign

String

Sign value

N

7d314d22efba4f336fb187697793b9d2

error

String

Error information when query fails.

Y

TRADE_NOT_EXIST

Business Parameters

buyer_email

String

Buyer Alipay Account

N

tstable01@alipay.com

buyer_id

String

A unique buyer ID to identify a contracted Alipay Account.

N

2088002007018955

trade_status

String

The status of this transaction can be:

  • TRADE_FINISHED
  •  WAIT_BUYER_PAY
  • TRADE_CLOSED
  • N

    TRADE_FINISHED

    is_total_fee_adjust

    String

    Is total fee adjusted

    • T for True
    • F for False

    N

    F

    out_trade_no

    String

    A unique number to identify a transaction in partner system

    Y

    6843192280647118

    trade_no

    String

    The unique trade number in Alipay system.Length from 16 to 64. To query by Alipay trade number is preferred w.r.t the accuracy of the result.

    N

    2008102303210710

    subject

    String

    Goods name/trade name/order name/order key words etc.

    N

    Apple

    flag_trade_locked

    String

    • 1 for trade is locked.
    • 0 for trade is not locked.

    N

    0

    body

    String

    Detail description about a transaction, if there are multiple items involved, accumulate together into body.

    N

    Gundam MKII,Miniature Bracelet

    gmt_create

    Date

    Time when transaction is created. Format: yyyy-MM-dd HH:mm:ss

    N

    2008-10-22 20:49:31

    seller_email

    String

    Partner Alipay Account

    N

    tianc001@alipay.com

    seller_id

    String

    A unique partner ID to identify a contracted Alipay Account. A 16 digit number starts with 2088

    N

    2088002007018966

    total_fee

    Number

    The total amount of the transaction for the escrow payment. Range: 0.01 to 1000000.00, accurate to 2 digits after the decimal point. Unit: RMB.

    N

    100

    price

    Number

    Unit:RMB Yuan. Value Range [0.01,100000000.00],accurate to two decimal places.

    Y

    10.00

    quantity

    Number

    Quantity of goods.

    Y

    1

    coupon_discount

    String

    Coupon discount.

    Y

    1

    use_coupon

    String(1)

    Whether coupon is used in transaction.

    • T for True
    • F for False

    Y

    T

    discount

    Number

    Discount

    Y

    0.00

    gmt_last_modified_time

    Date

    Time when the total fee is modified latest. Format: yyyy-MM-dd HH:mm:ss

    Y

    2008-01-08 20:39:30

    gmt_payment

    Date

    Time when transaction is paid by user. Format: yyyy-MM-dd HH:mm:ss

    Y

    2008-10-22 20:49:50

    to_buyer_fee

    String

    Accumulative refunded fee.

    Y

    1.00

    to_seller_fee

    String

    Accumulative fee paid to seller.

    Y

    20.00

    payment_type

    String

    Please refer to “Payment Type”

    Y

    1

    operator_role

    String

    • B:Buyer
    • S:Seller

    Y

    B

    Samples

    Request Sample

    https://mapi.alipay.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>intltest059@service.alipay.com</buyer_email>
    <buyer_id>2088122921745555</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

    Error Codes

    Descriptions

    TRADE_NOT_EXIST

    Trade not exist. out_trade_no or Alipay trade_no is incorrect

    ILLEGAL_SIGN

    Illegal signature.

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect.

    ILLEGAL_ENCRYPT

    Encryption is incorrect.

    ILLEGAL_ARGUMENT

    Parameter is incorrect.

    ILLEGAL_SERVICE

    Service parameter is incorrect.

    ILLEGAL_USER

    User ID is incorrect.

    ILLEGAL_PARTNER

    Partner ID is incorrect.

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect.

    ILLEGAL_PARTNER_EXTERFACE

    Partner’s interface information is incorrect.

    ILLEGAL_SECURITY_PROFILE

    Matching private key configuration has not been found.

    ILLEGAL_AGENT

    Agency ID is incorrect.

    ILLEGAL_SIGN_TYPE

    The signature type is incorrect.

    ILLEGAL_CHARSET

    The character set is illegal.

    ILLEGAL_CLIENT_IP

    Client IP address is illegal

    HAS_NO_PRIVILEGE

    Has no right to visit.

    ILLEGAL_DIGEST_TYPE

    Digest type is illegal

    ILLEGAL_DIGEST

    Digest is illegal

    ILLEGAL_FILE_FORMAT

    File format is illegal

    ILLEGAL_ENCODING

    Encoding type is illegal

    EXTERFACE_IS_CLOSED

    API is closed

    ILLEGAL_REQUEST_REFERER

    Anti-phishing checks illegal request

    ILLEGAL_ANTI_PHISHING_KEY

    Anti-phishing checks illegal timeframe

    ANTI_PHISHING_KEY_TIMEOUT

    Anti-phishing checks timeframe timeout

    ILLEGAL_EXTER_INVOKE_IP

    IP Anti-phishing checks illegal IP

    System Errors

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

    Returned result

    Description

    SYSTEM_ERROR

    Alipay system failed to process the request due to temporary internal glitch.

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong  target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type.

    EXTERFACE_IS_CLOSED

    The interface has been closed.

    Payment Type

    Type

    Description

    01

    Coupon Fee Pre-payment

    02

    Coupon Fee Payment

    03

    Reminding Payment

    04

    Automatic Sending Goods

    1

    Merchandise

    2

    Service Purchase

    3

    Online Auction

    4

    Donation

    5

    Post Fee Compensation

    6

    Bonus

    7

    Funds Purchase

    8

    Air Ticket

    9

    Go Dutch

    10

    Group Purchase

    11

    Electronic Ticket

    12

    Lottery Ticket

    13

    Auction

    14

    Mobile Payment

    15

    Flowers & Gifts

    16

    Agent Electronic Ticket

    17

    Party Membership Dues

    18

    Foreign Exchange

    19

    Automatic Charge

    20

    Refund of Overseas Payment

    21

    Refund of Instant Payment

    22

    Business Deposit

    24

    Cash Gift

    25

    Rent

    26

    Motopay

    23

    Shopping Chart

    27

    Escrow Payment of Group Purchase

    Transaction Status

    Status

    Description

    WAIT_BUYER_PAY

    Transaction awaits user payment.

    WAIT_SELLER_SEND_GOODS

    Transaction awaits seller sending goods.

    WAIT_BUYER_CONFIRM_GOODS

    Transaction awaits buyer confirming goods.

    TRADE_FINISHED

    Transaction is finished successfully.

    TRADE_CLOSED

    Transaction is closed during processing (finished, not successfully)

    WAIT_SYS_CONFIRM_PAY

    Transaction awaits system conforming payment, please do not send goods.

    WAIT_SYS_PAY_SELLER

    Buyer confirm goods, transaction awaits system paying to seller.

    TRADE_REFUSE

    Transaction refused.

    TRADE_REFUSE_DEALING

    Transaction refusing.

    TRADE_CANCEL

    Transaction canceled.

    TRADE_PENDING

    Pending Transaction.

    TRADE_SUCCESS

    Transaction complete, and available for refund

    BUYER_PRE_AUTH

    Buyer has paid. (IVR Payment)

    COD_WAIT_SELLER_SEND_GOODS

    Transaction awaits seller sending goods. (COD)

    COD_WAIT_BUYER_PAY

    Transaction awaits user payment. (COD)

    COD_WAIT_SYS_PAY_SELLER

    Buyer confirm goods, transaction awaits system paying to seller. (COD)

    Additional Trade Status

    Status

    Description

    ZHIFUBAO_CONFIRM

    Custom Service confirms goods for buyer.

    ZHIFUBAO_CANCEL_FP

    Custom Service cancels instant payment for buyer.

    DAEMON_CONFIRM_CANCEL_PRE_AUTH

    Expiration Program cancels pre authorization.

    DAEMON_CONFIRM_CLOSE

    Expiration Program cancels transaction as buyer did not pay.

    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:

    Environment HTTPS request URL
    Production environment https://intlmapi.alipay.com/gateway.do
    Test environment https://mapi.alipaydev.com/gateway.do

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

    If you are still using the previous sandbox gateway https://openapi.alipaydev.com, please use the https://mapi.alipaydev.com/gateway.do gateway instead. This gateway adjustment is caused by a system difference between the Alipay international sandbox test environment and the Alipay domestic sandbox test environment.

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    forex_compare_file

    partner

    String(16)

    Partner ID.
    Composed of 16 digits beginning with 2088.

    N

    2088001159940003

    sign_type

    String

    Signature method. The following are supported. Must be uppercase.
    DSA, RSA, and MD5.

    N

    RSA

    sign

    String

    Signature value.

    N

    e5815a4556db338ed237f7d3fd222184

    Business Parameter

    start_date

    String

    The start date of the reconciliation period, formatted as YYYYMMDD

    N

     

    end_date

    String

    The end date of the reconciliation period, formatted as   YYYYMMDD

    N

     

    • The starting and end dates should be within a 10-day interval.
    • There is a time delay such that the transactions in the current day will not be listed in the return of this API call.
    • Currently the interface only supports .TXT file to be downloaded. The file contains no headings for data fields. Each data field is separated by “|”, following the order given in the specification.

    Sync Response

    Response format

    The responses could be in different formats for different use cases

    File Format for the Transaction Report file in the Response

    Order

    Field name

    Type

    Description

    1

    Partner transaction ID

    String(64)

    The  Unique transaction ID passed by the merchants in the payment transaction

    2

    Amount

    Number(8,2)

    The amount of fund in foreign currency.

    3

    Currency

    String(10)

    Abbreviated currency names.

    4

    Payment Time

    String(14)

    YYYYMMDDHHMMSS
    Empty if the status being “failed” or “waiting”.

    5

    Settlement Time

    String(14)

    YYYYMMDDHHMMSS
    Empty if unliquidated

    6

    Transaction type

    String(1)

    Normal transaction: P
    Refund transaction: R

    7

    Service charge

    Number(8,2)

    The amount of service charge.

    8

    Status

    String(1)

    Normal transaction:
    P : Payment made         
    L: Liquidated
    Refund transaction :
    F: Failed   
    L: Liquidated

    9

    Remark

    String(50)

    An optional field. If the transaction is refund, the time of the refund request should be added into the remark field in YYYYMMDDHHMMSS format.

    10

    Split foreign currency amount

    Number(8,2)

    This trade's split foreigh currency amount or this refund's split refund foreigh currency amount.

    11

    Split RMB amount

    Number(8,2)

    This trade's split RMB amount or this refund's split refund RMB amount.


    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

    Returned result

    Description

    Over limit balance amount record

    Exceed the maximum entries : 100000

    System exception

    System exception

    Merchant ID incorrect

    Incorrect partner ID

    Finish date not ahead of today

    The end date could not be the future time

    No balance amount data in the period

    Do not have any trade during the period

    Over 10 days to date period

    Over 10 day limit for the request time span

    Finish date ahead of begin date

    The end date needs to be later than the begin date

    Illegal date period

    Null in date field

    Date format incorrect YYYYMMDD

    Incorrect format of the date ,YYYYMMDD

    Internet connected exception ,please try later

    Network exception

    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.

    Returned result

    Description

    SYSTEM_EXCEPTION

    Alipay system error

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_SIGN_TYPE

    Signature is of wrong type.

    ILLEGAL_PARTNER_EXTERFACE

    Service is not activated for this account

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect

    ILLEGAL_ENCRYPT

    Encryption is incorrect.

    ILLEGAL_USER

    User ID is incorrect.

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect.

    ILLEGAL_AGENT

    Agency ID is incorrect.

    HAS_NO_PRIVILEGE

    Has no right to visit.

    INVALID_CHARACTER_SET

    The character set is invalid.

    System Errors

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

    Returned result

    Description

    SYSTEM_ERROR

    Alipay system error

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong  target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type.

    EXTERFACE_IS_CLOSED

    The interface has been closed.

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

    The gateway URL:

    Environment HTTPS request URL
    Production environment https://intlmapi.alipay.com/gateway.do
    Test environment https://mapi.alipaydev.com/gateway.do

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

    If you are still using the previous sandbox gateway https://openapi.alipaydev.com, please use the https://mapi.alipaydev.com/gateway.do gateway instead. This gateway adjustment is caused by a system difference between the Alipay international sandbox test environment and the Alipay domestic sandbox test environment.

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    forex_liquidation_file

    partner

    String(16)

    Partner ID.
    Composed of 16 digits beginning with 2088.

    N

    2088001159940003

    sign_type

    String

    Signature method. The following are supported. Must be uppercase.
    DSA, RSA, and MD5.

    N

    RSA

    sign

    String

    Signature value.

    N

    e5815a4556db338ed237f7d3fd222184

    Business Parameter

    start_date

    String

    The start date of the reconciliation period, formatted as YYYYMMDD

    N

     

    end_date

    String

    The end date of the reconciliation period, formatted as?? YYYYMMDD

    N

     

    • The starting and end dates should be provided within a 10-day interval.
    • There is a time delay such that the transactions in the current day will not be listed in the return of this API call.
    • Currently the interface only supports .TXT file to be downloaded. The file contains no headings for data fields. Each data field is separated by “|”, following the order given in the specification.

    Sync Response

    Response format

    The responses could be in different formats for different use cases

    File Format for the Settlement file in the Response

    Order

    Field name

    Type

    Description

    1

    Partner transaction ID

    String(64)

    The? Unique transaction ID passed by the merchants in the payment transaction

    2

    Amount

    Number(8,2)

    The amount of fund in foreign currency.

    3

    Currency

    String(10)

    Abbreviated currency names.

    4

    Payment Time

    String(14)

    YYYYMMDDHHMMSS
    Empty if the status being “failed” or “waiting”.

    5

    Settlement Time

    String(14)

    YYYYMMDDHHMMSS
    Empty if unliquidated

    6

    Transaction type

    String(1)

    Normal transaction: P
    Refund transaction: R

    7

    Service charge

    Number(8,2)

    The amount of service charge.

    8

    Status

    String(1)

    Normal transaction:
    L: Liquidated
    Refund transaction:
    L: Liquidated

    9

    Remark

    String(50)

    An optional field. If the transaction is refund, the time of the refund request should be added into the remark field in YYYYMMDDHHMMSS format.

    10

    Split foreign currency amount

    Number(8,2)

    This trade's split foreigh currency amount or this refund's split refund foreigh currency amount.

    11

    Split RMB amount

    Number(8,2)

    This trade's split RMB amount or this refund's split refund RMB amount.

    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

    Returned result

    Description

    Over limit balance amount record

    Exceed the maximum entries: 100000

    System exception

    System exception

    Merchant ID incorrect

    Incorrect partner ID

    Finish date not ahead of today

    The end date could not be the future time

    No balance amount data in the period

    Do not have any trade during the period

    Over 10 days to date period

    Over 10 day limit for the request time span

    Finish date ahead of begin date

    The end date needs to be later than the begin date

    Illegal date period

    Null in date field

    Date format incorrect YYYYMMDD

    Incorrect format of the date ,YYYYMMDD

    Internet connected exception ,please try later

    Network exception

    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.

    Returned result

    Description

    SYSTEM_EXCEPTION

    Alipay system error

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_SIGN_TYPE

    Signature is of wrong type.

    ILLEGAL_PARTNER_EXTERFACE

    Service is not activated for this account

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect

    ILLEGAL_ENCRYPT

    Encryption is incorrect.

    ILLEGAL_USER

    User ID is incorrect.

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect.

    ILLEGAL_AGENT

    Agency ID is incorrect.

    HAS_NO_PRIVILEGE

    Has no right to visit.

    INVALID_CHARACTER_SET

    The character set is invalid.

    System Errors

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

    Returned result

    Description

    SYSTEM_ERROR

    Alipay system error

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong  target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type.

    EXTERFACE_IS_CLOSED

    The interface has been closed.

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

  • The exchange rate changes once between 9:00 and 11:00 GMT+8 everyday.
  • The maximum number of queries is 100 each day.
  • The gateway URL:

    Environment HTTPS request URL
    Production environment https://intlmapi.alipay.com/gateway.do
    Test environment https://mapi.alipaydev.com/gateway.do

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

    If you are still using the previous sandbox gateway https://openapi.alipaydev.com, please use the https://mapi.alipaydev.com/gateway.do gateway instead. This gateway adjustment is caused by a system difference between the Alipay international sandbox test environment and the Alipay domestic sandbox test environment.

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    forex_rate_file

    partner

    String(16)

    Partner ID.
    Composed of 16 digits beginning with 2088.

    N

    2088001159940003

    sign_type

    String

    Signature method. The following are supported. Must be uppercase.
    DSA, RSA, and MD5.

    N

    RSA

    sign

    String

    Signature value.

    N

    e5815a4556db338ed237f7d3fd222184

    • Currently the interface only supports .txt file to be downloaded.
    • The file contains no headings for data fields, and each data field is separated by “|”
    • The data is just for current day’s exchange rate.

    Sync Response

    Response format

    The responses could be in different formats for different use cases

    File Format for the Transaction Report file in the Response

    Order

    Field name

    Type

    Description

    1

    Date

    String(8)

    Rate releasing date: YYYYMMDD

    2

    Time

    String(6)

    Rate releasing time: HHMMSS

    3

    Currency

    String(3)

    Abbreviated currency names.

    4

    Rate

    String(10)

     

    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

    Returned result

    Description

    System exception

    Alipay system error

    Merchant ID incorrect

    Invalid partner ID

    File empty

    Null content of the file

    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.

    Returned result Description

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_SIGN_TYPE

    Signature is of wrong type.

    ILLEGAL_PARTNER_EXTERFACE

    Service is not activated for this account

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect

    ILLEGAL_ENCRYPT

    Encryption is incorrect.

    ILLEGAL_USER

    User ID is incorrect.

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect.

    ILLEGAL_AGENT

    Agency ID is incorrect.

    HAS_NO_PRIVILEGE

    Has no right to visit.

    INVALID_CHARACTER_SET

    The character set is invalid.

    System Errors

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

    Returned result Description

    SYSTEM_ERROR

    Alipay system error

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong  target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type.

    EXTERFACE_IS_CLOSED

    The interface has been closed.

    The gateway URL:

    Environment HTTPS request URL
    Production environment https://intlmapi.alipay.com/gateway.do
    Test environment https://mapi.alipaydev.com/gateway.do

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

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    notify_verify

    partner

    String(16)

    Partner ID.
    Composed of 16 digits beginning with 2088.

    N

    2088001159940003

    Business Parameter

    notify_id

    String(34)

    The ID of Alipay system’s notification.

    N

    • The proper event sequence to verify async notification is as the following
      • Receive the notification, do not reply ‘Success’ yet. Otherwise the reply will impact the system behavior. (Alipay will return false for all the inquiries whose notification has been replied with “success”).
      • Verify the notify id through calling this API.
        • If the input parameter is invalid, Alipay will return “Invalid”
        • If the notification is sent by Alipay and the inquiry occurs with the pre-defined time frame, Alipay will return “True”.
        • If the notification is not sent by Alipay, Alipay will return “False”.
        • If the inquiry occurs out of the pre-defined time frame, Alipay will return “False”.
        • If the merchant has replied any of the notification with the response of “true”, Alipay will return “False”.
      • Once verified, the merchant should reply “Success” to the asynchronous notification. If not, process with the proper business logic.

    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

    Returned result Description

    SYSTEM_EXCEPTION

    Alipay system error

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_SIGN_TYPE

    Signature is of wrong type.

    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.

    Returned result Description

    SYSTEM_EXCEPTION

    Alipay system error

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_SIGN_TYPE

    Signature is of wrong type.

    ILLEGAL_PARTNER_EXTERFACE

    Service is not activated for this account

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect

    ILLEGAL_ENCRYPT

    Encryption is incorrect.

    ILLEGAL_USER

    User ID is incorrect.

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect.

    ILLEGAL_AGENT

    Agency ID is incorrect.

    HAS_NO_PRIVILEGE

    Has no right to visit.

    INVALID_CHARACTER_SET

    The character set is invalid.

    System Errors

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

    Returned result Description

    SYSTEM_ERROR

    Alipay system error

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong  target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type.

    EXTERFACE_IS_CLOSED

    The interface has been closed.

    OpenSSL installation

    RSA key pair generation

    For Java developers, we need to remove the header, footer, <CR>, and space from the pkcs8 private key output in the console. For.NET and PHP developer, there is no need for the pkcs8 operation.

    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.

    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
      

    RSA
    Private Key:
    
      MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBAKQ5oPb0bAuwPqeBm01hBCiyAEg6q5hLqaHgVOZliuBsY49H9zupOhvCTPFMqV4IheggNqx1C3b2zik5egn/QdY3Y1SDKnWblVMRpdSxmasR1G6Jh6s2JPrgwAYMAnm+800otolXHIAP8Sryz9z9Kti9rtSNejSef/PEndsWTiCbAgMBAAECgYEAiD1q5RUXAYdgIxSpo0MF8UDibQmHS5wRiUKTDGRXFyG0YqyAVZVpqJfDvzcrFuCZPl5jHSUosrPDin2tWdfSZC6Hn7w+L89EwoekThUkSI6J6GPHSTiGssscBjN0RDjGH87KUmGsoDkgdwBFyG5krJOdCNjlWXnjSag6LFEusLkCQQDpqv4pqGKTSR70NjIFDeXIk8WfMuLFDQTG/Fl3JTt3ptBP0GNyNxZthgSz8+bVYz/udQU0Gx9UaG0guvpfKaKlAkEAs+ufKxFhGSk75+B93D8p6LXug568V3XmgbwsBD4+9zzG9K3PKZDaG+8Y0DCrh0wRXcGEn98xKu+6AOU0uomSPwJBAOQI2HMk/dZI1Kl1PklKb8XX2FNtoHq3IsNiP5kTv74cEEzjzDkJY5zM3kgTrWDvs9NtZf+cvG1uX5lCf9Zg1nUCQCBSGoTFGXlIo/9Sn6l6G1A3poI0eMcJYgA6Snn0qKEHZQI9WvKvl87e08lKhPXIH3KFOgryMEXzTKmugxtjbUcCQDrpXHpYy7MAIcUFpXRWV6BeA/JX3NRugCX6n5NwBrLY+CASViyYctPqnTUKXEz9yRXycuTBdyFr0zJmCxfgKQw=
      
    Private Key in pkcs8 format for Java:
    
      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

    Abbreviation

    Currency

    Decimal Number

    AUD

    Australian Dollar

    2

    CAD

    Canadian Dollar

    2

    CHF

    Confederation Helvetica Franc

    2

    DKK

    Danish Krone

    2

    EUR

    Euro

    2

    GBP

    British Sterling

    2

    HKD

    Hong Kong Dollar

    2

    JPY

    Japanese Yen

    0

    KRW

    Korean Won

    0

    NOK

    Norwegian Krone

    2

    NZD

    New Zealand Dollar

    2

    SEK

    Swedish Krona

    2

    SGD

    Singapore Dollar

    2

    THB

    Thai Baht

    2

    USD

    U.S. Dollar

    2

    Parameter

    Type(length in bytes)

    Description

    Optional

    Example

    transIn

    String

    Alipay userID that Alipay account for deposit. Alipay userID that composed of 16 digits beginning with 2088.

    N

    2088101126708402

    amount

    String

    Split Amount. The format must be correct to the currency!

    N

    0.10

    currency

    String

    Split currency. If parameter (total_fee) was used, the split currency must be foreign currency and the same with settlement currency!
    If parameter (rmb_fee) was used, the split currency must be ‘CNY’!

    The parameter (total_fee and rmb_fee ) are mutual exclusive.

    N

    USD

    desc

    String

    Split discretion

    Y

     

    For example

    Format Structure :
    split_fund_info=[{"transIn":"2088101126708402","amount":"0.10","currency":"USD","desc":"  Split _test1"},{"transIn":"2088101126707869","amount":"0.10","currency":"USD","desc":"Split_test2"}]
    • You can own at most 10 domestic split accounts.
    • You must own a domestic split account that has contracted successfully with Alipay. The domestic split account need to be linked with the global primary account. To check whether the link is successfully built, contact Global Merchant Business Support.

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

    Parameter

    Type (Byte length)

    Description

    Optional

    Example

    transOut

    String

    Alipay userID that Alipay account for transfer refund fee . Alipay userID that composed of 16 digits beginning with 2088.

    N

    2088101126708402

    amount

    String

    Split Amount. The format must be correct to the currency!

    N

    0.10

    currency

    String

    Split currency .The currency must be same with refund currency!
    If parameter (total_fee) was used, the split currency must be foreign currency and the same with settlement currency!
    If parameter (rmb_fee) was used, the split currency must be ‘CNY’!

    The parameter (total_fee and rmb_fee ) are mutual exclusive.

    N

    USD

    desc

    String

    Split discretion

    Y

    Refund split test1

    Example

    Format Structure :

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

    Refund splitting does not need to follow exactly the payment splitting. Just ensure that the total refund amount is equal to the total payment amount. For example, ¥9 of the total payment of ¥10 was allocated to the primary account, ¥1 to the split account. When performing a refund, you can return ¥5 through the primary account, ¥5 through the split account.

    Record Detail

     No.

    Field

    Type(Byte)

    Description

    1

    Partner_transaction_id

    String(64)

    The unique transaction ID specified by the partner. If the id is duplicated with an earlier transaction’s out_trade_no, the payment will fail with a error message indicating that it is the duplicated payment. It is equal to “out_trade_no” in the payment request when the transaction type is 'P'.

    2

    Transaction_id

    String(64)

    Alipay Transaction ID.Max length is 64 and min length is 16.

    3

    Amount

    Number(8,2)

    The amount foreign currency given.

    4

    Rmb_amount

    Number(8,2)

    The amount RMB currency given.

    5

    Fee

    Number(8,2)

    Commission fee in foreign currency

    6

    Distribute_amount

    String(8,2)

    This trade's split foreign currency amount or this refund's split refund foreign currency amount.

    7

    Distribute_rmb_amount

    String(8,2)

    This trade's split RMB amount or this refund's split refund RMB amount.

    8

    Settlement

    String(8,2)

    The amount of foreign settlement currency

    9

    Rmb_settlement

    String(8,2)

    The amount of RMB settlement currency

    10

    Currency

    String(10)

    The settlement currency code the merchant specifies in the contract.

    11

    Rate

    String(8,6)

    The exchange rate.

    12

    Payment_time

    String(19)

    The time of transaction;

    Format: YYYY-MM-DD HH:MM:SS

    13

    Settlement_time

    String(19)

    The time of settlement;

    Format: YYYY-MM-DD HH:MM:SS

    14

    Type

    String(1)

    Normal transaction: P

    Refund transaction: R

    15

    Status

    String(1)

    Normal transaction:

    L: Liquidated

    Refund transaction:

    L: Liquidated

    16

    Remarks

    String(256)

    Remarks

    An example of file content:

    Partner_transaction_id|Transaction_id|Amount|Rmb_amount|Fee|Distribute_amount|Distribute_rmb_amount|Settlement|Rmb_settlement|Currency|Rate|Payment_time|Settlement_time|Type|Status|Remarks

    GDR-EP-5542324-20170922110026136|2017092221001000000009179004|0.01|0.01|0.0|0.0|0.0|0.01|0.01|HKD|0.84682000|2017-09-22 11:04:13|2017-09-28 15:36:00|P|L|GDR-EP-5542324-20170922110026136

    GDR-EP-5542324-20170922110729211|2017092221001000000009204295|0.01|0.01|0.0|0.0|0.0|0.01|0.01|HKD|0.84682000|2017-09-22 11:11:05|2017-09-28 15:36:00|P|L|GDR-EP-5542324-20170922110729211

     

    Record Detail

     No.

    Field

    Type(Byte)

    Description

    1

    Partner_transaction_id

    String(64)

    The unique transaction ID specified by the partner. If the id is duplicated with an earlier transaction’s out_trade_no, the payment will fail with a error message indicating that it is the duplicated payment. It is equal to “out_trade_no” in the payment request when the transaction type is 'P'.

    2

    Transaction_id

    String(64)

    Alipay Transaction ID.Max length is 64 and min length is 16.

    3

    Amount

    Number(8,2)

    The amount foreign currency given.

    4

    Rmb_amount

    Number(8,2)

    The amount RMB currency given.

    5

    Fee

    Number(8,2)

    Commission fee in foreign currency

    6

    Distribute_amount

    String(8,2)

    This trade's split foreign currency amount or this refund's split refund foreign currency amount.

    7

    Distribute_rmb_amount

    String(8,2)

    This trade's split RMB amount or this refund's split refund RMB amount.

    8

    Settlement

    String(8,2)

    The amount of foreign settlement currency

    9

    Rmb_settlement

    String(8,2)

    The amount of RMB settlement currency

    10

    Currency

    String(10)

    The settlement currency code the merchant specifies in the contract.

    11

    Rate

    String(8,6)

    The exchange rate.

    12

    Payment_time

    String(19)

    The time of transaction;

    Format: YYYY-MM-DD HH:MM:SS

    13

    Settlement_time

    String(19)

    The time of settlement;

    Format: YYYY-MM-DD HH:MM:SS

    14

    Type

    String(1)

    Normal transaction: P

    Refund transaction: R

    15

    Status

    String(1)

    Normal transaction:

    P: Payment made

    L: Liquidated

    Refund transaction:

    F: Failed

    L: Liquidated

    16

    Remarks

    String(256)

    Remarks

    An example of file content:

    Partner_transaction_id|Transaction_id|Amount|Rmb_amount|Fee|Distribute_amount|Distribute_rmb_amount|Settlement|Rmb_settlement|Currency|Rate|Payment_time|Settlement_time|Type|Status|Remarks

    GDR-EP-5729068-20170927105445022|2017092721001003000000578434|2899.05|2473.73|34.79|0.0|0.0|2864.26|2444.04|HKD|0.85329000|2017-09-27 10:57:23||P|P|GDR-EP-5729068-20170927105445022

    FOREXREFUND_2017092700641633|2017092721001003720000000258|555.0|473.58|6.66|0.0|0.0|548.34|467.9|HKD|0.85329000|2017-09-27 21:37:08||R|P|GDR-EP-5727442-20170927144456087

     

    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

    Transaction file generation time

    Settlement file generation time

    Note:

    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 AlipayMy Transaction to view and download your transaction files and settlement files. You can also download the files at the Download Files tab.

    Watch the video to learn the procedure:

    Files can only be downloaded after the file is generated.

    SFTP

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

    1. Apply for an SFTP account
    2. 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.

    3. Connect to SFTP sites
    4. 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
    • SFTP accounts that are not used within 90 days will be closed.
    • Files older than 7 days on the SFTP server might be deleted. It is suggested to download the files within 3 days. If the file you need is deleted, contact Global Merchant Technical Support.

    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.

    Partner ID

    Date

    File Type

    File Suffix

    Sample

    API

    A unique ID assigned by Alipay

    YYYYMMDD + a 6-digit random number

    /

    .txt

    2088021017666931_20180531143440.txt

    Website

    A unique ID assigned by Alipay

    YYYYMMDD, YYYYMM, or YYYYMMDD + a 6-digit random number

    /

    .csv, .txt, or .xls

    2088611221573217_20180621151516.xls

    SFTP

    A unique ID assigned by Alipay

    YYYYMMDD

    A fixed value: "transaction"

    .csv

    2088721149955614_fptrade_20180823.csv

    A transaction file might contain the following fields:

    NO.

    Field Name

    Description

    1

    Partner_transaction_id

    A unique transaction ID specified by the partner. It is the same with out_trade_no in the payment request or out_return_no in refund request.

    2

    Amount

    Transaction amount in foreign currency

    3

    Rmb_amount

    Transaction amount in CNY

    4

    Currency

    Currency

    5

    Fee

    Service fee in foreign currency

    6

    Rate

    Foreign exchange rate

    7

    Payment_time

    Payment time

    8

    Settlement_time

    Settlement time

    9

    Type

    Transaction type

    10

    Status

    Status.
    For transactions, P is paid, L is liquidated.
    For refunds, W is pending, F is failed.

    11

    Original_partner_transaction_ID

    The original partner transaction ID. It is the same with the out_trade_no in the payment request.
    Note: This field is not a default one. If you want to add this filed, contact Alipay Overseas Support to configure.

    12

    Transaction_ID

    A unique transaction ID specified by Alipay.
    Note: This field is not a default one. If you want to add this filed, contact Alipay Overseas Support to configure.

    13

    Distribute_amount

    The split foreign currency amount of a trade or refund

    14

    Distribute_rmb_amount

    The split CNY amount of a trade or refund

    15

    Remarks

    Remarks

    16

    Settlement

    Settlement amount in foreign currency

    17

    Rmb_settlement

    Settlement amount in CNY

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

    NO.

    Field Name

    SFTP

    API

    Global Site Online

    Global Site Download

    1

    Partner_transaction_id

    Yes

    Yes

    Yes

    Yes

    2

    Amount

    Yes

    Yes

    Yes

    Yes

    3

    Rmb_amount

    Yes

    /

    Yes

    Yes

    4

    Currency

    Yes

    Yes

    Yes

    Yes

    5

    Fee

    Yes

    Yes

    Yes

    Yes

    6

    Rate

    Yes

    /

    Yes

    Yes

    7

    Payment_time

    Yes

    Yes

    Yes

    Yes

    8

    Settlement_time

    Yes

    Yes

    Yes

    Yes

    9

    Type

    Yes

    Yes

    Yes

    Yes

    10

    Status

    Yes

    Yes

    Yes

    Yes

    11

    Original_partner_transaction_ID

    Yes

    /

    /

    /

    12

    Transaction_ID

    Yes

    /

    /

    /

    13

    Distribute_amount

    Yes

    Yes

    Yes

    Yes

    14

    Distribute_rmb_amount

    Yes

    Yes

    Yes

    Yes

    15

    Remarks

    Yes

    Yes

    Yes

    Yes

    16

    Settlement

    Yes

    /

    /

    Yes

    17

    Rmb_settlement

    Yes

    /

    /

    Yes

    Settlement file

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

    Note:

    The settlement files you download from Alipay global site and SFTP are compressed into a .zip file. The .zip file contains the settlement summary file and the settlement file. The naming convention of the .zip file is <PID>_<date>.<file_suffix>, for example, 2088021******931_20180508.zip.

    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:

    Partner ID

    File Type

    Date

    File Suffix

    Sample

    A unique ID assigned by Alipay

    A fixed value: "settlebatch"

    YYYYMMDD or YYYYMM

    .csv

    2088021******931_settlebatch_20180531.csv

    A settlebatch file might contain the following fields:

    NO.

    Field Name

    Description

    1

    settle_batch_no

    An internal serial number of the file in Alipay system

    2

    settle_date

    Settlement time

    3

    Amount

    Transaction amount in foreign currency

    4

    Fee

    Service fee in foreign currency

    5

    Settlement

    Settlement amount in foreign currency

    6

    Currency

    Currency

    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.

    Partner ID

    File Type

    Date

    System Assigned ID

    File Suffix

    Sample

    API

    A unique ID assigned by Alipay

    /

    YYYYMMDD + a 6-digit random number

    /

    .txt

    2088021017666931_20180531143440.txt

    Alipay global site

    A unique ID assigned by Alipay

    A fixed value: "settle"

    YYYYMMDD, YYYYMM, or YYYYMMDD + a 6-digit random number

    A unique ID assigned to each settlement file by Alipay

    .csv, .txt, or .xls

    2088721631012256_settle_20171106_50002017080100032007000005107441.csv

    SFTP

    A unique ID assigned by Alipay

    A fixed value: "settle"

    YYYYMMDD

    A unique ID assigned to each settlement file by Alipay

    .csv

    2088721631012256_settle_20171106_50002017080100032007000005107441.csv

    A settlement file might contain the following fields:

    NO.

    Field Name

    Description

    1

    Partner_transaction_id

    The unique transaction ID specified by the partner. It is equal to “out_trade_no” in the payment request or “out_return_no” in the refund request.

    2

    Transaction_ID

    A unique transaction ID assigned by Alipay.
    Note: This field is not a default one. If you want to add this filed, contact Alipay Overseas Support to configure.

    3

    Original_partner_transaction_ID

    The original partner transaction ID. It is the same with the out_trade_no in the payment request.
    Note: This field is not a default one. If you want to add this filed, contact Alipay Overseas Support to configure.

    4

    Amount

    Transaction amount in foreign currency

    5

    Rmb_amount

    Transaction amount in CNY

    6

    Currency

    Currency

    7

    Fee

    Service fee in foreign currency

    8

    Rate

    Foreign exchange rate

    9

    Payment_time

    Payment time

    10

    Settlement_time

    Settlement time

    11

    Type

    Transaction type

    12

    Status

    Transaction status

    13

    Distribute_amount

    The split foreign currency amount of a trade or refund

    14

    Distribute_rmb_amount

    The split CNY amount of a trade or refund

    15

    Remarks

    Remarks

    16

    Settlement

    Settlement amount in foreign currency

    17

    Rmb_settlement

    Settlement amount in CNY

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

    NO.

    Field Name

    SFTP

    API

    Global Site Download

    1

    Partner_transaction_id

    Yes

    Yes

    Yes

    2

    Transaction_ID

    Yes

    /

    /

    3

    Amount

    Yes

    /

    Yes

    4

    Rmb_amount

    Yes

    /

    Yes

    5

    Fee

    Yes

    Yes

    Yes

    6

    Distribute_amount

    Yes

    Yes

    /

    7

    Distribute_rmb_amount

    Yes

    /

    /

    8

    Settlement

    Yes

    Yes

    Yes

    9

    Rmb_settlement

    Yes

    /

    Yes

    10

    Currency

    Yes

    Yes

    Yes

    11

    Rate

    Yes

    Yes

    Yes

    12

    Payment_time

    Yes

    Yes

    Yes

    13

    Settlement_time

    Yes

    Yes

    Yes

    14

    Type

    Yes

    Yes

    Yes

    15

    Status

    Yes

    Yes

    Yes

    16

    Remarks

    Yes

    Yes

    Yes

    17

    Original_partner_transaction_ID

    Yes

    /

    /

    Call this interface to register online secondary merchants information into Alipay system.

    The gateway URL:

    Environment HTTPS request URL
    Production environment https://intlmapi.alipay.com/gateway.do
    Test environment https://mapi.alipaydev.com/gateway.do

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

    If you are still using the previous sandbox gateway https://openapi.alipaydev.com, please use the https://mapi.alipaydev.com/gateway.do gateway instead. This gateway adjustment is caused by a system difference between the Alipay international sandbox test environment and the Alipay domestic sandbox test environment.

    Request Parameters

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    service

    String

    Service Name

    N

    alipay.overseas.secmerchant.online.maintain

    partner

    String(16)

    A unique partner ID to identify a contracted Alipay Account.

    A 16 digit number starts with 2088.

    N

    2088101142878662

    _input_charset

    String

    The charset on partner website, such as utf-8, gbk, gb2312 etc.

    N

    gbk

    sign_type

    String

    DSA, RSA, or MD5, capital letter

    N

    MD5

    sign

    String

    See Digital Signature.

    N

    2118ac8fad6bc1d9e88a6cd017c18d37

    timestamp

    String

    The time when the merchant server sends request, in GMT + 8, format: yyyy-MM-dd HH:mm:ss.

    By default, the request expires in 30 minutes.

    N

    2012-12-21 17:11:16

    Business Parameter

    secondary_merchant_name

    String(64)

    A name is shown in the Alipay Wallet and the reconciliation file to identify a secondary merchant.

    N

    secMerchantName

    secondary_merchant_id

    String(64)

    A unique ID assigned by the partner to identify a secondary merchant. The ID can contain letters, numbers, and underscores.

    N

    63472327348

    secondary_merchant_industry

    String(4)

    Business category code of the secondary merchant. See MCC list.

    N

    MCC list.

    register_country

    String(2)

    A 2-letter code defined in ISO 3166. For more details about the 2-letter country code, see ISO 3166.

    N

    HK

    register_address

    String(256)

    Registered address of the secondary merchant

    Y

    HANGZHOU

    site_infos

    String

    This field is in JSON format and can contain up to 5 website URLs or app download URLs. See site_infos for details.

    URLs in this field cannot be updated incrementally. To add or remove URLs, re-pass the value again.

    N

    Secondary merchant website URL or app download URL. Format: [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"},

    {"site_type":"APP","site_url":"https://alipay.com","site_name":"websit"}]

    Sub-parameter

    site_infos

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    site_type

    String

    Site type. Website URL must be WEB, and app download URL must be APP. Use uppercase.

    N

    WEB

    site_url

    String(256)

    Site URL.

  • When site_type is WEB, pass the URL in this format: http/https + SLD + TLD, for example, https://www.alipay.com.
  • When site_type is APP, pass the APP download URL starting with http/https, for example, https://itunes.apple.com/cn/app/id333206289.
  • N

    https://www.alipay.com

    site_name

    String(512)

    Site name

    N

    xx Store

    Some parameters of String type have no length limit and the system will not check their length.

    Sync Response

    The response is in XML format.

    Parameter

    Type (length in bytes)

    Description

    Optional

    Example

    Basic Parameter

    is_success

    String

    Request succeeds or not. Successful request does not mean the business request is accepted and processed successfully.

  • T means success
  • F means failure
  • N

    T

    sign_type

    String

    The value can be one of DSA, RSA, or MD5. Uppercase must be used.

    Y

    MD5

    sign

    String

    See Signature Algorithms.

    Y

    3afc92ac4708425ab74ecb2c4e58ef56

    error

    String

  • If the request succeeds, this parameter does not exist.
  • When a request fails, the value of this parameter is the error code. See Access Errors and System Errors for details.
  • Y

    PARAM_ILLEGAL

    The synchronous response may have more parameters due to the upgrade on the Alipay server side. You can ignore parameters that are not included in this API document.

    Samples

    Request Examples

    String to be signed

    partner=2018283223743743&secendary_merchant_name=merchantname &secendary_merchant_id=23647324&sign=2118ac8fad6bc1d9e88a6cd017c18d37&secondary_merchant_industry= 4039&_input_charset=GBK&register_address=HANGZHOU&service=alipay.overseas.secmerchant.online.maintain& amp;timestamp=1438432738473843&site_infos= [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]

    Generated URL

    http://mapi.alipay.com/gateway.do?_input_charset=UTF-8&service=alipay.overseas.secmerchant.online.maintain&partner=20881332189403823&timestamp=2018-10-09 16:04:16&secondary_merchant_name=test1&secondary_merchant_id=100510000031&secondary_merchant_industry=5935&register_country=HK&register_address=HANGZHOU&site_infos= [{"site_type":"WEB","site_url":"https://alipay.com","site_name":"websit"}]&sign=8457f906bf89a5e444a6e5c28f8da499&sign_type=MD5

    The sample is for reference only. Alipay gateway is https://mapi.alipay.com/gateway.do?.

    Response Examples

    Request succeeds and the registration is successful:

    
    <?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">HANGZHOU</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>
    </request>
    <response>
        <alipay>
            <result_code>SUCCESS</result_code>
        </alipay>
    </response>
    </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

    Returned result

    Description

    MCC_CAN_NOT_MODIFY

    The MCC passed in cannot match the original MCC. Please ensure that the passed MCC is the original MCC.

    REGISTER_COUNTRY_FORBIDDEN

    For anti-money laundering reasons, the country or region in register_country cannot be registered.

    PARAM_ILLEGAL

    The parameter is illegal. The parameter is too long, parameter format is wrong, or a required parameter is not passed. Please check and rectify the parameter according to the API document.

    SYSTEM_ERROR

    Alipay system error

    Access Errors

    Returned result

    Description

    ILLEGAL_SIGN

    Illegal signature

    ILLEGAL_DYN_MD5_KEY

    Dynamic key information is incorrect

    ILLEGAL_ENCRYPT

    Encryption is incorrect

    ILLEGAL_ARGUMENT

    Incorrect parameter

    ILLEGAL_SERVICE

    Service Parameter is incorrect

    ILLEGAL_USER

    User ID is incorrect

    ILLEGAL_PARTNER

    Incorrect Partner ID

    ILLEGAL_EXTERFACE

    Interface configuration is incorrect

    ILLEGAL_PARTNER_EXTERFACE

    Partner's interface information is incorrect

    ILLEGAL_SECURITY_PROFILE

    Matching private key configuration is not found

    ILLEGAL_AGENT

    Agency ID is incorrect

    ILLEGAL_SIGN_TYPE

    The signature type is incorrect

    ILLEGAL_CHARSET

    The character set is illegal

    HAS_NO_PRIVILEGE

    Has no right to visit

    INVALID_CHARACTER_SET

    The character set is invalid

    System Errors

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

    Returned result

    Description

    SYSTEM_ERROR

    Alipay system error

    SESSION_TIMEOUT

    Session timeout

    ILLEGAL_TARGET_SERVICE

    Wrong target service

    ILLEGAL_ACCESS_SWITCH_SYSTEM

    Merchant is not allowed to visit system of this type

    EXTERFACE_IS_CLOSED

    The interface is closed

    The following integration flow shows the process of using Alipay payment solution. For more details about integration, see Integration.

    1. Before you start integration, ensure that you completed the registration and other steps in the following graphic:
      1

      Registration

      Sign up with your email address and confirm to activate.

      2

      Qualification

      Provide your company information and upload certificate documents for the first time application.

      3

      Application

      Select an Alipay service product to apply.

      4

      Integration

      Integrate Alipay APIs to add Alipay services on your web and mobile site and in your app.

    2. You can also use the following business flows to increase your understanding of Alipay APIs:

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

    The payment service name is: create_forex_trade.

    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.

    1. The refunding service name is: Forex_refund.
    2. The refund API is applicable as long as the refunding period has not expired yet.
    3. The refunding of a transaction can be full or partial. The refunding amount can respectively be the same as or less than the original transaction amount that was paid. Furthermore, for a transaction, multiple refunding requests are allowed if the sum of the amount of the multiple refunding requests is less than or equal to the original transaction amount. .

    You can query a transaction by sending a query request to Alipay.

    The query service name is: single_trade_query.

    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.

    The secondary merchant maintenance service name is: alipay.overseas.secmerchant.online.maintain.

    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.

    Generating the private/public 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.

    Notes:

    The following are the examples of the key pair:

    Exchange the public key

    You need to exchange your public key with Alipay. Contact Global Merchant Technical Support and provide your PID and public key information. Alipay will then make configurations accordingly, and provide you Alipay 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

    Use the Alipay sandbox gateway for testing. The URL of the sandbox gateway is:
    https://mapi.alipaydev.com/gateway.do?

    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.

    If you call an API, Alipay server returns an asynchronous notification, a synchronous notification, or both. The asynchronous notification is in the format of notifyURL. The synchronous notification can be either in the format of returnURL or XML. The following table shows which kind of notification is returned for a specific API call:

    API notifyURL (Async) XML (Sync) returnURL (Sync)

    Create_forex_trade

    Forex_refund

    Single_Trade_Query

    alipay.overseas.secmerchant.online.maintain

    Forex_compare_file

    Forex_liquidation_file

    Forex_rate_file

    After receiving a notification, you need to verify the authenticity of the signature to ensure the data contained in the notification is originated from Alipay without being modified during the transmission. Only after verifying the content, you can trust the received notification and use the data contained in the notification in your own system for further process.

    • After the transaction succeeds, you might receive both asynchronous and synchronous responses. It is recommended to process the asynchronous notification. You don't need to verify both of the asynchronous notification and synchronous notification.
    • Verification of the asynchronous notification involves the notify_verify method to check the sender of the notification; verification of the synchronous notification doesn't involve the notify_verify method.

    For more information about different types of notifications and the verification of their signatures, see:

    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

    Parameter

    Type (length in bytes)

    Description

    Example

    Basic Parameter

    notify_type

    String

    The notification type

    trade_status_sync

    notify_time

    Date

    The time that the notification was sent

    2009-08-12 11:08:32

    notify_id

    String

    The notification ID

    70fec0c2730b275286 65af4517c27b95

    sign_type

    String

    Signature method. The following are supported. Must be uppercase.
    DSA, RSA, and MD5.

    MD5

    sign

    String

    Signature value.

    656578b72f40e52 326dba4a41d6da62b

    Business Parameter

    out_trade_no

    String(64)

    The merchant transaction ID for the refund

    3824701800653976

    out_return_no

    String(64)

    Refund ID of the partner

    refund_status

    String(32)

    The refund status. The value can be:
    REFUND_SUCCESS: refund successfully
    REFUND_FAIL: refund failed

    REFUND_SUCCESS

    error_code

    String(64)

    Error code for a failed refund, this parameter is required only for the refund failed

    RETURN_AMOUNT_EXCEED

    currency

    String(8)

    The currency for the refund

    CNY

    return_amount

    Number(8,2)

    Refund amount

    100.00

    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

    • Make sure the Notification Page (notify_url) is absolutely blank, without space, html tag, or any error message threw from the program system.
    • Parameters in this page can be acquired with GET method, like request.Form("out_trade_no"), $_POST['out_trade_no'].
    • This response will be used, if Alipay initiatively notifies.
    • Alipay will notify when there is a real transaction in Alipay system and the status of that transaction has changed.
    • Interaction between servers, unlike interaction between websites which is visible, is usually not displayable.
    • When the first time the transaction status is changed, the page is redirected to the partner website, and a notification with the transaction result from Alipay will be received.
    • After the program is executed, the page must print “success” (without quote). If not, Alipay server keeps re-sending the notification, until over 24 hour 22 minutes Generally, there are 8 notifications within 25 hours (Frequency: 2m,10m,15m,1h,2h,6h,15h)
    • After the program is executed, the page should not be redirected. Otherwise, Alipay cannot receive the “success” string, and determines that an error occurred to the program execution. So Alipay will resend the notification.
    • Cookies and session are invalid on this page, so that these data cannot be captured.
    • The configuration and testing of this system must be on a server, via internet
    • By using the asynchronous notification, the transaction lost can be prevented. When the synchronous notification fails to update the transaction status, the asynchronous notification makes the update.
    • Only when the partner receives the sever asynchronous response and prints “success”, the parameter notify_id becomes invalid. That is to say, when Alipay sends the asynchronous notification, or when no “success” is printed and Alipay keeps re-sending the notifications, the parameter notify_id doesn't change.
    • Along with the business growth, Alipay may add new parameters (existing parameters will not change). When doing notification verification, Merchants MUST use all parameters (except sign and sign_type) returned from Alipay.

    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:

    Environment HTTPS request URL
    Production environment https://intlmapi.alipay.com/gateway.do
    Test environment https://mapi.alipaydev.com/gateway.do

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