文档中心 > 开放平台

交易保障接口

更新时间:2017/01/09 访问次数:3277

接口名称: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——收银机;

  • STORE——门店;

  • VM——售卖

不可空

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——打印机异常;

  • HE_SCANER——扫描枪异常;

  • HE_OTHER——其他硬件异常

可空

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——交易成功;
  • I-支付宝返回支付处理中;
  • F——支付宝返回失败;
  • P——商户收银系统失败;
  • X——建立连接异常;
  • Y——报文上送异常;
  • Z——报文接收异常
不可空 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"}&timestamp=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

无效签名

签名错误或者签名方式有误

重新检查签名方式后,再调用。

TIPS:此接口数据设备接入时请勿依赖或影响交易主链路。当支付宝处理完成后,支付宝会以json同步返回数据的形式,把数据反馈给商户网站。商户可以利用编程方法来模拟http请求远程解析json获得处理的结果数据,增加商户的业务逻辑处理程序。此时,商户必须判断商户网站中是否已经对该次的结果数据做过同样处理。如果不判断,存在潜在的风险,商户自行承担因此而产生的所有损失。

使用SDK快速接入

交易保障接口monitor.heartbeat.syn:

//获得初始化的AlipayClient
AlipayClient alipayClient = new DefaultAlipayClient(http://mcloudmonitor.com/gateway.do
       ,"2014111122223333" // appid
      ,"RSA private key" // RSA私钥
   ,"json","GBK"
);
//创建API对应的request类
MonitorHeartbeatSynRequest request = new MonitorHeartbeatSynRequest();
request.setBizContent("{" +
   "     \"product\":\"FP\"," +
   "     \"type\":\"CR\"," +
   "     \"equipment_id\":\"cr1000001\"," +
   "   \"time\":\"2015-01-22 16:46:02\"," +
   "     \"store_id\":\"store10001\"," +
   "     \"network_type\":\"LAN\"," +
   "     \"sys_service_provider_id\":\"2088123412341234\"," +
   "   \"trade_info\":[{" +
   "         \"OTN\":\"00000001\"," +
   "         \"TC\":\"5\"," +
   "      \"STAT\":\"K\"" +
   "       }]" +
   " }");
MonitorHeartbeatSynResponse response = alipayClient.execute(request);
//通过alipayClient调用API,获得对应的response类
// TODO 根据response中的结果继续业务逻辑处理

 关键入参:

   参数

参数

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:当系统商为商户集成当面付以及交易保障接口时,需要系统商填写系统商编号(同下单并支付接口)。普通商户直接对接支付宝无需填写该参数。

FAQ

关于此文档暂时还没有FAQ
返回
顶部