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

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

背景

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

约定

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

接口定义

0. 银行卡绑定/解绑

  • 绑定URL: .../bankservice/{bank}/bindbankcard

  • 解绑URL: .../bankservice/{bank}/unbindbankcard

  • 请求方式 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+stuempno+custid+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" 标识查询到指定的圈存流水,并交易成功；其它表示错误
  • 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: http(s)://ip:port/epayapi/services/bankservice/sendchkbilldata

  • 请求方式 POST

API接收对账单统一接口，由前置发起调用。前置拉取对账单后调用此接口向API发送解析后的对账数据。

  • 请求
  • accdate - 账单日期，yyyyMMdd
  • chkcode - 账单标识，若是银行对账，传银行标识{bankcode}。‘alipay’-支付宝，‘wechat’- 微信，‘wmxy’-完美校园等
  • thirdpartid -第三方ID，非必传。如充值机对账时的终端ID等
  • errmsg - 存放错误信息（拉取第三方对账单失败时也要调用此接口，发送错误原因），默认为空。（明确某天系统无对账单时，是拉取对账单失败或解析失败等，而不是前置或系统异常导致）
  • pageno - 分批次上传时，pageno逐次递增，初始为1（1，2，3，...），不能跳跃
  • endflag - 结束标志。true-全部上传完成，false-未上传完成，还需继续
  • app_id - 前置配置的APPID
  • timestamp - 时间戳 ‘yyyyMMddHHmmss’
  • sign - 签名数据 (accdate+chkcode+pageno+endflag+ timestamp +APPKEY 最后MD5)
  • data -数据集合
    • transdate - 交易日期 yyyyMMdd
    • transtime - 交易时间 HHmmss
    • stuempno - 系统唯一号，如学工号、客户号
    • thirdpartaccno - 支付宝、微信、银行卡号等账号
    • refno - 系统交易参考号，本地流水号
    • thirdpartrefno - 第三方流水号，银行、支付宝、微信流水号
    • amount - 交易金额，单位分。
    • billtype - 流水状态标志。（'SUCCESS'-圈存成功流水；‘BEREFD’-被冲正的圈存流水; -'REFUND'-冲正流水）
  • 返回
  • retcode - "0" 标识冲正成功，其它表示错误
  • retmsg -"msg" 返回信息
  • totalcnt - 收到的流水笔数
  • totalamt - 收到的流水金额，单位元
{
    "retcode":"0",
    "retmsg":"msg", // 返回信息
    "totalcnt":100,
    "totalamt":2340.00
}