source/_posts/一卡通v5对接银联电子校园卡接口文档.md

约定

传输编码统一为utf-8
RSA 加密算法为本接口采用的非对称加密算法，SIGN_ALGORITHMS ="SHA1WithRSA";
RSA公钥由本系统提供，本系统返回信息的签名数据，第三方系统得到后通过公钥校验算法，验证返回数据的合法性
HMAC加密算法为用户请求本系统采用的加密算法，SIGN_ALGORITHMS ="HMAC-SHA1";
具体签名生成参考后面的签名章节
retcode等于0表示成功，非0表示失败，失败具体信息查看retmsg

电子校园卡绑定

请求URL:

http(s)://ip:port/epayapi/services/thirdparty/unionpay/ecardbind

请求方式/格式:

post
content-type: application/x-www-form-urlencoded

请求参数

参数名	类型	必传	备注
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
schoolcode	String	是	学校代码
stuempno	String	是	学工号
custname	String	是	姓名
idtype	String	否	证件类型
idno	String	否	证件号
mobile	String	否	手机号
timestamp	String	是	时间戳 yyyyMMddHHmmss
sign_method	String	是	`HMAC`
sign	String	是	签名

返回参数

参数名	类型	必传	备注
retcode	String	是	0-成功；其他失败
retmsg	String	是	错误信息
ecardno	String	否	电子校园卡卡号，成功时必传
ecardaccno	String	否	电子校园卡账号，成功时必传

电子校园卡解绑

请求URL:

http(s)://ip:port/epayapi/services/thirdparty/unionpay/ecardunbind

请求方式/格式:

post
content-type: application/x-www-form-urlencoded

请求参数

参数名	类型	必传	备注
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
schoolcode	String	是	学校代码
ecardno	String	是	电子校园卡号
timestamp	String	是	时间戳 yyyyMMddHHmmss
sign_method	String	是	`HMAC`
sign	String	是	签名

返回参数

参数名	类型	必传	备注
retcode	String	是	0-成功；其他失败
retmsg	String	是	错误信息

账户余额查询

请求URL:

http(s)://ip:port/epayapi/services/thirdparty/common/accountquery

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
stuempno	String	是	用户唯一号（学工号）。与卡片物理ID必传一项
useridtype	String	否	指定用户唯一号值的类型。`STUEMPNO`-stuempno为学工号；`CARDPHYID`-stuempno为卡物理ID；`ECARDNO`-电子校园卡号；为空时默认stuempno为学工号
timestamp	String	是	时间戳格式为yyyyMMddhh24miss
sign	String	是	签名
sign_method	String	是	固定填： HMAC （加密方式为HAMC-SHA1）

请求内容示例:


- URI：http(s)://ip:port/epayapi/services/thirdparty/common/accountquery
- partner_id:10000
- stuempno:09893092
- timestamp:20150119130901
- sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
- sign_method:HMAC

返回示例:

成功

{
    "retcode": "0",
    "retmsg": "query success",
    "status": "normal",
    "balance": 5040,
    "frozenbal": 0,
    "expiredate": "20300801",
    "onceTimeLimit": 3000,
    "dayTotalLimit": 20000
}

失败

{
    "retcode": "51",
    "retmsg": "card is lost"
}

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，其他为失败）
retmsg	String	返回消息
status	String	状态 normal 正常，其他返回错误
balance	Integer	余额(分)
frozenbal	Integer	冻结金额（分）
expiredate	String	卡有效期
onceTimeLimit	Integer	单次消费最高限额(分)，超出要输卡密码
dayTotalLimit	Integer	当天累计消费限额（分），超出要输入卡密码

通用账户流水查询

请求URL:

http（s）://ip:port/epayapi/services/thirdparty/common/getbilldata

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
stuempno	String	是	查询对象的唯一号（学工号）
useridtype	String	否	指定用户唯一号值的类型。`STUEMPNO`-stuempno为学工号；`CARDPHYID`-stuempno为卡物理ID；`ECARDNO`-电子校园卡号；为空时默认stuempno为学工号
pageno	String	否	页码，默认1
pagesize	String	否	每页行数,默认10，范围10-500
startdate	String	是	开始时间格式yyyyMMdd 最多3个月前
enddate	String	是	结束日期格式yyyyMMdd
timestamp	String	是	时间戳格式为yyyyMMddhh24miss
sign	String	是	签名
sign_method	String	是	HMAC 加密方式为HAMC-SHA1

请求内容示例:


- URI：http(s)://ip:port/epayapi/services/thirdparty/common/getbilldata
- partner_id:10000
- pageno:1
- pagesize:10
- startdate:20150829
- enddate:20150929
- timestamp:20150119130901
- sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
- sign_method:HMAC

返回示例:

成功

{
    "retcode": "0",
    "retmsg": "查询成功",
    "data": {
        "totalCount": 11,
        "pageSize": 10,
        "pageNo": 1,
        "list": [
            {
                "refno": "20170809160440168058",
                "paytime": "20170809160449",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机1"
            },
            {
                "refno": "20170809103401168050",
                "paytime": "20170809103413",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机3"
            },
            {
                "refno": "20170809101226168047",
                "paytime": "20170809101238",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机2"
            },
            {
                "refno": "20170809101217168046",
                "paytime": "20170809101229",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机1"
            },
            {
                "refno": "20170809100854168045",
                "paytime": "20170809100905",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机1"
            },
            {
                "refno": "20170809100845168043",
                "paytime": "20170809100824",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机1"
            },
            {
                "refno": "20170809100845168044",
                "paytime": "20170809100824",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费撤销",
                "billstatus": 2,
                "tradetype": "1",
                "tradecode": "6632",
                "termname":"第一食堂POS机1"
            },
            {
                "refno": "20170807145900002705",
                "paytime": "20170807145958",
                "billname": "现金充值",
                "amount": 270,
                "billtype": "钱包充值",
                "billstatus": 2,
                "tradetype": "1",
                "tradecode": "6500",
                "termname":"第一食堂充值机1"
            }
        ],
        "firstResult": 0,
        "totalPage": 2,
        "firstPage": true,
        "lastPage": false,
        "nextPage": 2,
        "prePage": 1
    }
}

失败

{
    "retcode": "304",
    "retmsg": "签名验证失败",
    "data": null
}

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，其他为失败）
retmsg	String	返回消息
data	list	流水明细集合

流水明细说明:

参数名	类型	说明
refno	String	交易参考号
paytime	String	交易时间 yyyyMMddhh24miss
billname	String	交易名称
amount	Integer	交易金额(元)
billtype	String	交易类型
billstatus	String	状态 2-成功 3-失败
tradetype	String	交易方向 1-充值 2-消费
tradecode	String	交易码
termname	String	终端名称

附录A-用户请求HMAC签名算法

签名方式：hmac-sha1
签名密钥由本系统统一线下提供

签名校验的通用步骤如下：

第一步: 设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

假设传送的参数如下：

	partner_id:10000
	openid:xv909vsfijksf9912
	stuempno:09893092
	timestamp:20150119130901
	sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
	sign_method:HMAC

对参数按照key=value的格式，并按照参数名ASCII字典序排序如下：

	openid=xv909vsfijksf9912&partner_id=10000&sign_method=HMAC&stuempno=09893092&timestamp=20150119130901

** 特别注意以下重要规则：**

参数名ASCII码从小到大排序（字典序）；
如果参数的值为空不参与签名；
参数名区分大小写；
传送的sign参数不参与签名，用该sign值作校验。

第二步: 用密钥secretkey对stringA字符串，进行hmac-sha1签名，得到sign值signValue。signValue最后采用十六进制小写hex编码生成签名字符串。