title: 一卡通v5第三方充值接口文档 date: 2016-06-21 13:54:11 tags:

1.1文档说明

本文档用于描述了一卡通对第三方应用提供的通用支付api接口文档，供第三方系统（前置和应用）对接参考。

1.2约定

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

2.1 通用账户查询

请求URL:

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

请求方式/格式:

  • POST
  • application/x-www-form-urlencoded

请求参数:

参数名类型必选说明
partner_idString是      本系统分配给各个接入应用的合作伙伴id号
stuempnoString是查询对象的学号
timestampString是时间戳格式为yyyyMMddhh24miss
signString是签名
sign_methodString是参数的加密方法选择，可选值是：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":"查询成功",
	"stuempno":"09893092",
	"username":"王二小",
    "balance":4850,
    "cardno":103920299,
	"status":"正常",
	"timestamp":"20160606150902",
	"sign":"hjAtBGygGjFyOKEZmWdxi1tk51/xqLYTr5tm2+zQVfD1RHRzGVC9GNm4ZaXnUsHnu5o3kAZ4U32m0YNiSFpncs0pl1AnnCf1n2hhn39ruABsvD//GzkEINHjyHsnxBr44G2UhyNxplUj+s7s0a7ggjbiMk+BYC3u7VkU9/l+kZOTkEyqs+wZKumfByMZGvKVkY2c2Nr67RaSWd7bsfOJ6HYw2spvu3ptAo2RTrfCxZ0Kn5DcSDm4cagzPMZSHxB8isqqNGrdUaAU0wzzC7704iA5zze//SvCqpCJfYt0OrHOiJEN5kw1d4KESrKGMG6bezlXzAp0LbNlhl+HwZJcag==",
    "sign_method": "RSA"
}
  • 失败
{
	"retcode":"1",
	"retmsg":"账户不存在",
	"timestamp":"20160606150902",
	"sign": "hjAtBGygGjFyOKEZmWdxi1tk51/xqLYTr5tm2+zQVfD1RHRzGVC9GNm4ZaXnUsHnu5o3kAZ4U32m0YNiSFpncs0pl1AnnCf1n2hhn39ruABsvD//GzkEINHjyHsnxBr44G2UhyNxplUj+s7s0a7ggjbiMk+BYC3u7VkU9/l+kZOTkEyqs+wZKumfByMZGvKVkY2c2Nr67RaSWd7bsfOJ6HYw2spvu3ptAo2RTrfCxZ0Kn5DcSDm4cagzPMZSHxB8isqqNGrdUaAU0wzzC7704iA5zze//SvCqpCJfYt0OrHOiJEN5kw1d4KESrKGMG6bezlXzAp0LbNlhl+HwZJcag==",
    "sign_method":"RSA"
}

返回参数说明:

参数名类型说明
retcodeString返回码（0=成功，其他为失败）
retmsgString返回消息
stuempnoString学号
usernameString姓名
balanceInteger余额(分)
cardnoInteger卡号
statusString状态(正常)

2.2 通用充值

请求URL:

  • https://ip:port/epayapi/services/thirdparty/common/recharge

请求方式/格式:

  • POST
  • application/x-www-form-urlencoded

请求参数:

参数名类型必选说明
partner_idString是本系统分配给各个接入应用的合作伙伴id号
student_idString是用户唯一号
student_idtypeString是指定用户唯一号类型（stuempno,custid,cardno,idno等）
extdataString否备用，扩展字段
amountString是整数，单位分
transdateString是交易日期，yyyyMMdd
transtimeString是交易时间，HHmmss
fundtypeString是资金类型，指定入账科目（1-现金；2-支票；3-经费本）
billnoString否票据号，现金类型时可空，其他必传
tradenoString是外部流水号。唯一，不能重复
operidString是指定充值操作员
termidString否区分发起终端
sourcetypeString否发起来源
timestampString是时间戳 yyyyMMddHHmmss
sign_methodString是HMAC
signString是签名

请求内容示例:

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

partner_id:10000
student_id:09893092
student_idtype:stuempno
tradeno:20160607000001
transdate:20180808
transtime:100404
amount:2000
operid:90
fundtype:1
timestamp:20150119130901
sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
sign_method:HMAC

返回示例:

  • 成功
{
	"retcode":"0",
	"retmsg":"充值成功"
	"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"
}

返回参数说明:

参数名类型说明
retcodeString返回码（0=成功，其他为失败）
retmsgString返回消息
tradenoString第三方流水号
refnoString本系统生成流水号
balanceInteger账户余额(分)

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

  • 签名方式：hmac-sha1

  • 签名密钥由本系统统一线下提供

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

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

    特别注意以下重要规则：

  • 参数名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"