source/_posts/一卡通v5圈存对接前置接口文档.md

title: 一卡通v5圈存对接前置接口文档 date: 2016-06-21 13:45:23 tags:

日期	版本	作者	说明
2015-4-14	V1.0	汤成	初稿
2017-2-13	V1.1	夏凯祥	V1.1

背景

在项目中进行银行圈存对接开发时需要对悦校与一卡通同时支持。此文档为一卡通系统与银行圈存前置的对接规范，用户可根据实际情况实现前置与银行业务的对接。

约定

传输编码统一为utf-8
请求数据都用HAMC签名加密，收到请求参数后可验证数据正确性，秘钥共同约定。SIGN_ALGORITHMS ="HmacSHA1";
retcode 等于"0"（字符串）表示成功，其他表示失败，失败具体信息查看 retmsg
{bank} 为银行标识，区别不同的银行圈存

接口定义

0. 银行卡绑定

URL: .../bankservice/{bank}/bindbankcard
请求方式 POST

绑定银行卡

请求参数

bankcardno - 银行账号（银行卡号）
bankcode - 银行代码如：ICBC、ABC、BOC
custname - 用户姓名，必须是该用户在银行的开户名（可选）
custid - 系统唯一号，客户号（可选）
stuempno - 系统唯一号，如学工号（可选）
idtype - 证件类型（可选）
idno - 身份证号（可选）
termid - 发起终端号（可选）
tradetime - 发起方时间，格式 yyyyMMddHHmmss
seqno - 发起方流水号（可选）
timeout - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
sign - 签名。除sign的非空字段按上述顺序拼接进行签名加密，如（bankcardno + bankcode + custid +stuempno+idtype+idno+termid+tradetime+timeout）。

返回

retcode - "0" 标识操作成功，其余为异常情况
retmsg - "msg" 返回信息

{
    "retcode":"0",
    "retmsg":"msg", // 异常原因
}

1. 查询银行卡余额

URL: .../bankservice/{bank}/bankbalquery
请求方式 POST

查询银行余额，根据银行实际情况不是所有银行都支持

请求参数

bankcardno - 银行账号（银行卡号）
custname - 用户姓名，必须是该用户在银行的开户名（可选）
custid - 系统唯一号，客户号（可选）
stuempno - 系统唯一号，如学工号（可选）
idtype - 证件类型（可选）
idno - 身份证号（可选）
termid - 发起终端号（可选）
tradetime - 发起方时间，格式 yyyyMMddHHmmss
seqno - 发起方流水号（可选）
timeout - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
sign - 签名。除sign的非空字段按上述顺序拼接进行签名加密，如（bankcardno+ custid +stuempno+idtype+idno+termid+tradetime+timeout）。

返回

retcode - "0" 标识操作成功，其余为异常情况
retmsg - "msg" 返回信息
money - 银行卡余额，单位元

{
    "retcode":"0",
    "retmsg":"msg", // 异常原因
    "money":412.3 //单位（元）
}

2. 圈存请求

URL: .../bankservice/{bank}/charge
请求方式 POST

银行圈存请求，通过该请求完成银行卡转账业务

请求

bankcardno - 银行卡号
bankcardpwd - 银行卡密码（可选）
extdata - 银行卡扩展信息
refno - 系统交易参考号
stuempno - 系统唯一号，如学工号（可选）
custid - 系统唯一号，如客户号（可选）
custname - 客户姓名(可选）
idtype - 证件类型(可选）
idno - 身份证号(可选）
amount - 圈存金额，单位分（整数）
termid - 终端编号（可选）
tradetime - 请求时间，格式yyyyMMddHHmmss
timeout - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
sign 签名。除sign的非空字段按上述顺序拼接进行签名加密，如（bankcardno+refno+custid+stuempno+idtype+idno+amount+termid+ tradetime+timeout）。

返回

retcode - "0" 标识操作成功，其余为异常情况
retmsg - "msg" 返回信息
bankseqno - （可选）返回银行端流水号，但不是所有银行都支持返回银行端流水号

{
    "retcode":"0",
    "retmsg":"msg", // 返回信息 
    "bankseqno": "1231", // 如果银行支持，返回银行端流水号
}

3. 圈存结果查询

URL: .../bankservice/{bank}/transquery
请求方式 POST

根据系统交易参考号查询圈存请求的结果，一般是圈存请求超时后通过这个接口判断银行交易是否成功，但不是所有银行都支持这个接口

请求

bankcardno - 银行卡号
extdata - 银行卡扩展信息
refno - 系统交易参考号
stuempno - (可选）学工号
custid - （可选）客户号
custname - (可选）客户姓名
idtype - (可选）证件类型
idno - (可选）身份证号码
termid - （可选）终端编号
tradetime - 请求时间，格式yyyyMMddHHmmss
timeout - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
sign - 签名。除sign的非空字段按上述顺序拼接进行签名加密。如（bankcardno+refno+custid+stuempno+idtype+idno+termid+ tradetime+timeout）。

返回

retcode - "0" 标识查询到指定的圈存流水,并交易成功；"01" 标识无指定流水，其它表示错误
retmsg -"msg" 返回信息
bankseqno - （可选）如果查询到圈存流水则返回银行端流水号，但不是所有银行都支持返回银行端流水号

{
    "retcode":"0",
    "retmsg":"msg" // 返回信息
    "bankseqno": 123, // 银行端流水号
}

4. 圈存冲正（退款）

URL: .../bankservice/{bank}/chargereverse
请求方式 POST

圈存冲正接口，一般是圈存请求超时后通过这个接口冲正前面一笔圈存交易，但不是所有银行都支持这个接口

请求

bankcardno - 银行卡号
extdata - 银行卡扩展信息
refno - 系统交易参考号
reverserefno - 前一笔要冲正的圈存交易的参考号
stuempno - (可选）学工号
custid - （可选）客户号
custname - (可选）客户姓名
idtype - (可选）证件类型
idno - (可选）身份证号
amount - 金额，单位分（整数）
termid - （可选）终端编号
tradetime - 请求时间，格式yyyyMMddHHmmss
timeout - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
sign 签名。除sign的非空字段按上述顺序拼接进行签名加密。（bankcardno+refno+ reverserefno +custid+stuempno+idtype+idno+ amount +termid+ tradetime+timeout）。

返回

retcode - "0" 标识冲正成功，其它表示错误
retmsg - 返回信息
bankseqno - （可选）返回银行端流水号，但不是所有银行都支持返回银行端流水号

{
    "retcode":"00",
    "retmsg":"msg", // 返回信息
    "bankseqno":"122121"
}

5. 圈存对账

URL: .../bankservice/{bank}/chargedtlchk
请求方式 POST

圈存流水对账接口，一卡通系统每天定时的访问这个接口查询前一天或过去某一天的全部圈存流水(交易成功)，与系统记录的圈存流水进行比对，不一致时进行业务处理。

请求

transdate - 查询日期，yyyyMMdd
bankcode - 银行标识
billtype - 查询类型,有的银行圈存转账和退款可能是分开的。"ALL"-查询圈存和冲正（退款）所有交易成功的流水;"SUCCESS"-查询圈存交易成功的流水;"REFUND"-查询冲正（退款）所有交易成功的流水。
offset - 偏移量，int型，初始为0
tradetime - 请求时间，格式yyyyMMddHHmmss
timeout - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
checkagain - 重新对账标志，1-是重新对账；0-不是
sign 签名。除sign的非空字段按上述顺序拼接进行签名加密（transdate + bankcode + billtype + offset + tradetime + timeout + checkagain）。

返回

retcode - "0" 标识冲正成功，其它表示错误
retmsg -"msg" 返回信息
hasnext - true或false。是否继续查询的标志。true继续查询，false结束查询
offset - 继续查询时的偏移量，int型。
data - 流水数据集合。
- transdate - 交易日期 yyyyMMdd
- transtime - 交易时间 HHmmss
- stuempno - 系统唯一号，如学工号、客户号
- bankcardno - 银行账号
- refno - 系统交易参考号，
- bankseqno - 银行端流水号
- amount - 交易金额，单位元
- billtype - 圈存或冲正的标志。（'SUCCESS'-圈存成功流水；‘BEREFD’-被冲正的圈存流水; -'REFUND'-冲正流水）

{
    "retcode":"0",
    "retmsg":"msg", // 返回信息
    "hasnext":true，
    "offset":100,
    "data":[
    			{
    				"transdate":"20160901",
    				"tramsdate":"142328",
    				"stuempno":"20170001",
    				"bankcardno":"6022111001004394733",
    				"refno":"20160901142328000023",
    				"bankseqno":"1020160901142328130713",
    				"amount":50.0,
    				"billtype":"SUCCESS"
    			},...]
}