重庆长江师范学院水控对接接口

1.1文档说明

本文档用于描述了重庆长江师范学院水控对接接口api文档，供水控厂商对接参考。

1.2约定

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

2.1 账户查询

请求URL:

https://ip:port/epayapi/services/thirdparty/common/accountquery

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
cardphyid	String	二选一	查询对象的卡物理id
stuempno	String	二选一	查询对象的学号
timestamp	String	是	时间戳格式为yyyyMMddhh24miss
sign	String	是	签名
sign_method	String	是	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1

请求内容示例:

URI：https://ip:port/epayapi/services/thirdparty/common/accountquery

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

返回示例:

成功

{
	"retcode":"0",
	"retmsg":"query success",
	"stuempno":"09893092",
	"username":"王二小",
    "balance":4850,
    "cardno":103920299,
	"status":"normal",
	"timestamp":"20160606150902",
	"sign":"hjAtBGygGjFyOKEZmWdxi1tk51/xqLYTr5tm2+zQVfD1RHRzGVC9GNm4ZaXnUsHnu5o3kAZ4U32m0YNiSFpncs0pl1AnnCf1n2hhn39ruABsvD//GzkEINHjyHsnxBr44G2UhyNxplUj+s7s0a7ggjbiMk+BYC3u7VkU9/l+kZOTkEyqs+wZKumfByMZGvKVkY2c2Nr67RaSWd7bsfOJ6HYw2spvu3ptAo2RTrfCxZ0Kn5DcSDm4cagzPMZSHxB8isqqNGrdUaAU0wzzC7704iA5zze//SvCqpCJfYt0OrHOiJEN5kw1d4KESrKGMG6bezlXzAp0LbNlhl+HwZJcag==",
    "sign_method": "RSA"
}

失败

{
	"retcode":"1",
	"retmsg":"account not exsit",
	"timestamp":"20160606150902",
	"sign": "hjAtBGygGjFyOKEZmWdxi1tk51/xqLYTr5tm2+zQVfD1RHRzGVC9GNm4ZaXnUsHnu5o3kAZ4U32m0YNiSFpncs0pl1AnnCf1n2hhn39ruABsvD//GzkEINHjyHsnxBr44G2UhyNxplUj+s7s0a7ggjbiMk+BYC3u7VkU9/l+kZOTkEyqs+wZKumfByMZGvKVkY2c2Nr67RaSWd7bsfOJ6HYw2spvu3ptAo2RTrfCxZ0Kn5DcSDm4cagzPMZSHxB8isqqNGrdUaAU0wzzC7704iA5zze//SvCqpCJfYt0OrHOiJEN5kw1d4KESrKGMG6bezlXzAp0LbNlhl+HwZJcag==",
    "sign_method":"RSA"
}

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，其他为失败）
retmsg	String	返回消息
stuempno	String	学号
username	String	姓名
balance	Integer	余额(分)
cardno	Integer	卡号
status	String	状态(正常)

2.2 扣款接口

请求URL:

https://ip:port/epayapi/services/thirdparty/common/pay

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
stuempno	String	是	发起消费对象的学号
tradeno	String(32)	是	第三方系统唯一流水号
tradename	String(60)	是	交易名称
amount	Integer	是	消费金额（分）
timestamp	String	是	时间戳格式为yyyyMMddhh24miss
sign	String	是	签名
sign_method	String	是	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1

请求内容示例:

URI：https://ip:port/epayapi/services/thirdparty/common/pay

partner_id:10000
stuempno:09893092
tradeno:20160607000001
trandename:print fee
amount：2000
timestamp:20150119130901
sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
sign_method:HMAC

返回示例:

成功

{
	"retcode":"0",
	"retmsg":"success"
	"tradeno":"20160607000001",
  "balance":4850,
  "refno":"20160605190200000001",
	"timestamp":"20160606150902",
	"sign":"hjAtBGygGjFyOKEZmWdxi1tk51/xqLYTr5tm2+zQVfD1RHRzGVC9GNm4ZaXnUsHnu5o3kAZ4U32m0YNiSFpncs0pl1AnnCf1n2hhn39ruABsvD//GzkEINHjyHsnxBr44G2UhyNxplUj+s7s0a7ggjbiMk+BYC3u7VkU9/l+kZOTkEyqs+wZKumfByMZGvKVkY2c2Nr67RaSWd7bsfOJ6HYw2spvu3ptAo2RTrfCxZ0Kn5DcSDm4cagzPMZSHxB8isqqNGrdUaAU0wzzC7704iA5zze//SvCqpCJfYt0OrHOiJEN5kw1d4KESrKGMG6bezlXzAp0LbNlhl+HwZJcag==",
    "sign_method": "RSA"
}

失败

{
	"retcode":"1",
	"retmsg":"账户余额不足",
	"tradeno":"20160607000001",
	"timestamp":"20160606150902",
	"sign": "hjAtBGygGjFyOKEZmWdxi1tk51/xqLYTr5tm2+zQVfD1RHRzGVC9GNm4ZaXnUsHnu5o3kAZ4U32m0YNiSFpncs0pl1AnnCf1n2hhn39ruABsvD//GzkEINHjyHsnxBr44G2UhyNxplUj+s7s0a7ggjbiMk+BYC3u7VkU9/l+kZOTkEyqs+wZKumfByMZGvKVkY2c2Nr67RaSWd7bsfOJ6HYw2spvu3ptAo2RTrfCxZ0Kn5DcSDm4cagzPMZSHxB8isqqNGrdUaAU0wzzC7704iA5zze//SvCqpCJfYt0OrHOiJEN5kw1d4KESrKGMG6bezlXzAp0LbNlhl+HwZJcag==",
    "sign_method":"RSA"
}

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，其他为失败）
retmsg	String	返回消息
tradeno	String	第三方流水号
refno	String	本系统生成流水号
balance	Integer	余额(分)

2.3 扣款流水查询

请求URL:

https://ip:port/epayapi/services/thirdparty/common/payquery

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
stuempno	String	是	发起消费对象的学号
tradeno	String(32)	是	第三方系统唯一流水号
timestamp	String	是	时间戳格式为yyyyMMddhh24miss
sign	String	是	签名
sign_method	String	是	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1

请求内容示例:

URI：https://ip:port/epayapi/services/thirdparty/common/payquery

partner_id:10000
stuempno:09893092
tradeno:20160607000001
timestamp:20150119130901
sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
sign_method:HMAC

返回示例:

成功

{
	"retcode":"0",
	"retmsg":"success"
	"tradeno":"20160607000001",
  "balance":4850,
  "refno":"20160605190200000001",
	"tradestatus": "success",
	"paytime":"20160606150902",
	"timestamp":"20160606150902",
	"sign":"hjAtBGygGjFyOKEZmWdxi1tk51/xqLYTr5tm2+zQVfD1RHRzGVC9GNm4ZaXnUsHnu5o3kAZ4U32m0YNiSFpncs0pl1AnnCf1n2hhn39ruABsvD//GzkEINHjyHsnxBr44G2UhyNxplUj+s7s0a7ggjbiMk+BYC3u7VkU9/l+kZOTkEyqs+wZKumfByMZGvKVkY2c2Nr67RaSWd7bsfOJ6HYw2spvu3ptAo2RTrfCxZ0Kn5DcSDm4cagzPMZSHxB8isqqNGrdUaAU0wzzC7704iA5zze//SvCqpCJfYt0OrHOiJEN5kw1d4KESrKGMG6bezlXzAp0LbNlhl+HwZJcag==",
    "sign_method": "RSA"
}

失败

{
	"retcode":"0",
	"retmsg":"成功",
	"tradestatus": "fail",
	"tradeno":"20160607000001",
	"timestamp":"20160606150902",
	"sign": "hjAtBGygGjFyOKEZmWdxi1tk51/xqLYTr5tm2+zQVfD1RHRzGVC9GNm4ZaXnUsHnu5o3kAZ4U32m0YNiSFpncs0pl1AnnCf1n2hhn39ruABsvD//GzkEINHjyHsnxBr44G2UhyNxplUj+s7s0a7ggjbiMk+BYC3u7VkU9/l+kZOTkEyqs+wZKumfByMZGvKVkY2c2Nr67RaSWd7bsfOJ6HYw2spvu3ptAo2RTrfCxZ0Kn5DcSDm4cagzPMZSHxB8isqqNGrdUaAU0wzzC7704iA5zze//SvCqpCJfYt0OrHOiJEN5kw1d4KESrKGMG6bezlXzAp0LbNlhl+HwZJcag==",
    "sign_method":"RSA"
}

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，1 - 流水不存在）
retmsg	String	返回消息
tradeno	String	第三方流水号
refno	String	本系统生成流水号
tradestatus	String	交易状态, success - 成功，fail - 失败
paytime	String	支付时间，交易成功才会返回
balance	Integer	余额(分)

2.4 交易明细下载

请求URL:

https://ip:port/epayapi/services/thirdparty/common/query_bill_list

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
accdate	String	是	账单日期
pageno	String	否	页码，默认1
pagesize	String	否	每页行数,默认10，范围10-500
timestamp	String	是	时间戳格式为yyyyMMddhh24miss
sign	String	是	签名
sign_method	String	是	HMAC 加密方式为HAMC-SHA1

请求内容示例:

URI：https://ip:port/epayapi/services/thirdparty/common/query_bill_list

partner_id:10000
accdate:20190701
pageno:1
pagesize:10
timestamp:20150119130901
sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
sign_method:HMAC

返回示例:

成功

{
    "retcode": "0",
    "retmsg": "查询成功",
    "data": {
        "totalCount": 11,
        "pageSize": 10,
        "pageNo": 1,
        "list": [
            {
                "refno": "20170809160440168058",
								 "tradeno": "20170809160440168058",
                "paytime": "20170809160449",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机1",
                "aftbal": 65.21
            },
            {
                "refno": "20170809103401168050",
								 "tradeno": "20170809103401168050",
                "paytime": "20170809103413",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机3",
                "aftbal": 66.21
            },
            {
                "refno": "20170809101226168047",
								 "tradeno": "20170809101226168047",
                "paytime": "20170809101238",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机2",
                "aftbal": 67.21
            },
            {
                "refno": "20170809101217168046",
								 "tradeno": "20170809101217168046",
                "paytime": "20170809101229",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机1",
                "aftbal": 68.21
            },
            {
                "refno": "20170809100854168045",
								 "tradeno": "20170809100854168045",
                "paytime": "20170809100905",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机1",
                "aftbal": 69.21
            },
            {
                "refno": "20170809100845168043",
								 "tradeno": "20170809100845168043",
                "paytime": "20170809100824",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费",
                "billstatus": 2,
                "tradetype": "2",
                "tradecode": "6630",
                "termname":"第一食堂POS机1",
                "aftbal": 70.21
            },
            {
                "refno": "20170809100845168044",
								 "tradeno": "20170809100845168044",
                "paytime": "20170809100824",
                "billname": "IC卡消费",
                "amount": 1,
                "billtype": "联机刷卡消费撤销",
                "billstatus": 2,
                "tradetype": "1",
                "tradecode": "6632",
                "termname":"第一食堂POS机1",
                "aftbal": 71.21
            },
            {
                "refno": "20170807145900002705",
								 "tradeno": "20170807145900002705",
                "paytime": "20170807145958",
                "billname": "现金充值",
                "amount": 70,
                "billtype": "钱包充值",
                "billstatus": 2,
                "tradetype": "1",
                "tradecode": "6500",
                "termname":"第一食堂充值机1",
                "aftbal": 70.21
            }
        ],
        "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	交易参考号
tradeno	String	第三方交易流水号
paytime	String	交易时间 yyyyMMddhh24miss
billname	String	交易名称
amount	Double	交易金额(元)
billtype	String	交易类型
billstatus	String	状态 2-成功 3-失败
tradetype	String	交易方向 1-充值 2-消费
tradecode	String	交易码
termname	String	终端名称
aftbal	Double	交易后余额(元)

2.5 水控明细上传

请求URL:

https://ip:port/epayapi/services/thirdparty/common/yznu_water_record

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

用户ID、用水开始时间、用水结束时间、用水量、热水单价、实际消费金额等

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
tradeno	String	是	第三方系统唯一流水号, 主键唯一标识
stuempno	String	是	学工号
start_time	String(32)	是	开始时间，格式 YYYYMMDDHHMISS, 例如 2018年9月8日15点7分34秒表示为 20180908150734
end_time	String(32)	是	结束时间，格式同上
volumn	String(32)	是	单位升
unit_price	string(16)	是	-
device_name	string(60)	是	设备名称
pay_amount	integer	是	实际消费金额（单位分)
timestamp	String	是	时间戳格式为yyyyMMddhh24miss
sign	String	是	签名
sign_method	String	是	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，其他为失败）
retmsg	String	返回消息

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

签名方式：hmac-sha1
签名密钥由本系统统一线下提供
签名校验的通用步骤如下：
**第一步，**设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。

假设传送的参数如下：

	partner_id:10000
	stuempno:09893092
	tradeno:20160607000001
	trandename:printfee
	amount：2000
	timestamp:20150119130901
	sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
	sign_method:HMAC

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

	amount=2000&partner_id=10000&sign_method=HMAC&stuempno=09893092
	&timestamp=20150119130901&tradeno=20160607000001&trandename=printfee

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

参数名ASCII码从小到大排序（字典序）；
如果参数的值为空不参与签名；
参数名区分大小写；
传送的sign参数不参与签名，用该sign值作校验。
**第二步，**用密钥secretkey对stringA字符串，进行hmac-sha1签名，得到sign值signValue。signValue最后采用十六进制小写hex编码生成签名字符串。

附录B-服务端返回数据RSA签名校验算法

签名方式：SHA1withRSA
签名校验的公钥key为本系统统一线下提供。
签名校验的通用步骤如下：

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

特别注意以下重要规则：

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

**第二步，**对sign值进行base64解码，用本系统提供的公钥key对sign签名值解码后的数据基于stringA字符串，进行SHA1withRSA签名验证

举例：

假设传送的参数如下：

retcode:1
retmsg:账户余额不足
timestamp:20160513155100
sign_mehtod:RSA

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

retcode=1&retmsg=账户余额不足&timestamp=20160513155100&sign_mehtod=RSA