title: 一卡通v5 App 接口文档 date: 2017-07-13 09:09:48 tags:

修订历史

版本作者日期备注
V4.0.0何林青2015-01-06初稿
v4.0.1汤成2016-3-16增加设备相关接口

前言

编写目的

本文档用于描述了易支付对外提供的所有api接口，包括提供手机app端和pos消费端，供内部业务依据此接口开发提供参考。

约定

  1. 传输编码统一utf-8

接口描述

1. 手机api功能入口

1.1 注册绑定服务

Uri: https://ip:port/epayapi/services/bindservice

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
uidString是从终端获取的唯一号
phoneString否手机号
schoolString是学校代码
useridString是学号
usernameString是姓名
idnoString是身份证后六位
timestampString是手机时间戳
platformString是手机平台android/ios

例子:

URI：https://ip:port/epayapi/services/bindservice

uid:12309487839029

phone:15089039087

school:01

userid:09893092

username:王小二

idno:092010

timestamp:2015-01-19 13:09:01

platform:android

返回：

返回格式：application/json

{

"timestamp": "2015-01-19 16:25:29",

"uid": "12309487839029",

"gid": "10000021",

"rsapbulic": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCG3ADBVO/ngyMGlIZ6LM62CXrmBQ/lvuo6u/03\r\namCFHgxBC9U0E+AawCgf4tgVOzePxlmqqkFgh2NIySAL9e2qcqvUa2a3jjutAdmamfo6raofnr9G\r\nf6hO1LZp7NRR0cXgojJyXkTRvDdkR46ZUydMng2AXm6jNr1Sdg643OQ83QIDAQAB\r\n",

"isfirstreg": false,

"ispwdset": false

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.2 登录密码初始设置

Uri: https://ip:port/epayapi/services/auth/pwdset

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gidString是客户端号
pwdString是密码
dpwdString是重复密码

例子:

URI：https://ip:port/epayapi/services*/auth*/pwdset

gid:10000001

pwd:123456

dpwd:123456

返回：

返回格式：application/json

{

"retcode":"0",

"retmsg":"设置成功"

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.3登录密码重置

Uri: https://ip:port/epayapi/services/auth/pwdreset

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gidString是客户端号
opwdString是原始密码
pwdString是密码
dpwdString是重复密码

例子:

URI：https://ip:port/epayapi/services*/auth*/pwdset

gid:10000001

opwd:654321

pwd:123456

dpwd:123456

返回：

返回格式：application/json

{

"retcode":"0",

"retmsg":"重置成功"

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.4登录-设备授权码

Uri: https://ip:port/epayapi/services/oauth2/device

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
client_idString是客户端标识,统一分配给平台指定客户端id
typeString是类型 device_code/device_token
codeString否验证码

例子:

URI：https://ip:port/epayapi/services/oauth2/device

Client_id:a9020b039900d9001

type:device_code

返回：

返回格式：application/json

{

"retcode":"0",

“code”:255409389383939

“userCode”:1234,

verifyURL:”/user/code”

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.5登录-oauth授权

Uri: https://ip:port/epayapi/services/oauth2/authlogin

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
uidString是客户端唯一识别码
gidString是终端编号
schoolString否学校代码
useridString是学工号
pwdString是密码
usercodeString否验证码
platformString否手机平台

例子:

URI：https://ip:port/epayapi/services/oauth2/authlogin

uid:12309487839029

gid:2000100002020101

school:01

userid:09893092

pwd:123456

usercode:092010

platform:android

返回：

返回格式：application/json

{

"retcode":"0",

“gid”:2001902902909,

“accname”:”小二”,

“token”:abcde32423523cabb434,

“expiresin”:149059504,

“schoolcode”:”01”

“secretkey”:iosdkfjhs9293i98421kljsjflksjfd

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.6电控校区查询

Uri: https://ip:port/epayapi/services/elecfee/queryarea

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述

例子:

URI：https://ip:port/epayapi/services/elecfee/queryarea

返回：

返回格式：application/json

{

["areaId":"1",

"areaName":"A校区"]，["areaId":"2",

"areaName":"B校区"]

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.7电控区域查询

Uri: https://ip:port/epayapi/services/elecfee/querydistricts

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
areaId校区id是

例子:

URI：https://ip:port/epayapi/services/elecfee/querydistricts

areaId:1

返回：

返回格式：application/json

{

["districtId":"101",

" districtName":"A区域"]，["districtId ":"102",

"districtName ":"B区域"]

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.8电控楼栋查询

Uri: https://ip:port/epayapi/services/elecfee/querybuilds

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
areaId校区id是
districtId区域id是

例子:

URI：https://ip:port/epayapi/services/elecfee/querybuilds

areaId:1

districtId:102

返回：

返回格式：application/json

{

["buildId":"101",

" buildName":"al楼"]，["buildId ":"102",

"buildName ":"B1楼"]

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.9电控楼层查询

Uri: https://ip:port/epayapi/services/elecfee/queryfloors

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
areaId校区id是
districtId区域id是
buildId楼栋id是

例子:

URI：https://ip:port/epayapi/services/elecfee/queryfloors

areaId:1

districtId:101

buildId:3001

返回：

返回格式：application/json

{

["floorId":"101",

" floorName":"1楼"]，["floorId ":"102",

"floorName ":"2楼"]

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.10电控房间查询

Uri: https://ip:port/epayapi/services/elecfee/queryrooms

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
areaId校区id是
districtId区域id是
buildId楼栋id是
floorId楼层id是

例子:

URI：https://ip:port/epayapi/services/elecfee/queryrooms

areaId:1

districtId:101

buildId:3001

floorId:1

返回：

返回格式：application/json

{

["roomId":"101",

" roomName":"301"]，["roomId ":"102",

"roomName ":"302"]

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.11电控房间电量信息查询

Uri: https://ip:port/epayapi/services/elecfee/queryroominfo

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
areaId校区id是
buildId楼栋id是
roomId房间id是

例子:

URI：https://ip:port/epayapi/services/elecfee/queryroominfo

areaId:1

buildId:3001

roomId:1

返回：

返回格式：application/json

{"areaId":"1",

“buildId”:3001,

“roomId”:1,

" roomName":"301",

“restElecDegree”:20.9

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.12电控房间电量信息查询

Uri: https://ip:port/epayapi/services/elecfee/buyelectrity

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
areaId校区id是
buildId楼栋id是
roomId房间id是
amount充值金额是单位元
gid客户端唯一标识是
payrouteid支付途径id是
paypwd支付密码是

例子:

URI：https://ip:port/epayapi/services/elecfee/queryroominfo

areaId:1

buildId:3001

roomId:1

amount:10.4

gid:10000001

payrouteid:1

paypwd:123456

返回：

返回格式：application/json

{"retcode":"0",

“retmsg”:”充值成功”

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.13账户信息查询

Uri: https://ip:port/epayapi/services/account/getaccountinfo

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gid客户端唯一标识是
userid学号是

例子:

URI：https://ip:port/epayapi/services/account/getaccountinfo

gid:10000014

userid:098298192

返回：

返回格式：application/json

{ “accno”:1

“accname“:”212”,

“status“:1,

“balance“:105,

“availbal“:105,

“frozebal“:0,

“opendate“:”20140509”,

“closedate”:null,

“timelimit“:50,

“daylimit“:100，

Bankcards:1

Schoolcards:1

Schoolcollege:”A学院”

Schoolprofessional:”武警”

Schoolclass:”101”

Mobile:”129839383993”

Email:”sdkfj@kjsdf.com”

Sex:”男”

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.14账单列表查询

Uri: https://ip:port/epayapi/services/billservice/getbilldata

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gid客户端唯一标识是
pageNo页码是
billtype账单类型是EPAY/YKT

例子:

URI：https://ip:port/epayapi/services/billservice/getbilldata

gid:10000014

pageNo:1

billtype:”EPAY”

返回：

返回格式：application/json

{[

“refno“:20392103929303，

“paytime“:20150802091029，

“billname“:”pos消费”,

“amount“:”10.9”,

“billtype“:”EPAY”,

“billstatus“:”2”,

“tradetype”:2],

[

“refno“:20392103929303,

“paytime“:20150802091029,

“billname“:”pos消费”,

“amount“:”10.9”,

“billtype“:”EPAY”,

“billstatus“:”2”,

“tradetype”:2],

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.15账单明细查询

Uri: https://ip:port/epayapi/services/billservice/getbilldetail

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gid客户端唯一标识是
refno参考号是
billtype账单类型是EPAY/YKT

例子:

URI：https://ip:port/epayapi/services/billservice/getbilldetail

gid:10000014

refno:”2013040192029192”

billtype:”EPAY”

返回：

返回格式：application/json

{

“refno“:20392103929303

“paytime“:20150802091029

“billname“:”pos消费”

“amount“:”10.9”

“billtype“:”EPAY”

“billstatus“:”2”,

“organname”:”财务处”,

“paidmethod”:”卡余额”,

“tradetype”:2}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.16挂失卡查询

Uri: https://ip:port/epayapi/services/ykt/cardlist

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gid客户端唯一标识是

例子:

URI：https://ip:port/epayapi/services/ykt/cardlist

gid:10000014

返回：

返回格式：application/json

[{

“cardno“:100092

“cardphytypename“:cpu卡

}]

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.17卡挂失

Uri: https://ip:port/epayapi/services/ykt/cardloss

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gid客户端唯一标识是
cardno卡号是
cardpwd卡密码是

例子:

URI：https://ip:port/epayapi/services/ykt/cardloss

gid:10000014

cardno:”100092”

cardpwd:”111111”

返回：

返回格式：application/json

{

“retcode“:0，

“retmsg“:”挂失成功”

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.18圈存银行卡列表查询

Uri: https://ip:port/epayapi/services/charge/bankcard/list

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gid客户端唯一标识是
payroute充值方式是

例子:

URI：https://ip:port/epayapi/services/charge/bankcard/list

gid:10000014

payroute:”1”

返回：

返回格式：application/json

[{

“bankcardno“:1002920192393909，

“bankname“:”中国银行”，

}]

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.19充值初始化

Uri: https://ip:port/epayapi/services/charge/term/init

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gid客户端唯一标识是
payroute充值方式是
amount充值金额是

例子:

URI：https://ip:port/epayapi/services/charge/term/init

gid:10000014

payroute:”1”

amount:”10.4”

返回：

返回格式：application/json

{

“retcode“:0，

“retmsg“:”初始化成功”，

“refno”:”20140809120901000001”

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.20圈存充值

Uri: https://ip:port/epayapi/services/charge/term/qctrans

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gid客户端唯一标识是
payroute充值方式是
amount充值金额是
refno参考号是
paypwd支付密码是

例子:

URI：https://ip:port/epayapi/services/charge/term/qctrans

gid:10000014

payroute:”1”

amount:”10.4”

refno:”20140902103001000001”

paypwd:123456

返回：

返回格式：application/json

{

“retcode“:0，

“retmsg“:”充值成功”，

“refno”:”20140809120901000001”

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误

1.21圈存充值结果查询

Uri: https://ip:port/epayapi/services/charge/term/qcresultquery

请求格式：application/x-www-form-urlencoded

请求方式：post

参数：

名称类型是否必须描述
gid客户端唯一标识是
payroute充值方式是
amount充值金额是
refno参考号是

例子:

URI：https://ip:port/epayapi/services/charge/term/qcresultquery

gid:10000014

payroute:”1”

amount:”10.4”

refno:”20140902103001000001”

返回：

返回格式：application/json

{

“retcode“:0，

“retmsg“:”交易成功”，

“refno”:”20140809120901000001”

“successtime”:2014-05-05 10:43:29

}

异常信息：

HTTP 错误码英文索引中文消息
400SC_BAD_REQUEST请求信息不完整
400SC_BAD_REQUEST请求时间戳错误,格式为：yyyyMMddHHmmss
401SC_UNAUTHORIZED密码验证错误