当面付
接口名称：monitor.heartbeat.syn
使用场景：支付宝将大数据和监控开放给商户/ISV。为了保障商户收银效果，要求每30分钟（或小于30分钟）从终端同步支付宝交易性能和异常信息。支付宝将该数据和支付宝内数据有机整合为商户/ISV提供实时监控能力，为线下收银保障护航。
数据交互
说明：
- “计算支付耗时”即下面参数TC（交易耗时）；
- “本地缓存交易数据”即下面参数trade_info 中OTN（商户订单号）、TC（交易耗时）、STAT（交易状态）；
- “同步本地数据”即将交易保障接口中涉及的数据同步到支付宝。
请求参数
商户/ISV通过自主监控平台对自身的业务进行实时监控。覆盖商户和门店的性能和异常监控。
公共请求参数：
| 参数 | 类型 | 是否必填 | 最大长度 | 描述 | 示例值 |
|---|---|---|---|---|---|
| app_id |
String |
是 |
32 |
支付宝分配给开发者的应用ID |
2014072300007148 |
| method |
String |
是 |
128 |
接口名称 |
monitor.heartbeat.syn |
| format |
String |
否 |
40 |
仅支持JSON |
json |
| charset |
String |
是 |
10 |
请求使用的编码格式，如UTF-8,gbk,gb2312等 |
UTF-8 |
| sign_type |
String |
是 |
10 |
商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2 |
RSA2 |
| sign |
String |
是 |
256 |
商户请求参数的签名串，详见签名 |
详见示例 |
| timestamp |
String |
是 |
19 |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" |
2014-07-24 03:07:50 |
| version |
String |
是 |
3 |
调用的接口版本，固定为：1.0 |
1.0 |
| notify_url |
String |
否 |
256 |
支付宝服务器主动通知商户服务器里指定的页面http路径。 |
http://api.test.alipay.net/atinterface/receive_notify.htm |
| app_auth_token |
String |
否 |
40 |
详见应用授权概述 |
|
业务请求参数：
| 参数 | 参数名称 | 类型（字节长度） | 参数说明 | 是否可为空 | 样例 |
|---|---|---|---|---|---|
| product |
发送心跳的设备所依赖的支付宝产品 |
String(5) |
发送心跳的设备所依赖的支付宝产品，目前仅支持FP：当面付产品 |
不可空 |
FP |
| type |
发送心跳的设备类型 |
String(10) |
发送心跳的设备类型：
|
不可空 |
CR |
| equipment_id |
发送心跳的设备ID |
String(32) |
商户下唯一识别终端的标识。若发起方为收银机，可为收银机设备的ID，最短6位；如没有设备ID，可填MAC地址 |
不可空 |
1001023 |
| time |
心跳发生时间 |
String(19) |
产生心跳的时间，格式为：yyyy-MM-dd HH:mm:ss |
不可空 |
2015-01-22 16:46:02 |
| store_id |
门店ID |
String(32) |
门店ID。需要和交易接口中的门店ID保持一致。 如无门店ID，请填“DF” |
不可空 |
112 |
| network_type |
网络类型 |
String(4) |
pos设备连接的网络类型：2G、3G、WIFI、LAN。 LAN：有线网络 |
不可空 |
LAN |
| sys_service_provider_id |
系统商编号 |
String(16) |
系统商的编号 |
可空 |
2088511833207846 |
| mac |
mac地址 |
String(64) |
Mac地址 |
可空 |
01-23-45-67-89-AB |
| trade_info |
交易性能信息 |
String(256) |
两次心跳时间内的交易相关信息。包括期间所有交易的商户订单号、耗时和状态。最多发送前30笔交易信息。json格式，具体参见下面的“交易性能信息参数说明”。 多笔交易按时间顺序直接拼接。 如果由于网络等原因心跳发送失败，则该交易性能信息本地继续累积，直到有心跳发送成功后，本地数据才可以清除。 此数据非常重要，有交易则必填 |
不可空 |
[{“OTN”:“201508011234”,“TC”:“5”,“STAT”:“S”},{“OTN”:“201508012345”,“TC”:“15”,“STAT”,“X”}] |
| exception_info |
异常信息 |
String(128) |
心跳时间段内的机具异常原因，如有多个用“|”分隔。
|
可空 |
HE_PRINTER |
| extend_info |
扩展信息 |
String(256) |
心跳信息发送方自定义，json格式 |
可空 |
{“SHOP_ID”:“BJ_ZZ_001”,“TERMINAL_ID”:“1234”} |
交易性能信息参数说明：
| 参数 | 参数名称 | 类型（字节长度） | 参数说明 | 是否可为空 | 样例 |
|---|---|---|---|---|---|
| OTN | 商户订单号 | String(32) | 商户订单号 | 不可空 | 201508011234 |
| TC | 交易耗时 | String(8) | 在终端上，从扫描到条码开始，到支付宝下单支付结果返回的间隔时间，单位为秒 | 不可空 | 5.315 |
| STAT | 交易状态 | String(1) |
|
不可空 | S |
请求样例：
---> HTTP POST http://mcloudmonitor.com/gateway.do Content-Type: application/x-www-form-urlencoded; charset=UTF-8 Content-Length: 926 sign=pRuVxmlnsd4NNaRP3RACZLfejHNEnCKlLklO16o0tKv3To29TlKyAUuuM+xjd6wSd0g7rWYFGNY0SQWaXgwQZXrhx4jPKjk/aDYRvueURepQM9KB5GudAVqaour2hyAychGFZ3yHaoX5zLrWyjObPjeqSUsT0BmgmsN8ps/E7Xk=&biz_content={"product":"FP","type":"CR","equipment_id":"cr1000001","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
说明：本样例仅供参考。
同步返回参数说明
操作成功时响应结果
{
"monitor_heartbeat_syn_response": {
"code": "10000",
"msg": "同步心跳信息成功"
}
}
操作失败时响应结果
{
"monitor_heartbeat_syn_response": {
"code": "40004",
"sub_code":"ILLEGAL_SIGN",
"msg":"接口调用异常",
"sub_desc":"签名不正确"
}
}
错误码
| 错误代码（sub_code） | 含义(sub_desc) | 场景描述 | 解决方案 |
|---|---|---|---|
| ILLEGAL_ARGUMENT |
非法参数 |
请求参数未按指引填写 |
请求参数有错，重新检查请求后，再调用。 |
| SYSTEM_ERROR |
系统错误 |
系统出现未知错误 |
如果多次调用依然报此错误码，请联系支付宝客服 |
| isv.invalid-app-id |
无效的AppID参数 |
应用APP_ID填写错误或者对应的APP_ID状态无效 |
联系支付宝客服，确认APP_ID的状态 |
| isv.invalid-signature |
无效签名 |
签名错误或者签名方式有误 |
重新检查签名方式后，再调用。 |
使用SDK快速接入
交易保障接口monitor.heartbeat.syn：
| //获得初始化的AlipayClient |
关键入参：
| 参数 |
参数说明 |
| product |
发送心跳的设备所依赖的支付宝产品，目前仅支持FP：当面付产品 |
| type |
发送心跳的设备类型 |
| equipment_id |
商户下唯一识别终端的标识 |
| time |
产生心跳的时间 |
| store_id |
门店ID |
| network_type |
pos设备连接的网络类型 |
| trade_info |
两次心跳时间内的交易相关信息。此数据非常重要，有交易则必填 |
关键交易性能信息入参：
| 参数 |
参数说明 |
| OTN |
商户订单号 |
| TC |
在终端上，从扫描到条码开始，到支付宝下单支付结果返回的间隔时间，单位为秒 |
| STAT |
· S——交易成功； · I-支付宝返回支付处理中； · F——支付宝返回失败； · P——商户收银系统失败； · X——建立连接异常； · Y——报文上送异常； · Z——报文接收异常 |
常见问题
Q：为什么需要接入交易保障接口？
A：接入交易保障接口不仅可以发现终端存在的问题，更是为了优化商户收银的支付体验，通过交易耗时、终端支付结果等数据的统计和开放，可以及时发现门店和终端问题，进而提升整个收银链路的效率。
Q：交易耗时等数据是否可以在服务端统计？
A：不可以。交易保障接口是为了保障终端到支付宝全链路的支付体验，所以这些数据需要在终端进行统计，也就是商户的收银机、POS机、APP等终端设备。服务端通常非常稳定，从服务端统计这些数据意义不大。
Q：如何集成交易保障接口？
A：集成交易保障接口需要交易线程和发送交易保障信息的线程协同工作，进行交易的线程完成一笔交易后，则会将交易信息异步写入内存；交易保障线程每隔30分钟从内存队列中读取未同步的交易信息，然后调用交易保障接口同步给支付宝。
Q：什么是交易耗时？
A：交易耗时指的是调用当面付下单并支付接口时所消耗的时间。调用接口前记录起始时间，接口返回（或发生网络异常）后记录终止时间，终止时间减去起始时间就是交易耗时。
Q：如何记录交易耗时？
A：记录交易耗时是由交易线程完成的，具体情况如下：
- 调用当面付2.0支付接口之前记录起始时间；
- 返回支付成功（状态码10000）时，记录终止时间，交易状态为S；
- 返回用户处理中（状态码10003）时，记录终止时间，交易状态为I；
- 返回支付失败，则记录终止时间，交易状态F；
- 如果出现连接建立异常，则记录终止时间，交易状态为X；
- 如果出现报文上送异常，则记录终止时间，交易状态为Y；
- 如果出现报文接收异常，则记录终止时间，交易状态为Z。
所记录的交易数据通过异步线程保存在内存中，由交易保障线程每隔30分钟取出并发送。
Q：什么时候开始和结束调用交易保障接口？
A：开机或者程序启动后开始调用，每隔30分钟轮询发送，在正常关机和系统正常退出前最后调用一次交易保障接口。不可以根据绝对时间统一同步请求，需要防止所有终端同时发送请求。
Q：没有交易的时候是否需要发送心跳数据？
A：没有交易的时候也需要发送心跳数据，此时trade_info字段不传即可。
Q：我没有设备ID（equipment_id）怎么办？
A：设备ID的目的是区分商户/系统商的所有终端，可以由商户/系统商自行编号，只要能保证在同一个商户下唯一即可。
Q：什么时候传递系统商编号（sys_service_provider_id）？
A：当系统商为商户集成当面付以及交易保障接口时，需要系统商填写系统商编号（同下单并支付接口）。普通商户直接对接支付宝无需填写该参数。
