title: 一卡通v5平台WebSocket协议接口 date: 2017-04-27 13:45:23 tags:

一卡通v5平台WebSocket协议接口文档

日期	版本	说明
2017-4-27	V1.0	草稿

背景

一卡通平台所有终端设备，包括食堂POS、车载机、考勤机和前置等应用端需要能接收从服务端推送过来的数据，并完成相关业务。这些接入终端等都是Client。

接口

1 创建WebSocket连接

从Client发起请求
- action : 请求业务, "login"
- needresp: 是否必须应答
- requestid: 请求ID
- data: 数据域

参数	说明	备注
clientid	clientid	客户端生成临时ID
local_time	本地时间	YYYYMMDDHH24MISS
devphyid	设备物理ID

{
    "action": "login",
    "needresp: true,
    "requestid": "21232",
    "data": {
        "clientid": "123fabfdef19f",
        "local_time": "20170427132134",
        "devphyid": "10000008"
    }
}

server端返回数据
- action : 请求业务, "login"
- retcode: 响应码
- retmsg: 返回信息
- requestid: 请求ID

参数	说明	备注
host_time	主机时间	服务端返回系统时间
clientid	clientid	服务端原值返回

{
    "action": "login",
    "retcode": 0,
    "retmsg": "成功",
    "requestid": "21232",
    "data": {
        "clientid": "123fabfdef19f",
        "host_time": "20170427132135"
    }
}

2 扫码付中间过程请求

在扫码付业务流程中，当用户手机扫描二维码并成功请求二维码中的支付URL，服务端向对应Client 推送通知信息，Client 接收到这个返回后完成对应的业务流程

Server 端发起请求
- action: 请求业务， "qrpay_in_process"
- needresp: 是否必须应答
- requestid: 请求ID
- data: 数据域

参数	说明	备注
devphyid	devphyid	设备ID号
refno	交易参考号	服务端交易初始化成功后生成

{
    "action": "qrpay_in_process",
    "needresp": true,
    "requestid": "5656565",
    "data": {
        "clientid": "123fabfdef19f",
        "refno": "20170427132134000001",
        "devphyid": "10000008"
    }

}

client端返回数据
- action: 请求业务， "qrpay_in_process"
- retcode: 响应码
- retmsg: 返回信息
- requestid: 请求ID

参数	说明	备注
host_time	主机时间	服务端返回系统时间
clientid	clientid	服务端原值返回

{
    "action": "qrpay_in_process",
    "retcode": 0,
    "retmsg": "成功",
    "requestid": "5656565",
    "data": {
        "devphyid": "10000008",
        "stuempno": "20140001",
        "custname": "张三"
    }
}

3 扫码付完成请求

当用户手机扫描付完成付款业务后，由Server端推送通知给Client。

Server 端发起
- action: "qrpay_finish"
- needresp: 是否必须应答
- requestid: 请求ID
- data: 数据域

参数	说明	备注
devphyid	devphyid	设备ID号
refno	交易参考号	服务端交易初始化成功后生成
status	交易状态	succ: 成功， cancel: 取消
fail_reason	交易取消原因	当交易取消时存在
stuempno	支付用户学号	当交易成功时存在
custname	支付用户名	当交易成功时存在
amount	支付金额	单位分，当交易成功时存在
availbal	账户可用余额	单位分，当交易成功时存在

{
    "action": "qrpay_finish",
    "needresp": true,
    "requestid": "12345566",
    "data": {
        "refno": "20170427132134000001",
        "devphyid": "10000008",
        "status": "succ",
        "stuempno": "2014001",
        "custname" : "张三",
        "amount": 110,
        "availbal": 9420
    }
}

Client 端应答
- action: 请求业务， "qrpay_finish"
- retcode: 响应码
- retmsg: 返回信息
- requestid: 请求ID

参数	说明	备注
devphyid	devphyid	设备ID号
refno	交易参考号	服务端交易初始化成功后生成

{
    "action": "qrpay_finish",
    "retcode": 0,
    "retmsg": "成功",
    "requestid": "12345566",
    "data": {
        "devphyid": "10000008",
        "refno": "20170427132134000001"
    }
}