52
- [Introduction](./1) - [Payment Flow and User Experience](./3) - [Quick start](./64) - [Pay Flow](./57) - [Refund Flow](./58) - [Query Flow](./59) - [Reconciliation Flow](./67) - [Secondary Merchant Maintenance Flow](./68) - [Integration](./42) - [Preparing keys](./48) - [Downloading Demo Code](./66) - [Calling APIs](./65) - [Creating the Pre-sign String](./75) - [Signing the Request and Creating the Request URL](./50) - [Processing Notifications](./51) - [Verifying the Asynchronous Notification](./52) - [Verifying the Synchronous Notification](./53) - [Testing in Sandbox](./44) - [Prerequisites](./43) - [Deploying in Sandbox](./45) - [Running Demo Code in Sandbox](./46) - [Going Live](./55) - [API list](./6) - [Create_forex_trade](./6) - [Request Parameters](./6) - [Sync Response](./7) - [Samples](./8) - [Async Notification](./9) - [Error Codes](./10) - [Change History](./74) - [Forex_refund](./11) - [Request Parameters](./11#Request) - [Sync Response](./11#Response) - [Samples](./11#Samples) - [Error Codes](./12#Errors) - [Async Notification](./70) - [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](./37) - [Request Parameters](./37#request) - [Sync Response](./37#sync) - [Samples](./37#samples) - [Error Codes](./37#error) - [Change History](./37#history) - [alipay.overseas.secmerchant.maintain.queryStatus](./73) - [Request Parameters](./73#request) - [Sync Response](./73#sync) - [Samples](./73#samples) - [Error Codes](./73#error) - [Change History](./73#history) - [Reconciliation files](./34) - [Obtaining Reconciliation Files](./35) - [API](./35#API) - [Alipay global site](./35#Global) - [SFTP](./35#SFTP) - [Reconciliation File Contents](./36) - [Transaction file](./36#TransactionFile) - [Settlement file](./36#SettlementFile) - [Digital Signature](./69) - [Preparing Keys](./48) - [Creating the Pre-sign String](./75) - [Signing the Request](./50) - [Verifying the Signature of Asynchronous Response](./52) - [Verifying the Signature of Synchronous Response](./53) - [FAQ](/help/online)
New Cross-border Website Payment

Verifying the Asynchronous Notification

What is an asynchronous notification?

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.

After sending the notification, Alipay calls the notify page to check whether the notification is received. If the notify page doesn't show "SUCCESS", Alipay continues to resend the notification. The notify page is one of the following pages in different languages:

  • Java: notify_url.jsp
  • Php: notify_url.php
  • C#: notify_url.aspx.cs
  • 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.
  • Only when the transaction exists in the Alipay transaction management center, and the status of the transaction is changed (except that the transaction status is “waiting for the buyer to pay” for instant transfer ), Alipay sends an asynchronous notification through the POST method.

Verify the asynchronous notification

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. 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 the 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:

    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:

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

    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=

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

    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

  3. Encode the signature parameter (sign) into a bytecode string by using the Base64 scheme.
  4. 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.
    
    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.

Notify_verify method

  • Purpose

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

  • Mechanism

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

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


    Through this request URL, you can get the result data from Alipay server with the method of programming to simulate the http request interacting with Alipay server.
    If returned information is true, the verification succeeds, otherwise fails.

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 the asynchronous notification is as below:
    • Receive the notification, do not reply ‘Success’. 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 by 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 you replied any of the notification with the response of “true”, Alipay returns “False”.
    • Once verified, you 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

Error codes

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.

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 in the production environment.

Sandbox environment 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 you access the Alipay Sandbox Portal to start the test, you need to make some preparations. See Prerequisites for details.

Before you test Alipay payment features in sandbox, you need to get the following preparations:

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

Use your merchant account to log in to the Alipay Sandbox Portal, if you don’t have the account, see Prerequisites.

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

There are two types of test account: merchant test account and buyer test account.

Merchant test accounts:

Find the merchant test account information in the Alipay sandbox portal under Sandbox Accounts > Merchant. More than one test accounts are provided, and the accounts are sorted by payment feature. Find the correct one to use according to the payment feature you want to test. For example, to test the Alipay Auto Debit feature, use the account information provided under Alipay Auto Debit.

  • Login password: Use this password to login to the Alipay for Business website in the sandbox environment.
  • Signature key: Only MD5 signature is supported in the sandbox environment. RSA signature is not supported at this time.

    For more information about the MD5 signature, see Digital Signature.

Buyer test account:

Use the buyer test account to login to the Alipay sandbox app.
The buyer test account information can be found in the Alipay sandbox portal under Sandbox Accounts > Buyer.

Account balance: You can click Top Up to top up the buyer test account.

Download the Alipay sandbox app

The Alipay sandbox app supports only Android at this time.

1) In the Alipay sandbox portal, click Alipay Sandbox App from the menu on the left.
2) Take one of the following steps:

To log in to the Alipay sandbox app, use the buyer test account and login password that are provided in the portal under Sandbox Accounts > Buyer.

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.

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 the merchant can make use of the refunding interface to complete the refunding, as illustrated.

For the integration of the refunding service, we would like to highlight:

  1. The refunding service name is: alipay.acquire.overseas.spot.refund(REFUND);
  2. To refund a transaction, the interface REVERSE is only applicable at the same day of the payment (GMT +8, Beijing time); on the other hand, the interface REFUND is applicable as long as the refunding period has not expired yet;
  3. the refunding of a transaction can be full or partial, i.e. the refunding amount can respectively be the same as or less than the original transaction amount that has been paid; furthermore, for a transaction, multiple refunding request is allowed provided the sum of the amount of the multiple refunding request is less than or equal with the original transaction amount. 

Except for "sign" and "sign_type", all other parameters used need to be signed.

Generating the pre-sign string for request

For the following parameter array:

string[]  parameters={"partner=\"208861122157****\"",
"seller_id=\"208861122157****\"",
"out_trade_no=\"0811172929-1013\"",
"subject=\"test\"",
"body=\"test\"",
"currency=\"HKD\"",
"total_fee=\"0.1\"",
"notify_url=\"http://0ee96cd2.ngrok.io/notify.htm\"",
"service=\"mobile.securitypay.pay\"",
"payment_type=\"1\"",
"_input_charset=\"utf-8\"",
"appenv=\"system=java^version=1.8\"",
"forex_biz=\"FP\""
  };
Combine all array values in the format of key= “value” and then link them up by the character “&” in an alphabetical order. For example:

_input_charset="utf-8"&appenv="system=java^version=1.8"&body="test"¤cy="HKD"&forex_biz="FP"¬ify_url="http://0ee96cd2.ngrok.io/notify.htm"&out_trade_no="0811172929-1013"&partner="208861122157****”&payment_type="1"&seller_id="208861122157****”&service="mobile.securitypay.pay"&sign="$$$"&sign_type="RSA"&subject="test"&total_fee="0.1"

Generating the pre-sign string for synchronous notification

The following sample illustrates the content of a synchronous notification:

resultStatus={9000};memo={};result={partner="2088101568358171"&seller_id="xxx@alipay.com"&out_trade_no="0819145412-6177"&subject="test"&body="testtest"&total_fee="0.01"&notify_url="http://notify.msp.hk/notify.htm"&service="mobile.securitypay.pay"&payment_type="1"&_input_charset="utf-8"&it_b_pay="30m"&show_url="m.alipay.com"&success="true"&sign_type="RSA"&sign="hkFZr+zE9499nuqDNLZEF7W75RFFPsly876QuRSeN8WMaUgcdR00IKy5ZyBJ4eldhoJ/2zghqrD4E2G2mNjs3aE+HCLiBXrPDNdLKCZgSOIqmv46TfPTEqopYfhs+o5fZzXxt34fwdrzN4mX6S13cr3UwmEV4L3Ffir/02RBVtU="}

Take out the part of result, remove "sign" and "sign_type" parameters:

partner="2088101568358171"&seller_id="xxx@alipay.com"&out_trade_no="0819145412-6177"&subject="test"&body="testtest"&total_fee="0.01"&notify_url="http://notify.msp.hk/notify.htm"&service="mobile.securitypay.pay"&payment_type="1"&_input_charset="utf-8"&it_b_pay="30m"&show_url="m.alipay.com"&success="true"

Generating the pre-sign string for asynchronous notification

The following sample illustrates the contents of an asynchronous notification:

http://0ee96cd2.ngrok.io/notify.htm? buyer_id=208812287878****¤cy=HKD&forex_rate=0.85420000¬ify_id=e5f5c6a77034fcd111e373e7e61dcbegdy¬ify_type=trade_status_sync¬ify_time=2017-08-11 17:31:39&out_trade_no=0811172929-1013&rmb_fee=0.09&seller_id=208861122157****&trade_no=2017081121001003050274536539&total_fee=0.10&trade_status=TRADE_FINISHED&sign_type=RSA&sign=$$$

Remove sign and sign_type, sort other parameters in alphabetical order, and then link up all array values by the character of “&”:

buyer_id=208812287878****¤cy=HKD&forex_rate=0.85420000¬ify_id=e5f5c6a77034fcd111e373e7e61dcbegdy¬ify_type=trade_status_sync¬ify_time=2017-08-11 17:31:39&out_trade_no=0811172929-1013&rmb_fee=0.09&seller_id=208861122157****&trade_no=2017081121001003050274536539&total_fee=0.10&trade_status=TRADE_FINISHED

  • Parameters without value don't need to be transmitted, nor to be included in the data to be signed;
  • At signing, the character set used to change the character into byte stream must be consistent with that specified in _input_charset;
  • If the parameter _input_charset is transmitted, it shall also be included in the data to be signed.
MD5 sign type

After the pre-sign string is generated:

  1. Append the MD5 secret key to the pre-sign string to generate a new string.
  2. Calculate the new string with the MD5 signature algorithm (by using the MD5 signature function).
The result 32-byte string is the signature, which is used as the value of the “sign” parameter.

RSA/DSA sign type

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

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

MD5 sign type

After receiving the character string of the response or notification from Alipay system, similar to the steps taken in Signing the data, append the MD5 secret key to the character string to generate a new string. Then, calculate this new string with the MD5 signature algorithm. After the 32-byte signature result string is generated, verify whether the value is equal to the value passed in the sign parameter. If Yes, the verification is passed.

RSA/DSA sign type

After receiving a response or notification, perform the following steps to verify the signature:

  1. Generate the pre-sign string as described in Generating Pre-sign String.
  2. Use the RSA/DSA algorithm to calculate a message digest.
  3. Use the RSA/DSA public key to de-sign the signature (the value of the sign field) to a message digest.
  4. Compare the two message digests obtained in step 2 and step 3. If the digests are the same, then it indicates that the signed data has not been changed.

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.

客服小机器人

NEED HELP ?