当面付－英文版
Heartbeat Sync-up APIs
更新时间：2017/06/08
访问次数：4473
Use case：
To ensure the health of the system, it is required that the terminal to sync up with the Alipay system every 30 minutes. The action will help Alipay and other parties to monitor and maintain a healthy and efficient system.
Remarks:
For merchants that integrate with bar-code payment version 2.0 (bar-code payment and wave sound payment) can integrate with this interface. The gateway URL is http://mcloudmonitor.com/gateway.do.
Data Interaction
Calculation Method of Time Cost in an API Call
The Process of a Heartbeat Sync-up
1)Construct the request data
The merchant generates the request and signature based on the API spec provided by Alipay
2)Send request
Send the request to API via URL page redirect or web form.
3)Data processing
After getting the request data, Alipay will validate and process them.
4)Return the result data
Alipay return the processed data to the merchant in JSON format.
5)Clear the performance record between two sync-ups
After the merchant gets the response from Alipay, it should clear the performance record on the merchant side between two sync-ups to avoid data duplication.
Request Parameters
| Parameter | Type | Mandatory | Length | Description | Sample |
|---|---|---|---|---|---|
| product | String | Y | 5 | The Alipay solution that the sync-up is bond with. For now we support only FP. | FP |
| type | String | Y | 10 | The device type which sends the heartbeat sync-up： CR——Terminal；STORE——Store；VM——Vending Machine |
CR |
| equipment_id | String | Y | 32 | Equipment id. If it is a terminal, it is the terminal id, whose min length is 6. If there is no equipment id, MAC address could be used here. | 1001023 |
| time | String | Y | 19 | Time of the heartbeat, in the format of “yyyy-MM-dd HH:mm:ss” | 2015-01-22 16:46:02 |
| store_id | String | Y | 32 | Store id which needs to be the same as the store_id in the payment API call. If there is no store id, please fill in “DF”. | 112 |
| network_type | String | Y | 4 | Network type that POS devices connect with: 2G、3G、WIFI、LAN. | LAN |
| equipment_status | String | Y | 2 | Equipment status： 10——device/software start-up；20——device/software shutdown；30——Normal |
10 |
| sys_service_provider_id | String | N | 16 | System service provider id. | 2088511833207846 |
| mac | String | N | 64 | MAC address. | 01-23-45-67-89-AB |
| trade_info | String | N | 256 | The payment performance information between two heartbeat sync-ups. It includes all the order numbers, time consumed, and status. The maximum is the first 30 payments. The data is in JSON format. More details please refer to the following section “payment performance information parameters” If we have multiple payment transactions, we can combine them in the order and payment time.If the heartbeat sync-up fails to be sent due to the network issues, the trade performance info could continue to accumulate until the sync-up succeeds and local data could be cleared. This data is very important. It should be filled if there is payment in the time frame. |
[{“OTN”:“201508011234”,“TC”:“5”,“STAT”:“S”},{“OTN”:“201508012345”,“TC”:“15”,“STAT”,“X”}] |
| exception_info | String | N | 128 | The information of the exceptions within the 2 heartbeats. If there are multiple exceptions, separate them with “|”. HE_PRINTER——Printer exception； HE_SCANER——scanner exception； HE_OTHER——Other hardware exceptions |
HE_PRINTER |
| extend_info | String | N | 256 | The extended info defined by the sender, in JSON format. | {“SHOP_ID”:“BJ_ZZ_001”,“TERMINAL_ID”:“1234”} |
Payment Performance Information Parameters
| Parameter | Type | Mandatory | Length | Description | Sample |
|---|---|---|---|---|---|
| OTN | String | Y | 32 | Merchant order number. | 201508011234 |
| TC | String | Y | 8 | The time consumed from barcode scanning to the return of payment result, in seconds. | 5.315 |
| STAT | String | Y | 1 | Status of the payment: S—Succes； I——In-progress return from Alipay； F——Failure return from Alipay； P——Failure with the merchant cashier system； X——Netwrok connection exception； Y——Exception in sending the request； Z——Exception in receiving the response； C——Cancelled by cashier |
S |
Sample:
1 2 3 4 5 6 | ---> HTTP POST http://mcloudmonitor.com/gateway.doContent-Type: application/x-www-form-urlencoded; charset=UTF-8Content-Length: 926 sign=pRuVxmlnsd4NNaRP3RACZLfejHNEnCKlLklO16o0tKv3To29TlKyAUuuM+xjd6wSd0g7rWYFGNY0SQWaXgwQZXrhx4jPKjk/aDYRvueURepQM9KB5GudAVqaour2hyAychGFZ3yHaoX5zLrWyjObPjeqSUsT0BmgmsN8ps/E7Xk=&biz_content={"product":"FP","type":"CR","equipment_id":"cr1000001","equipment_status":"30","time":"2015-09-28 11:14:49","store_id":"store10001","network_type":"LAN","mac":"0a:00:27:00:00:00","trade_info":[{"OTN":"00000001","TC":5,"STAT":"S"},{"OTN":"00000002","TC":4,"STAT":"F"},{"OTN":"00000003","TC":11,"STAT":"P"}],"exc eption_info":"HE_SCANER|HE_PRINTER|HE_OTHER"}×tamp=2015-10-23 15:41:47&sign_type=RSA2&charset=utf-8&method=monitor.heartbeat.syn&app_id=2014100900013222&version=1.0 |
Response Parameters in Synchronous Return
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | The result of “Success” return{ "monitor_heartbeat_syn_response": { "code": "10000", "msg": "同步心跳信息成功" }}The result of “Failed” return{ "monitor_heartbeat_syn_response": { "code": "40004", "sub_code":"ILLEGAL_SIGN", "msg":"接口调用异常", "sub_desc":"签名不正确" }} |
Error Codes
| Name | Description | Solution |
|---|---|---|
| ILLEGAL_ARGUMENT | At least one of the parameters is not valid. | Examine the request parameters and resend the request after fixing the issue. |
| SYSTEM_ERROR | System error. | If the error persists after multiple retries, please contact Alipay support team. |
| isv.invalid-app-id | Invalid APP_ID. | Contact Alipay CS to get the valid APP_ID. |
| isv.invalid-signature | Invalid signature. | Examine the signature function and retry. |
Remarks：
When integrate with this API, please do not impact the payment’s functionality and performance. When Alipay completes the processing, Alipay will return the feedback to the merchant. The merchant could use programs to simulate http to get the process the result and help the processing logic. The merchant must be able to judge if the result has been processed previously. If the merchant fails to do that, there is a potential risk that the merchant would be responsible for.
FAQ
- Q：Why do we need to integrate this API？
A：Integrating this API not only helps to monitor and discover potential issues, but also helps to improve the user experience of the payment. By collecting and sharing of the statistics of payment time and payment result, we could promptly find and fix the potential issues in the payment stack with stores and terminals such that we could improve the system performance and efficiency. - Q：Could the data such as time consumed be collected at Alipay server side?
A：No. The data has to be end-to-end. The data has to be obtained at the terminal end, such as the merchant’s cashier machine, POS, and APP, for the complete data. The server end normally it is very stable and not very meaningful to calculate the data on the server end only. - Q：How to integrate the API?
A：One possible solution is to use multi-thread to cooperate with the payment thread and heartbeat sync-up payment. Whenever a payment is in progress, the info is written into the memory by the payment thread. Every 30 minute, the heartbeat sync-up thread will pick up the unsynchronized payment info from the memory, pack them and send to Alipay via the API. - Q：What is time consumption for the payment?
A：The time consumption for the payment refers to the time that it takes for calling the pay API. Record the start time before calling the API. Record the complete time when the call returns (or with exception). The time difference between the start time and the complete time is the time consumption of the API call. - Q：How to record the time consumption for one payment API call?
A：The recording is done by the payment thread. The details are as the following:
Record the start time before calling the pay API
When the API call returns successfully with a status code 10000, record the complete time and mark the payment status to ‘S’.
When the API call returns “In-progress” code with a status code 10003, record the end time and mark the payment status to ‘I’.
When the API call returns with error, record the end time and mark the payment status to ‘F’.
When the API call has network connection error, record the end time and mark the payment status to ‘X’.
When the API call has parameter errors, record the complete time and mark the payment status to ‘Y’.
When the API call returns with error, record the complete time and mark the payment status to ‘F’.
When the API call fails to get the response, record the complete time and mark the payment status to ‘Z’.
All the data would be recorded to the memory by the payment thread, and be retrieved and sent every 30 minutes by the heartbeat sync-up thread. - Q：When to start and finish to call the heartbeat sync-up API?
A：It is start when the machine/software starts up. It is sent every 30 min. When the system/software power-off or closed, call the API for the last call, We should not send sync-up according to absolute time, which might cause all the machines calling the API in almost the same time. last time in the same time., - Q：Do we need to send the heartbeat sync-up even without any payment in the timeframe?
A：Yes we should. We can ignore the trade_info field and leave it blank. - Q：What to do if I do not have equipment id?
A：The equipment id is used to identify the terminals on the merchant/system provider side. It can be recorded by the merchant / system provider, as long as it is unique in the system. - Q：When should I pass in the sys_service_provider_id parameter?
A：When the system provider integrates the solution for the merchants, the system provider needs to fill the field with its id assigned by Alipay. The merchant could ignore the field.
