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

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

Notes:

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

Verifying the asynchronous notification

Verifing the asynchronous notification is an optional step.

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 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 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 "&".
Take the asynchronous response data of the create_forex_trade_wap 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.

RSA2/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 "&". 
Take the asynchronous response data of the create_forex_trade_wap 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 RSA2/RSA verification method to verify the signature. Pass the pre-sign string, the value of the sign parameter, and Alipay public key to the RSA2/RSA verification method to check the verification result. For more information about the RSA2/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 (overseas_support@service.alibaba.com).

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

ParameterType (length)DescriptionOptionalExample
Basic parameter
serviceStringService NameNnotify_verify
partnerString(16)Partner ID.
Composed of 16 digits beginning with 2088.
N2088001159940003
Business parameter
notify_id

String(34)

The ID of Alipay system's notification.N

Notes:

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

copy
Invalid

If the notification is from Alipay, and inquires in the valid time frame, (1 min)

copy
True

If the notification is not from Alipay, or passes 1 min time frame,

copy
False

Samples

Request sample

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

Returned resultDescription
SYSTEM_EXCEPTIONAlipay system error
ILLEGAL_ARGUMENTIncorrect parameter
ILLEGAL_SIGNIllegal signature
ILLEGAL_SERVICEService Parameter is incorrect
ILLEGAL_PARTNERIncorrect Partner ID
ILLEGAL_SIGN_TYPESignature is of wrong type.

Access errors

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 resultDescription
SYSTEM_EXCEPTIONAlipay system error
ILLEGAL_ARGUMENTIncorrect parameter
ILLEGAL_SIGNIllegal signature
ILLEGAL_SERVICEService Parameter is incorrect
ILLEGAL_PARTNERIncorrect Partner ID
ILLEGAL_SIGN_TYPESignature is of wrong type.
ILLEGAL_PARTNER_EXTERFACEService is not activated for this account
ILLEGAL_DYN_MD5_KEYDynamic key information is incorrect
ILLEGAL_ENCRYPTEncryption is incorrect.
ILLEGAL_USERUser ID is incorrect.
ILLEGAL_EXTERFACEInterface configuration is incorrect.
ILLEGAL_AGENTAgency ID is incorrect.
HAS_NO_PRIVILEGEHas no right to visit.
INVALID_CHARACTER_SETThe character set is invalid.

System errors

When system error occurs, please contact Global Merchant Technical Support (overseas_support@service.alibaba.com) to assist the error repair.

Returned resultDescription
SYSTEM_ERRORAlipay system error
SESSION_TIMEOUTSession timeout
ILLEGAL_TARGET_SERVICEWrong target service
ILLEGAL_ACCESS_SWITCH_SYSTEMMerchant is not allowed to visit system of this type.
EXTERFACE_IS_CLOSEDThe interface has been closed.