Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

API specification

Introduction

Alipay APIs are web-based APIs with request and response messages.  

The gateway URL:

EnvironmentHTTPS request URL
Production environmenthttps://intlmapi.alipay.com/gateway.do
Test environmenthttps://mapi.alipaydev.com/gateway.do

Request and response message structure

The following examples illustrate the message structure of Alipay web-based APIs.

API request：

Combine the gateway information, parameters and their values, and the sign type and value with a character of &, you can get a complete URL address. For example:

copy
https://mapi.alipaydev.com/gateway.do?_input_charset=UTF-8&service=create_forex_trade&partner=2088101122136***&out_trade_no=test201707180942***&subject=test123&body=test&currency=USD&total_fee=0.01&product_code=NEW_OVERSEAS_SELLER&notify_url=http://localhost:8080/create_forex_trade-JAVA-UTF-8-RSA/notify_url.jsp&return_url=http://localhost:8080/create_forex_trade-JAVA-UTF-8-RSA/return_url.jsp&sign_type=RSA&sign=H6WZp6aQqNkr5j%2BaclPlSz45L3udPBoXf8KS5CfHKaB1oWdDs8mte5TPy6GInJCpET0I9aSPc%2FlXqlTkVee64%2F01wyHumWQriMW7tB%2F0Rlko6jImL0QysX4y%2BsonxHs94t7wmUf9zAoAcLGZplnsn4n04u4eprBI%2B3SIqJDd82k%3D

API response:

copy
<?xmlversion="1.0"encoding="UTF-8"?> 
  <alipay> 
  <is_success>T</is_success> 
   <request> 
    <param name="_input_charset">UTF-8</param> 
    <param name="currency">USD</param> 
    <param name="buyer_identity_code">2013112012345678</param> 
    <param name="identity_code_type">qrcode</param> 
    <param name="mcc">4021</param> 
    <param name="extend_info">{"licence":"123",name=”LG”}</param> 
    <param name="partner_trans_id">2010121000000002</param> 
    <param name="partner">2088102012343978</param> 
    <param name="password">SJV88po0XvIptqWGM4rxP5EQ</param> 
    <param name="memo">shopping</param> 
    <param name="service">alipay.acquire.overseas.pay</param> 
    <param name="sign">22904adafb1806178b410d2d5c9c02a3</param> 
    <param name="sign_type">MD5</param> 
    <param name=“trans_name”>Belkin wrist type</param> 
    <param name="trans_amount">39.25</param> 
    <param name="trans_create_time">20131120153059</param> 
   </request> 
  <response> 
  <alipay> 
   <alipay_trans_id>2011091703338463</alipay_trans_id> 
   <partner_trans_id>201311221000000002</partner_trans_id> 
   <alipay_buyer_login_id>caoxxx@126.com</alipay_buyer_login_id>
   <alipay_buyer_user_id>2088102130896433</alipay_buyer_user_id> 
   <alipay_pay_time>20131120155823</alipay_pay_time> 
   <exchange_rate>6.0939</exchange_rate> 
   <trans_amount>39.25</trans_amount> 
   <trans_amount_CNY>239.19</trans_amount_CNY> 
   <result_code>SUCCESS</result_code> 
  </alipay> 
  </response> 
  <sign>6fb8a322f15cfd0fcfe65301b10f6994</sign> 
  <sign_type>MD5</sign_type> 
 </alipay>

Note:

  • Service parameters in the request and response section vary depending on services. For more information, see instructions of the specific interface.
  • For both the GET request and POST requests, if the value of request parameters contains special characters or Chinese characters, you need to URL encode values of all the parameters in the request URL.
  • For a POST request, you need to include the _input_charset field in the gateway URL. For example，if the value of request parameters contains Chinese characters, the gateway URL is: https://intlmapi.alipay.com/gateway.do?_input_charset=utf-8

Digital signature

Digital signature is used to ensure the authenticity of the messages. To make the API call, client and Alipay must exchange their public keys. Therefore, each party keeps its own private key and shares the public key with the other side. When sending messages, the sender uses its private key to sign the message while the receiver uses sender's public key to verify the received message. The following steps show how to sign a message. 

1、Preparing keys

  • To get the MD5 keys, log in to the Global Portal with your user ID and view the technical service page.
  • To get the RSA/DSA keys, install OpenSSL from OpenSSL site and generate key pairs. 

2、Create the pre-sign string

Complete the following steps to create the pre-sign string:

  • Identify the parameters to be signed. 

All the parameters in the list of request and response parameters need to be signed except the sign and sign_type. (Sign_type also needs to be signed in some cases in the list of request parameters)

  • Sort the above parameters alphabetically.

Sort the parameters according to the key value ASCII code of the first character in ascending alphabetical order. For parameters with the same first character, make the sort based on the second character.

  • Create the pre-sign string.

Combine all the sorted parameters in the format of parameter name = parameter value and link the combinations with the character of &. In this way, you get the pre-sign string.

3、Sign the request

After the pre-sign string is generated, perform the following steps to generate the signature:

  • Use the RSA/DSA algorithm and the merchant private key to generate the signature.
  • Encode the signature to a string.
  • Then, use the string as the value of the "sign" parameter.

Asynchronous or synchronous notification

The asynchronous notification is an API response that is sent to the API caller asynchronously with the POST method if the notify_url field was set in the request with the targeted URL to handle the asynchronous notification. The synchronous notification is an API response that is sent to the API caller synchronously with the GET method if the return_url field was set in the request with the targeted URL to handle the synchronous notification. 

After the transaction succeeds, you might receive both asynchronous and synchronous responses. It is recommended to process the asynchronous notification. You can verify both the asynchronous and synchronous notifications, however, it is not mandatory.

Alipay resends the asynchronous notification 8 times within 25 hours until the receiver acknowledges the receipt of the notification by sending a string "SUCCESS" (without the quotation) in the response. The Alipay resending frequency: 2m,10m,10m,1h,2h,6h,15h.

Verifying the asynchronous notification

After receiving a notification, it is recommended 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. You can verify the notification by completing the following steps:

MD5

1、Ensure that the notification is sent by Alipay before you start verify the content of the notification. To verify the sender of the notification, see Notify_verify method for details. If the sender is verified as Alipay, you will get a result of ResponseTxt==true from the Notify_verify method. If the sender is not Alipay, no need to continue the following steps.

2、Process the content of the notification sent from Alipay to get a pre-sign string. 

a. Remove sign and sign_type fields. 

b. Sort the remaining fields in alphabetical order from A to Z.

c. Connect all array values by the character of "&".

Take the asynchronous response data of the create_forex_trade API as an example: 

copy
notify_id=5b89a773c60af059d96b1693dd3b3d6nc1&notify_type=trade_status_sync&sign=b34d89788d9012f77f5b74ac232145f5&trade_no=2018110922001332950500389138&total_fee=0.01&out_trade_no=test20181109153145&notify_time=2018-11-09 15:36:17&currency=USD&trade_status=TRADE_FINISHED&sign_type=MD5

After processing, you get the following content to be signed: 

copy
currency=USD&notify_id=5b89a773c60af059d96b1693dd3b3d6nc1&notify_time=2018-11-09 15:36:17&notify_type=trade_status_sync&out_trade_no=test20181109153145&total_fee=0.01&trade_no=2018110922001332950500389138&trade_status=TRADE_FINISHED

3、Get the value of the mysign parameter.

a. Append MD5 key to the end of the pre-sign string obtained in Step 2. 

b. A value is generated by encrypting the string that consists of the pre-sign string and MD5 key by an MD5 encryption function. Assign this value to the mysign parameter.

4、Verify whether mysign = sign. If the value of mysign, obtained in Step 3, and the value of sign, returned by Alipay, are equal, the verification of the signature is passed and you can trust the content of the notification.

RSA

1、Ensure that the notification is sent by Alipay before you start verify the content of the notification. To verify the sender of the notification, see Notify_verify API for details. If the sender is verified as Alipay, you will get a result of ResponseTxt==true from the Notify_verify method. If the sender is not Alipay, no need to continue the following steps.

2、Process the content of the notification sent from Alipay to get a pre-sign string. 

a、Remove sign and sign_type fields, 

b、Sort the remaining fields in alphabetical order from A to Z

c、Connect all array values by the character of "&". 

Take the asynchronous response data of the create_forex_trade API as an example: 

copy
currency=USD&notify_id=5ac226e4cf7822d205cedcc252b54ebge1&notify_time=2017-08-16 15:24:12&notify_type=trade_status_sync&out_trade_no=test20170816150740&total_fee=0.01&trade_no=2017081621001003050502834160&trade_status=TRADE_FINISHED&sign_type=RSA&sign=NN2trlV3PKBjZN7KS4oE8PG8WkHFqXIvvQl32fJ2FO9J+HniSuvv36VYPWbARVmodnTvYVkFmR2FB9ioDX0iRTRRSCkz8+ox3ytrlRdRfaeGMSGBuHN6WP/tAHscBbNvjkzyshjTCoXO6MFFg92CR2K50DvtNNUerZa/mx4lA5I=

3、After processing, you get the following content to be signed: 

copy
currency=USD&notify_id=5ac226e4cf7822d205cedcc252b54ebge1&notify_time=2017-08-16 15:24:12&notify_type=trade_status_sync&out_trade_no= test20170816150740&total_fee=0.01&trade_no=2017081621001003050502834160&trade_status=TRADE_FINISHED

4、Encode the signature parameter (sign) into a bytecode string by using the Base64 scheme.

5、Use the RSA verification method to verify the signature. Pass the pre-sign string, the value of the sign parameter, and Alipay public key to the RSA verification method to check the verification result. For more information about the RSA verification method, see the following method in demo code.

copy
public static boolean verify(String content, String sign, String ali_public_key, String input_charset)

To get the Alipay public key, contact Global Merchant Technical Support (AlipayGlobalTechService@service.alipay.com).

Verifying the synchronous notification

After receiving a notification, it is recommended 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. By completing the following steps, the notification is verified and you can trust the notification.

MD5

1、Process the content of the notification sent from Alipay to get a pre-sign string. 

a、Remove sign and sign_type fields, 

b、Sort the remaining fields in alphabetical order from A to Z

c、Connect all array values by the character of "&". 

Note:

If the returned notification is in XML, the returned parameters are contained in the nodes. You can take each node name as the parameter name and node value as the parameter value.Take the synchronous response data of the create_forex_trade API as an example: 

copy
out_trade_no=test20181109153145&total_fee=0.01&trade_status=TRADE_FINISHED&sign=32c532376eee9281fa4d424dd4a40e5b&trade_no=2018110922001332950500389138&currency=USD&sign_type=MD5

After processing, you get the following content to be signed: 

copy
currency=USD&out_trade_no=test20181109153145&total_fee=0.01&trade_no=2018110922001332950500389138&trade_status=TRADE_FINISHED

2、Get the value of the mysign parameter.

a、Append MD5 key to the end of the pre-sign string obtained in Step 2. 

b、A value is generated by encrypting the string that consists of the pre-sign string and MD5 key by an MD5 encryption function. Assign this value to the mysign parameter.

3、Verify whether mysign = sign. If the value of mysign, obtained in Step 3, and the value of sign, returned by Alipay, are equal, the verification of the signature is passed and you can trust the content of the notification.

RSA

1、Process the content of the notification sent from Alipay to get a pre-sign string. 

    a. Remove sign and sign_type fields, 

    b. Sort the remaining fields in alphabetical order from A to Z

    c. Connect all array values by the character of "&". 

Note:

If the returned notification is in XML, the returned parameters are contained in the nodes. You can take each node name as the parameter name and node value as the parameter value.Take the synchronous response data of the create_forex_trade API as an example: 

copy
currency=USD&out_trade_no=test20170816150740&trade_no=2017081621001003050502834160&total_fee=0.01&trade_status=TRADE_FINISHED&sign=cOb1oftUVcIQFNcep%2FiVuR0HHxkrXa8eYH1xuYkBFZ4bNz7rBcsptahYnDeImzmq%2FND7mIjshyYw0Kt%2BuvM4fG7UzJHmSQS0JhMcmfIls60Qmd6UYpoTNEWi5jY7P%2BIB%2BxLyjRDFZgfkRX3jDkEGbvwgzYpEqhS1bx%2FdHn1kh7Y%3D%20

After processing, you get the following content to be signed: 

copy
currency=USD&out_trade_no=test20170816150740&total_fee=0.01&trade_no=2017081621001003050502834160&trade_status=TRADE_FINISHED

2、Encode the signature parameter (sign) into a bytecode string by using the Base64 scheme.

3、Use the RSA verification method to verify the signature. Pass the pre-sign string, the value of the sign parameter, and Alipay public key to the RSA verification method to check the verification result. For more information about the RSA verification method, see the following method in demo code.

copy
public static boolean verify(String content, String sign, String ali_public_key, String input_charset)

To get the Alipay public key, contact Global Merchant Technical Support (AlipayGlobalTechService@service.alipay.com).

Usage limitations

Whenever the interface description and specification limitations listed here are in conflict with that on a specific API doc, the information on the specific API doc prevails.