---

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

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

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

背景

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

服务地址 http(s)://ip:port/epayapi/websocket/devlogin

接口

1 创建WebSocket连接

• 从Client发起请求

  • action : 请求业务, "login"
  • needresp: 是否必须应答
  • requestid: 请求ID
  • data: 数据域

参数	说明	备注
clientid	clientid	客户端生成临时ID
local_time	本地时间	YYYYMMDDHH24MISS
devphyid	设备物理ID	如果不是终端设备，没有这个域
appid	appid	应用 ID
sign	签名	用 appsecret 对 appid + clientid + local_time 进行签名

{
    "action": "login",
    "needresp: true,
    "requestid": "21232",
    "data": {
        "clientid": "123fabfdef19f",
        "local_time": "20170427132134",
        "devphyid": "10000008"，
        "appid": "1000004",
        "sign": "83deea0c396c3fee2176c84d9d8505adaf1e34a5"
    }
}

• 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	交易参考号	服务端交易初始化成功后生成
stuempno	学工号	进行支付的学工号
custname	姓名	进行支付的学生姓名
payamt	交易金额	POS输入交易金额
amount	实际支付金额	包含搭伙费金额

{
    "action": "qrpay_in_process",
    "needresp": true,
    "requestid": "5656565",
    "data": {
        "clientid": "123fabfdef19f",
        "refno": "20170427132134000001",
        "devphyid": "10000008",
        "stuempno": "20140001",
        "custname": "张三",
        "payamt": 100,
        "amount": 110
    }

}

• 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"
    }
}

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"
    }
}