After the cashier displays the QR code from the “precreate” call to the buyer, the buyer could scan the QR code and complete the payment. Alipay will send the updated info of the order to the merchant with the URL specified in “notify_url” field in the “precreate” API call.
| Parameter | Type | Mandatory | Description | Sample |
|---|---|---|---|---|
| notify_time | Date | Y | Time of the notification. The format is “yyyy-MM-dd HH:mm:ss” | 2015-14-27 15:45:58 |
| notify_type | String(64) | Y | The type of the notification. | trade_status_sync |
| notify_id | String(128) | Y | The id of the notification. | ac05099524730693a8b330c5ecf72da9786 |
| sign_type | String(10) | Y | The type of the signature type. Currently RSA and RSA2 are supported. | RSA2 |
| sign | String(256) | Y | The value of the signature. | 601510b7970e52cc63db0f44997cf70e |
| trade_no | String(64) | Y | The Alipay trade no. | 2013112011001004330000121536 |
| app_id | String(32) | Y | The app_id that Alipay assigns to the APP developer. | 2014072300007148 |
| out_trade_no | String(64) | Y | The transaction/order id passed in by the partner/merchant. It must be unique inside the merchant system. | 6823789339978248 |
| out_biz_no | String(64) | N | The business id on the merchant side. It is mostly used for the order number in refund notification. | HZRF001 |
| buyer_id | String(16) | N | The user id associated with the buyer’s Alipay account, in the format of 16 digit number starting with “2088”. | 2088102122524333 |
| buyer_logon_id | String(100) | N | The buyer’s Alipay logon id. | 15901825620 |
| seller_id | String(30) | N | The seller’s user id associated with the seller’s Alipay account, in the format of 16 digit number starting with “2088”. | 2088101106499364 |
| seller_email | String(100) | N | The seller’s Alipay logon id. | zhuzhanghu@alitest.com |
| trade_status | String(32) | N | The current status of the payment transaction. Please refer to “trade status”. | TRADE_CLOSED |
| total_amount | Number(9,2) | N | The total amount of the order, in CNY. | 20 |
| receipt_amount | Number(9,2) | N | The total amount to be received by the merchant in the settlement, in CNY. | 15 |
| invoice_amount | Number(9,2) | N | The invoice amount in the payment, in CNY. | 10.00 |
| buyer_pay_amount | Number(9,2) | N | The total amount that the buyer will pay in the payment, in CNY. | 13.88 |
| point_amount | Number(9,2) | N | The total amount that the buyer will pay in the Alipay reward point program, in CNY. | 12.00 |
| refund_fee | Number(9,2) | N | Total refund amount in the refund notification, in CNY. | 2.58 |
| send_back_fee | Number(9,2) | N | The total amount refunded by the merchant, in CNY. | 2.08 |
| subject | String(256) | N | The value of the subject field in the request parameters. | Baby cloth |
| body | String(400) | N | The value of the body field in the request parameters. | |
| gmt_create | Date | N | The creation time of the payment. The format is in “yyyy-MM-dd HH:mm:ss”. | 2015-04-27 15:45:57 |
| gmt_payment | Date | N | The payment completion time of the transaction. The format is in “yyyy-MM-dd HH:mm:ss”. | 2015-04-27 15:45:57 |
| gmt_refund | Date | N | The payment refund time of the transaction. The format is in “yyyy-MM-dd HH:mm:ss”. | 2015-04-28 15:45:57 |
| gmt_close | Date | N | The payment close time of the transaction. The format is in “yyyy-MM-dd HH:mm:ss”. | 2015-04-29 15:45:57 |
| fund_bill_list | String(512) | N | Amount info for all the fund channels in a successful payment. Please refer to "Detailed funding info”. |
| Enumeration name | Description |
|---|---|
| WAIT_BUYER_PAY | The payment transaction is created and waiting for the buyer to complete. |
| TRADE_CLOSED | The payment transaction is closed due to incomplete payment within the required timeframe or full-amount refund after the payment. |
| TRADE_SUCCESS | The payment transaction is successful. |
| TRADE_FINISHED | The payment transaction is finished and not refundable. |
Detailed Funding Information
| Parameter | Type | Mandatory | Description | Sample |
|---|---|---|---|---|
| fund_channel | String | N | The funding channel for the payment, please refer to the “Funding channel details” table. | COUPON |
| amount | String | N | The amount paid with the fund channel, in CNY. | 70.00 |
Funding channel details
| Funding channel code | Funding channel name |
|---|---|
| COUPON | Alipay coupon / red envelop |
| ALIPAYACCOUNT | Alipay balance |
| POINT | Alipay reward points |
| DISCOUNT | Alipay discount |
| PCARD | Prepaid card |
| FINANCEACCOUNT | Alipay money market fund, Yu’e Bao |
| MCARD | Merchant’s store card with cash value |
| MDISCOUNT | Merchant’s discount coupon |
| MCOUPON | Merchant’s discount coupon/red envelop with fixed value |
| PCREDIT | Alipay credit |
1) The main purpose of the async notification is to guarantee the payment result and new updates are received by the merchant. It is achieved by a build-in retry mechanism.
2) The value in “notify_url” field should contain no illegal characters, such as space, HTML tag, etc.
3) Alipay uses POST to send the notification. The merchant can retrieve the data with request.Form(“out_trade_no”).$_POST[‘out_trade_no’],etc.；
4) Alipay will initiate the sending of the notification.
5) If “notify_url” is not set by the merchant, there will be no Async notification sent.
6) Alipay only sends the async notification when the payment is successful (TRADE_FINISHED) or timed out (TRADE_CLOSED). If there is no payment or the payment is not completed yet, no async notification will be sent.
7) Async notification is not designed to be displayed on web pages.
8) Async notification is in parallel with URL page redirect (synchronous return). The merchant could get successful payment result from both async notification and URL page redirect.
9) After receiving the async notification and proper processing of the data, the merchant should send response back with a plain string “success”. Any different response or no response will be treated as “No Acknowledgement”. Alipay server will send the notification again. Normally they will resend 8 times within 25 hour. （Time interval：4m, 10m, 10m, 1h, 2h, 6h, 15h）All of those notifications are sharing with the same “notify_id”, which will not expire until getting the “success” response from the merchant.
10) To test the async notification, the url in “notify_url” should be accessible from internet. Otherwise, the internal servers will not get the notification.
11) The main purpose of async notification is to guarantee the update of the payment status. In rare cases, the result of the synchronous call fails to be returned to the merchant. The async notification will help the merchant to get the payment status and complete the order process.
It is recommended that the partner needs to verify if the notification is from Alipay before accepting it and sending response back.
The partner can only verify the notifications within the last one minute (this configuration might be changed in the future), and before sending the ‘Success’ acknowledgement back to Alipay.
To verify, get the notify_id from the async notification, construct an API URL as the other API calls, as the following,
https://mapi.alipay.com/gateway.do?service=notify_verify∂ner=2088002396712354¬ify_id=RqPnCoPT3K9%252Fvwbh3I%252BFioE227%252BPfNMl8jwyZqMIiXQWxhOCmQ5MQO%252FWd93rvCB%252BaiGg
If the notification is from Alipay, and inquires in the valid time frame, the response would be “True”.
If the notification is not from Alipay, or passes one-minute time frame, the response would be “False”.
Verifying the signature for the async notification is slightly different from that for synchronous response.
For example:
http://api.test.alipay.net/atinterface/receive_notify.htm?gmt_payment=2015-06-11 22:33:59¬ify_id=42af7baacd1d3746cf7b56752b91edcj34&seller_email=testyufabu07@alipay.com¬ify_type=trade_status_sync&sign=kPbQIjX+xQc8F0/A6/AocELIjhhZnGbcBN6G4MM/HmfWL4ZiHM6fWl5NQhzXJusaklZ1LFuMo+lHQUELAYeugH8LYFvxnNajOvZhuxNFbN2LhF0l/KL8ANtj8oyPM4NN7Qft2kWJTDJUpQOzCzNnV9hDxh5AaT9FPqRS6ZKxnzM=&trade_no=2015061121001004400068549373&out_trade_no=21repl2ac2eOutTradeNo322&gmt_create=2015-06-11 22:33:46&seller_id=2088211521646673¬ify_time=2015-06-11 22:34:03&subject=FACE_TO_FACE_PAYMENT_PRECREATE中文&trade_status=TRADE_SUCCESS&sign_type=RSA2
gmt_create=2015-06-11 22:33:46&gmt_payment=2015-06-11 22:33:59¬ify_id=42af7baacd1d3746cf7b56752b91edcj34¬ify_time=2015-06-11 22:34:03¬ify_type=trade_status_sync&out_trade_no=21repl2ac2eOutTradeNo322&seller_email=testyufabu07@alipay.com&seller_id=2088211521646673&subject=FACE_TO_FACE_PAYMENT_PRECREATE中文&trade_no=2015061121001004400068549373&trade_status=TRADE_SUCCESS
The merchant must handle the async notification properly for correct payment result. Only when the payment status is “TRADE_SUCCESS” or “TRADE_FINISHED”, the payment is completed.
If the merchant fails to handle the notification logic correctly, the risk and the potential loss will be on the merchant side.
Remarks：
Notification with status “TRADE_SUCCESS” will be returned when the buyer complete the payment successfully and the payment solution supports the Refund function.
Notification with status “TRADE_FINISHED” will be returned when the buyer complete the payment successfully, and the payment solution does not support the refund function, or the payment solution supports the refund function but refund function is not available as the refund time window is closed. (Refund must be completed within the pre-defined time window, specified in the contract.)