source/_posts/一卡通v5第三方数据对接接口文档.md

title: 一卡通v5第三方数据对接接口文档 date: 2016-06-21 13:54:26 tags:

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/single/custcardinfo

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

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

请求内容示例:

URI：https://ip:port/epayapi/services/thirdparty/common/single/custcardinfo

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

返回示例:

成功

{
    "retcode": "0",
    "retmsg": "查询成功",
    "data": [
        {
            "stuempno": "2012135138",
            "custname": "徐晨",
            "cardno": 900,
            "cardstatus": 1,
            "showcardno": "0000006271",
            "cardphyid": "540DB1E3",
            "expiredate": "20160801",
            "opendate": "20150901",
            "cardverno": "150901001789",
            "cardtype": 1,
            "cardtypename": "正式卡",
            "custid": 2001393,
            "custtype": 3,
            "custtypename": "学生",
            "deptcode": "1",
            "deptname": "上海**学院",
            "specialtycode": "0",
            "specialtyname": null,
            "sex": "1",
            "idtype": "1",
            "idtypename": "身份证",
            "idno": "310108199********3",
            "areacode": "2",
            "areaname": "浦东校区",
            "classcode": null,
            "countrycode": "0",
            "country": null,
            "email": null,
            "nationcode": "0",
            "nation": "汉族",
            "tel": null,
            "mobile": null,
            "zipcode": null,
            "cardupdtime": "20150901135222",
            "custupdtime": "20150901135222"
        }
    ]
}

失败

{
	"retcode":"1",
	"retmsg":"账户不存在"
}

返回参数说明:

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

2.2 通用卡、账户信息查询-批量接口

请求URL:

https://ip:port/epayapi/services/thirdparty/common/batch/custcardinfo

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
pageno	String	否	页码，默认1
pagesize	String	否	每页行数,默认10，范围10-500
cardupdtime	String	否	卡最后更新时间（二选一）
custupdtime	String	否	客户最后更新时间（二选一）
timestamp	String	是	时间戳格式为yyyyMMddhh24miss
sign	String	是	签名
sign_method	String	是	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1

请求内容示例:

URI：https://ip:port/epayapi/services/thirdparty/common/batch/custcardinfo

partner_id:10000
pageno:1
pagesize:100
cardupdtime:20150829145802
timestamp:20150119130901
sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
sign_method:HMAC

返回示例:

成功

{
    "retcode": "0",
    "retmsg": "查询成功",
    "data": null,
    "page": {
        "totalCount": 10700,
        "pageSize": 10,
        "pageNo": 1,
        "list": [
            {
                "stuempno": "2012127213",
                "custname": "时妍婧",
                "cardno": 1767,
                "cardstatus": 1,
                "showcardno": "0000002103",
                "cardphyid": "540F38B3",
                "expiredate": "20160801",
                "opendate": "20150901",
                "cardverno": "150901003521",
                "cardtype": 1,
                "cardtypename": "正式卡",
                "custid": 2000907,
                "custtype": 3,
                "custtypename": "学生",
                "deptcode": "1",
                "deptname": "上海**学院",
                "specialtycode": "0",
                "specialtyname": null,
                "sex": "2",
                "idtype": "1",
                "idtypename": "身份证",
                "idno": "3702851*********",
                "areacode": "2",
                "areaname": "浦东校区",
                "classcode": null,
                "countrycode": "0",
                "country": null,
                "email": null,
                "nationcode": "0",
                "nation": "汉族",
                "tel": null,
                "mobile": null,
                "zipcode": null,
                "cardupdtime": "20150901143334",
                "custupdtime": "20150901143334"
            },
            {
                "stuempno": "2012145107",
                "custname": "汪珍霞",
                "cardno": 1779,
                "cardstatus": 1,
                "showcardno": "0000002340",
                "cardphyid": "54101943",
                "expiredate": "20160801",
                "opendate": "20150901",
                "cardverno": "150901003545",
                "cardtype": 1,
                "cardtypename": "正式卡",
                "custid": 2001795,
                "custtype": 3,
                "custtypename": "学生",
                "deptcode": "1",
                "deptname": "上海**学院",
                "specialtycode": "0",
                "specialtyname": null,
                "sex": "2",
                "idtype": "1",
                "idtypename": "身份证",
                "idno": "3702851*********",
                "areacode": "2",
                "areaname": "浦东校区",
                "classcode": null,
                "countrycode": "0",
                "country": null,
                "email": null,
                "nationcode": "0",
                "nation": "汉族",
                "tel": null,
                "mobile": null,
                "zipcode": null,
                "cardupdtime": "20150901143411",
                "custupdtime": "20150901143411"
            },
            {
                "stuempno": "2012127218",
                "custname": "高秋依",
                "cardno": 1781,
                "cardstatus": 1,
                "showcardno": "0000002098",
                "cardphyid": "540FA163",
                "expiredate": "20160801",
                "opendate": "20150901",
                "cardverno": "150901003550",
                "cardtype": 1,
                "cardtypename": "正式卡",
                "custid": 2000912,
                "custtype": 3,
                "custtypename": "学生",
                "deptcode": "1",
                "deptname": "上海**学院",
                "specialtycode": "0",
                "specialtyname": null,
                "sex": "2",
                "idtype": "1",
                "idtypename": "身份证",
                "idno": "3702851*********",
                "areacode": "2",
                "areaname": "浦东校区",
                "classcode": null,
                "countrycode": "0",
                "country": null,
                "email": null,
                "nationcode": "0",
                "nation": "汉族",
                "tel": null,
                "mobile": null,
                "zipcode": null,
                "cardupdtime": "20150901143419",
                "custupdtime": "20150901143419"
            },
            {
                "stuempno": "2012145110",
                "custname": "邱婷",
                "cardno": 1783,
                "cardstatus": 1,
                "showcardno": "0000002337",
                "cardphyid": "540C7BA3",
                "expiredate": "20160801",
                "opendate": "20150901",
                "cardverno": "150901003553",
                "cardtype": 1,
                "cardtypename": "正式卡",
                "custid": 2001798,
                "custtype": 3,
                "custtypename": "学生",
                "deptcode": "1",
                "deptname": "上海**学院",
                "specialtycode": "0",
                "specialtyname": null,
                "sex": "2",
                "idtype": "1",
                "idtypename": "身份证",
                "idno": "3702851*********",
                "areacode": "2",
                "areaname": "浦东校区",
                "classcode": null,
                "countrycode": "0",
                "country": null,
                "email": null,
                "nationcode": "0",
                "nation": "汉族",
                "tel": null,
                "mobile": null,
                "zipcode": null,
                "cardupdtime": "20150901143425",
                "custupdtime": "20150901143425"
            },
            {
                "stuempno": "2012145111",
                "custname": "汪逸馨",
                "cardno": 1785,
                "cardstatus": 1,
                "showcardno": "0000002336",
                "cardphyid": "540FDD33",
                "expiredate": "20160801",
                "opendate": "20150901",
                "cardverno": "150901003557",
                "cardtype": 1,
                "cardtypename": "正式卡",
                "custid": 2001799,
                "custtype": 3,
                "custtypename": "学生",
                "deptcode": "1",
                "deptname": "上海**学院",
                "specialtycode": "0",
                "specialtyname": null,
                "sex": "2",
                "idtype": "1",
                "idtypename": "身份证",
                "idno": "3702851*********",
                "areacode": "2",
                "areaname": "浦东校区",
                "classcode": null,
                "countrycode": "0",
                "country": null,
                "email": null,
                "nationcode": "0",
                "nation": "汉族",
                "tel": null,
                "mobile": null,
                "zipcode": null,
                "cardupdtime": "20150901143430",
                "custupdtime": "20150901143430"
            },
            {
                "stuempno": "0823",
                "custname": "殷林森",
                "cardno": 11267,
                "cardstatus": 1,
                "showcardno": "0000021032",
                "cardphyid": "540F8A03",
                "expiredate": "20990801",
                "opendate": "20151010",
                "cardverno": "151010000274",
                "cardtype": 1,
                "cardtypename": "正式卡",
                "custid": 2007087,
                "custtype": 2,
                "custtypename": "教工",
                "deptcode": "129",
                "deptname": "国际**学院",
                "specialtycode": "0",
                "specialtyname": null,
                "sex": "0",
                "idtype": "0",
                "idtypename": null,
                "idno": null,
                "areacode": "2",
                "areaname": "浦东校区",
                "classcode": null,
                "countrycode": "0",
                "country": null,
                "email": null,
                "nationcode": "0",
                "nation": null,
                "tel": null,
                "mobile": null,
                "zipcode": null,
                "cardupdtime": "20151010140928",
                "custupdtime": "20151010140928"
            },
            {
                "stuempno": "2012121242",
                "custname": "顾承阳",
                "cardno": 1586,
                "cardstatus": 1,
                "showcardno": "0000004005",
                "cardphyid": "540C6533",
                "expiredate": "20160801",
                "opendate": "20150901",
                "cardverno": "150901003160",
                "cardtype": 1,
                "cardtypename": "正式卡",
                "custid": 2000091,
                "custtype": 3,
                "custtypename": "学生",
                "deptcode": "1",
                "deptname": "上海**学院",
                "specialtycode": "0",
                "specialtyname": null,
                "sex": "1",
                "idtype": "1",
                "idtypename": "身份证",
                "idno": "3702851*********",
                "areacode": "2",
                "areaname": "浦东校区",
                "classcode": null,
                "countrycode": "0",
                "country": null,
                "email": null,
                "nationcode": "0",
                "nation": "汉族",
                "tel": null,
                "mobile": null,
                "zipcode": null,
                "cardupdtime": "20150901142422",
                "custupdtime": "20150901142422"
            },
            {
                "stuempno": "0920",
                "custname": "方磊",
                "cardno": 1592,
                "cardstatus": 1,
                "showcardno": "0000000168",
                "cardphyid": "540F7953",
                "expiredate": "20990801",
                "opendate": "20150901",
                "cardverno": "150901003172",
                "cardtype": 1,
                "cardtypename": "正式卡",
                "custid": 2007090,
                "custtype": 2,
                "custtypename": "教工",
                "deptcode": "129",
                "deptname": "国际**学院",
                "specialtycode": "0",
                "specialtyname": null,
                "sex": "0",
                "idtype": "0",
                "idtypename": null,
                "idno": null,
                "areacode": "2",
                "areaname": "浦东校区",
                "classcode": null,
                "countrycode": "0",
                "country": null,
                "email": null,
                "nationcode": "0",
                "nation": null,
                "tel": null,
                "mobile": null,
                "zipcode": null,
                "cardupdtime": "20150901142449",
                "custupdtime": "20150901142449"
            },
            {
                "stuempno": "2012127117",
                "custname": "施雨",
                "cardno": 1593,
                "cardstatus": 1,
                "showcardno": "0000002146",
                "cardphyid": "540CC9B3",
                "expiredate": "20160801",
                "opendate": "20150901",
                "cardverno": "150901003173",
                "cardtype": 1,
                "cardtypename": "正式卡",
                "custid": 2000864,
                "custtype": 3,
                "custtypename": "学生",
                "deptcode": "1",
                "deptname": "上海**学院",
                "specialtycode": "0",
                "specialtyname": null,
                "sex": "2",
                "idtype": "1",
                "idtypename": "身份证",
                "idno": "3702851*********",
                "areacode": "2",
                "areaname": "浦东校区",
                "classcode": null,
                "countrycode": "0",
                "country": null,
                "email": null,
                "nationcode": "0",
                "nation": "汉族",
                "tel": null,
                "mobile": null,
                "zipcode": null,
                "cardupdtime": "20150901142451",
                "custupdtime": "20150901142451"
            },
            {
                "stuempno": "2012127119",
                "custname": "朱时琳",
                "cardno": 1597,
                "cardstatus": 1,
                "showcardno": "0000002144",
                "cardphyid": "540CDDB3",
                "expiredate": "20160801",
                "opendate": "20150901",
                "cardverno": "150901003182",
                "cardtype": 1,
                "cardtypename": "正式卡",
                "custid": 2000866,
                "custtype": 3,
                "custtypename": "学生",
                "deptcode": "1",
                "deptname": "上海**学院",
                "specialtycode": "0",
                "specialtyname": null,
                "sex": "2",
                "idtype": "1",
                "idtypename": "身份证",
                "idno": "3702851*********",
                "areacode": "2",
                "areaname": "浦东校区",
                "classcode": null,
                "countrycode": "0",
                "country": null,
                "email": null,
                "nationcode": "0",
                "nation": "汉族",
                "tel": null,
                "mobile": null,
                "zipcode": null,
                "cardupdtime": "20150901142514",
                "custupdtime": "20150901142514"
            }
        ],
        "firstResult": 0,
        "firstPage": true,
        "lastPage": false,
        "nextPage": 2,
        "totalPage": 10,
        "prePage": 1
    }
}

失败

{
	"retcode":"1",
	"retmsg":"查询失败"

返回参数说明:

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

2.3 通用账户流水查询

请求URL:

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

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
stuempno	String	是	查询对象的学号
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	终端名称

签名计算

除sign和参数值为空以外的参数都要参与签名
以参数名按字母排序并以key=value的形式以&符号连接得到加密字符串
以约定的秘钥对加密字符串进行加密，加密方式为HAMC-SHA1

示例

partner_id: 100004
stuempno: 10000035
timestamp: 20170810153811
sign_method: HMAC
sign:42fa845499384b830b774caf423c2fedd43f0b23
加密字符串： partner_id=100004&sign_method=HMAC&stuempno=10000035&timestamp=20170810153811

2.4 卡片挂失

请求URL:

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

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
stuempno	String	否*	挂失对象的学工号。与卡片物理ID必传一项
cardphyid	String	否*	卡片物理ID，读卡得到。与学工号选其一即可，都传默认学工号为主
timestamp	String	是	时间戳格式为yyyyMMddhh24miss
sign	String	是	签名
sign_method	String	是	固定填： HMAC （加密方式为HAMC-SHA1）

请求内容示例:


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

返回示例:

成功

{
    "retcode": "0",
    "retmsg": "成功",
}

失败

{
    "retcode": "51",
    "retmsg": "卡已挂失"
}

返回参数说明:

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

2.5 账户余额查询

请求URL:

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

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	本系统分配给各个接入应用的合作伙伴id号
stuempno	String	否*	挂失对象的学工号。与卡片物理ID必传一项
cardphyid	String	否*	卡片物理ID，读卡得到。与学工号选其一即可，都传默认学工号为主
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	当天累计消费限额（分），超出要输入卡密码

2.6 验证学工号/卡号和密码

请求URL:

http://ip:port/epayapi/services/thirdparty/common/verify

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
partner_id	String	是	合作方ID
stuempno	String	否	学工号(二选一）
cardphyid	String	否	物理卡号（二选一）
cardpwd	String	是	卡密码AES加密，加密密钥线下提供
timestamp	String	是	时间戳格式为yyyyMMddHHmmss
sign	String	是	数据签名
sign_method	String	是	签名方式，固定为:HMAC

请求内容示例:


- URL：http://ip:port/epayapi/services/thirdparty/common/verify
- partner_id:10000
- stuempno:09893092
- cardpwd:vj16YGawjSlYkaWOND+gog==
- timestamp:20171219130901
- sign:09ce91ba0c46b486f841caa51cff1589e9b83b2e
- sign_method:HMAC


**返回示例:**

- 成功

```json
{
	"retcode":0,
	"retmsg":"验证成功"
}

失败

{
	"retcode":1,
	"retmsg":"错误信息"
}

返回参数说明:

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