source/_posts/一卡通v5系统应用接口文档.md

title: 一卡通v5系统应用接口文档 date: 2016-08-05 09:52:33 tags:

版本	日期	说明
1.0	2016-8-5	初始版本

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/epay/api/pos_deposit/oper_login

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
appid	String	是	本系统分配给各个接入应用的合作伙伴id号
cardphyid	String	是	操作员授权卡物理卡号
oper_pswd	String	是	操作员密码， MD5串
deviceid	Integer	否	充值POS机设备ID
devphyid	String	否	充值POS机物理ID，devphyid 和 deviceid 二选一
sign	String	是	签名
sign_method	String	是	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1

请求内容示例:

URI：https://ip:port/epay/api/pos_deposit/oper_login

partner_id:10000
stuempno:48BC2188
oper_pswd:e10adc3949ba59abbe56e057f20f883e
devphyid:10000001
timestamp:20150119130901
sign:5195f9b9116e4adf67eeebc9935d33dc683f677d
sign_method:HMAC

返回示例:

成功

{
	"retcode":"0",
	"retmsg":"签到成功",
	"termid":123,
	"termseqno":58,
    "checknum":123454,
    "cardno":456,
	"opername":"张三",
	"operid":45,
	"authcode": 64551,
	"batchno": 4757,
	"hostdate": "20160803",
	"hosttime": "154311",
	"mainkey": "434582727485",
	"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"
}

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，其他为失败）
retmsg	String	返回消息
termid	Integer	终端ID
termseqno	Integer	终端流水号
checknum	Integer	余额(分)
cardno	Integer	卡号
opername	String	状态(正常)
operid	Integer	操作员ID
authcode	Integer	授权号
batchno	Integer	批次号
hostdate	String	主机日期
hosttime	String	主机时间
mainkey	String	M1卡密钥（暂时为空）

2.2 操作员充值接口

请求URL:

https://ip:port/epay/api/pos_deposit/deposit

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
appid	String	是	本系统分配给各个接入应用的合作伙伴id号
cardno	Integer	是	交易卡号
dpscnt	Integer	是	充值前次数
paycnt	Integer	是	消费前次数
cardbefbal	Integer	是	充值前卡余额
amount	Integer	是	充值金额
dpsamt	Integer	是	实际写卡金额
radmon_num	String	是	随机数
mac1	String	是	MAC1
operid	Integer	是	操作员ID
authcode	Integer	是	授权号
batchno	Integer	是	批次号
termid	Integer	是	终端ID
termseqno	Integer	是	终端流水号
reqflag	String	是	请求标志，（暂时保留）
sign	String	是	签名
sign_method	String	是	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1

请求内容示例:

URI：https://ip:port/epay/api/pos_deposit/oper_login

返回示例:

成功

{
	"retcode":"0",
	"retmsg":"签到成功",
	"termid":123,
	"termseqno":58,
    "checknum":123454,
    "cardno":456,
	"opername":"张三",
	"operid":45,
	"authcode": 64551,
	"batchno": 4757,
	"hostdate": "20160803",
	"hosttime": "154311",
	"mainkey": "434582727485",
	"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"
}

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，其他为失败）
retmsg	String	返回消息
termid	Integer	终端ID
cardno	Integer	卡号
refno	String	交易参考号
hostdate	String	主机日期
hosttime	String	主机时间
mac2	String	MAC2

2.3 操作员充值确认接口

请求URL:

https://ip:port/epay/api/pos_deposit/confirm

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
appid	String	是	本系统分配给各个接入应用的合作伙伴id号
refno	String	是	交易参考号
isok	Integer	是	是否成功 1: 成功，其他失败
isbreak	Integer	是	是否是中途拔卡 0-不是，1-是
tac	String	是	TAC
sign	String	是	签名
sign_method	String	是	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1

请求内容示例:

URI：https://ip:port/epay/api/pos_deposit/oper_login

返回示例:

成功

{
	"retcode":"0",
	"retmsg":"签到成功",
	"termid":123,
	"termseqno":58,
    "checknum":123454,
    "cardno":456,
	"opername":"张三",
	"operid":45,
	"authcode": 64551,
	"batchno": 4757,
	"hostdate": "20160803",
	"hosttime": "154311",
	"mainkey": "434582727485",
	"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"
}

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，其他为失败）
retmsg	String	返回消息
termid	Integer	终端ID
next_termseqno	Integer	下一笔终端流水号
refno	String	交易参考号

2.4 B模式卡消费初始化

请求URL:

https://ip:port/epay/api/bmode_pay/init_for_pay

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
appid	String	是	本系统分配给各个接入应用的合作伙伴id号
cardno	Integer	是	交易卡号
paycnt	Integer	是	消费前次数
cardbefbal	Integer	是	卡消费前余额
amount	Integer	是	消费金额
termid	Integer	是	终端号
termseqno	Integer	是	终端流水号
termdate	String	是	终端日期
termtime	String	是	终端时间
sign	String	是	签名
sign_method	String	是	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1

请求内容示例:

URI：https://ip:port/epay/api/bmode_pay/init_for_pay

返回示例:

成功

{
	"retcode":"0",
	"retmsg":"签到成功",
	"termid":123,
	"termseqno":58,
    "checknum":123454,
    "cardno":456,
	"opername":"张三",
	"operid":45,
	"authcode": 64551,
	"batchno": 4757,
	"hostdate": "20160803",
	"hosttime": "154311",
	"mainkey": "434582727485",
	"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"
}

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，其他为失败）
retmsg	String	返回消息
termid	Integer	终端ID
cardno	Integer	交易卡号
refno	String	交易参考号
payamt	Integer	实际消费金额（分）
otheramt	Integer	其它金额（分）
otheramt_desc	String	说明
sign	String	签名
sign_method	String	是

2.5 B模式卡消费确认

请求URL:

https://ip:port/epay/api/bmode_pay/credit_for_pay

请求方式/格式:

POST
application/x-www-form-urlencoded

请求参数:

参数名	类型	必选	说明
appid	String	是	本系统分配给各个接入应用的合作伙伴id号
refno	String	是	交易参考号
isok	Integer	是	是否消费成功
tac	String	是	TAC
samno	String	是	SAM卡号
samseqno	Integer	是	SAM卡流水号
sign	String	是	签名
sign_method	String	是	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1

请求内容示例:

URI：https://ip:port/epay/api/bmode_pay/init_for_pay

返回示例:

成功

{
	"retcode":"0",
	"retmsg":"签到成功",
	"termid":123,
	"termseqno":58,
    "checknum":123454,
    "cardno":456,
	"opername":"张三",
	"operid":45,
	"authcode": 64551,
	"batchno": 4757,
	"hostdate": "20160803",
	"hosttime": "154311",
	"mainkey": "434582727485",
	"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"
}

返回参数说明:

参数名	类型	说明
retcode	String	返回码（0=成功，其他为失败）
retmsg	String	返回消息
refno	String	交易参考号
sign	String	签名
sign_method	String	参数的加密方法选择，可选值是：HMAC 加密方式为HAMC-SHA1