资金存管系统API接口规范文档示例.docx
《资金存管系统API接口规范文档示例.docx》由会员分享,可在线阅读,更多相关《资金存管系统API接口规范文档示例.docx(33页珍藏版)》请在冰点文库上搜索。
资金存管系统API接口规范文档示例
资金存管系统API接口规范文档
某某科技有限公司
二〇一七年八月
文档版本号
V1.0.0
起草人
审核人
审核日期
批准人
批准日期
修订记录
版本
日期
说明
V1.0.1
2017-8-23
发布版初稿
V1.0.2
2017-9-11
1.增加约定代扣(默认路由充值)接口:
proxyRecharge,删除约定代扣(可选择路由通道充值)接口:
autoDeduct
2.增加开通投标和购买债权授权接口:
openBid
3.增加四合一授权(页面)接口:
authModify
4.修改四合一授权(联机)接口:
请求报文中增加version字段,删除reserved字段;响应报文中修改restMsg字段为retMsg,删除reserved字段。
5.免密提现请求报文中seqno当天(银行系统日期)不能重复
V1.0.3
2017-9-29
1.增加手续费分账接口
1前言
1.1目的
本文档是存管业务平台对P2P端的接口规范,本规范定义了接口的数据交换格式。
1.2使用对象
本文档的使用对象是P2P公司的技术开发人员。
开发人员需要对form提交、post提交、json格式、https传输、非对称密钥和数据签名有一定认识。
1.3主要接口特点
本接口有两种类型:
接口调用和页面调用,接口调用时数据以json格式提交,页面调用时数据以form方式提交。
每笔交易的请求和应答都需要有签名,发送端签名,接收端验证签名。
2接口规范
2.1概要规范
2.1.1基本约定
报文在传输时采用UTF8编码。
报文采用json格式。
键值技术上均为字符串类型,业务上值数据类型按文档中类型传送。
所采用的符号说明如下:
N:
数字(Numeric)
A:
字符(Alphabetic)
2.1.2栏位约定
1.数字栏位以ASCII表示(非PACKED方式)。
2.数字栏位的最大长度若有“,”表示包括小数点,如12,2,表示最大12个字符,精确到两位小数,并且包括小数点,如1.03元以1.03填充。
3.字符栏位向左靠齐。
4.数字栏位不含正负号,通过额外的1位字符栏位表示数字的正负方向。
“D”或空白或“+”表示借方,正数,“C”或“-”代表贷方,负数。
5.域最大长度为该域的最大长度
2.1.3必填列填写规则
M:
必填
C、O、空:
有条件必填或非必填
2.1.4通讯方式
渠道通过HTTPSRESTAPI调用系统接口。
数据格式为JSON,数据提交为POST。
以所有JSON值按其对应的KEY以字典序排序拼接成字符串进行签名计算,结果放在JSON的最后,变量名为“sign”。
2.1.5基础域约定
请求端确保所有交易的“交易日期txDate”+“交易时间txTime”+“交易流水号seqNo”不重复;若因特殊情况,需要原样重发交易,则上述三域保持不变。
交易流水号seqNo”在5分钟内不重复
2.1.6接口URL
测试:
UAT:
生产:
联机:
页面在接口处单独标注
2.1.7页面通知的处理
对于页面调用的交易,存管系统以HttpClient形式POST数据至请求参数中的“后台通知连接”,P2P收到后需response数据,防止重复接受请求如:
response.getWriter().write("success");
如果存管系统未接收到响应,自动重发5次。
P2P端可以参考如下形式解析后台通知的数据:
StringbgData=request.getParameter("bgData");
返回数据bgData为JSONObject格式的字符串
Mapmap=JSONObject.fromObject(bgData);
2.1.8前台跳转的处理
对于页面调用的交易,如没有特殊说明,前台跳转没有数据返回,页面打开方式为GET。
如果注明需要接受POST表单请求,则需要按响应参数接收POST表单。
2.1.9敏感字符集
对于用户自定义字段,不允许使用以下敏感字符集:
”|”。
2.2平台相关需求
2.2.1.四合一授权(联机)
功能说明:
用户和平台签约自动投标、自动债权转让、预约提现、无密消费。
授权前需要先调用请求发短信验证接口。
调用方式:
接口调用【请求参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
termsAuth
instCode
机构代码
A
8
M
bankCode
银行代码
A
8
M
txDate
交易日期
A
8
M
YYYYMMDD
txTime
交易时间
A
6
M
HHmmss
seqNo
交易流水号
N
6
M
定长6位
channel
交易渠道
A
6
M
000001手机APP
000002网页
000003微信
000004柜面
accountId
电子账号
A
19
M
存管平台分配的电子账号
orderId
订单号
A
30
M
由P2P生成必须保证唯一
bitMap
是否维护标志位
A
20
M
由0和1组成的标志位,0表示查询授权,1表示维护授权,共20位,该字段第1位表示开通自动投标标志是否生效,第2位表示开通自动债转功能标志是否生效,其余以此类推;
autoBid
开通自动投标功能标志
N
1
C
0:
取消
1:
开通
autoTransfer
开通自动债转功能标志
N
1
C
0:
取消
1:
开通
agreeWithdraw
开通预约取现功能标志
N
1
C
0:
取消
1:
开通
directConsume
开通无密消费功能标识
N
1
C
0:
取消
1:
开通
mobile
手机号码
A
12
M
smsCode
短信验证码
A
8
M
smsSeq
短信序列号
A
4
M
acqRes
第三方保留域
A
100
C
【响应参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
同请求
instCode
机构代码
A
8
M
同请求
bankCode
银行代码
A
8
M
同请求
txDate
交易日期
A
8
M
同请求
txTime
交易时间
A
6
M
同请求
seqNo
交易流水号
N
6
M
同请求
channel
交易渠道
A
6
M
同请求
retCode
应答码
A
8
M
retMsg
应答码描述
A
60
M
accountId
电子账户
A
19
M
同请求
name
持卡人姓名
A
60
M
orderId
签约订单号
A
30
M
autoBid
开通自动投标功能标志
N
1
C
同请求
autoTransfer
开通自动债转功能标志
N
1
C
同请求
agreeWithdraw
开通预约取现功能标志
N
1
C
同请求
directConsume
开通无密消费功能标识
N
1
C
同请求
acqRes
第三方保留域
A
100
C
2.2.2.四合一授权(页面)
功能说明:
用户和平台签约自动投标、自动债权转让、预约提现、无密消费。
授权时需要用户输入电子账户密码。
调用方式:
页面调用
地址:
示例页面:
【请求参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
authModify
instCode
机构代码
A
8
M
bankCode
银行代码
A
8
M
txDate
交易日期
A
8
M
YYYYMMDD
txTime
交易时间
A
6
M
HHmmss
seqNo
交易流水号
N
6
M
定长6位
channel
交易渠道
A
6
M
000001手机APP
000002网页
000003微信
000004柜面
accountId
电子账号
A
19
M
存管平台分配的电子账号
orderId
订单号
A
30
M
由P2P生成必须保证唯一
autoBid
开通自动投标功能标志
A
1
C
0:
取消
1:
开通
空:
取消
autoTransfer
开通自动债转功能标志
A
1
C
0:
取消
1:
开通
空:
取消
agreeWithdraw
开通预约取现功能标志
A
1
C
0:
取消
1:
开通
空:
取消
directConsume
开通无密消费功能标识
A
1
C
0:
取消
1:
开通
空:
取消
remark
备注
A
200
C
acqRes
第三方保留域
A
200
C
forgotPwdUrl
忘记密码跳转链接
A
256
C
用于签约页面中的忘记密码跳转
transactionUrl
返回交易页面链接
A
256
M
用于签约后,跳转原交易页面
verifyOrderUrl
订单有效性连接
A
256
C
用于机构检查订单有效性
notifyUrl
后台响应链接
A
256
M
用于接收后台响应
retUrl
交易成功跳转链接
A
256
C
用于交易成功后post到机构成功页面
【响应参数】
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
同请求
instCode
机构代码
A
8
M
同请求
bankCode
银行代码
A
8
M
同请求
txDate
交易日期
A
8
M
同请求
txTime
交易时间
A
6
M
同请求
seqNo
交易流水号
N
6
M
同请求
channel
交易渠道
A
6
M
同请求
retCode
应答码
A
8
M
restMsg
应答码描述
A
60
M
accountId
电子账户
A
19
M
同请求
name
持卡人姓名
A
60
M
orderId
签约订单号
A
30
M
autoBid
开通自动投标功能标志
A
1
C
同请求
autoTransfer
开通自动债转功能标志
A
1
C
同请求
agreeWithdraw
开通预约取现功能标志
A
1
C
同请求
directConsume
开通无密消费功能标识
A
1
C
同请求
acqRes
第三方保留域
A
200
C
2.2.3.免密提现
功能说明:
用户将电子账户资金转移到绑定的银行卡,需要先进行四合一授权签约
调用方式:
接口调用
【请求参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
agreeWithdraw
instCode
机构代码
A
8
M
bankCode
银行代码
A
8
M
txDate
交易日期
A
8
M
YYYYMMDD
txTime
交易时间
A
6
M
hhmmss
seqNo
交易流水号
N
6
M
定长6位,
seqno当天(银行系统日期)不能重复
channel
交易渠道
A
6
M
000001手机APP
000002网页
000003微信
000004柜面
accountId
电子账号
A
19
M
存管平台分配的账号
idType
证件类型
A
2
M
01-身份证(18位)
idNo
证件号码
A
18
M
name
姓名
A
60
M
mobile
手机号
A
12
M
cardNo
银行卡号
A
19
M
绑定银行卡号
txAmount
交易金额
N
12,2
M
提现金额
txFee
手续费
N
12,2
M
提现手续费
routeCode
路由代码
A
1
C
0-本行通道
1-银联通道
2-人行通道
空-自动选择
cardBankCnaps
绑定银行联行号
A
20
C
人民银行分配的12位联行号
routeCode=2,必输
或者routeCode为空,但交易金额>20万,必输
cardBankCode
绑定银行代码
A
20
C
绑定的银行卡对应的银行代码
cardBankNameCn
绑定银行中文名称
A
50
C
绑定的银行卡对应的银行中文名称
cardBankNameEn
绑定银行英文名称
A
20
C
绑定的银行卡对应的银行英文名称缩写
cardBankProvince
绑定银行卡开户省份
A
20
C
绑定的银行卡的开户省份
cardBankCity
绑定银行卡开户城市
A
50
C
绑定的银行卡的开户城市
contOrderId
签约订单号
A
30
M
预约提现签约订单号
acqRes
请求方保留
A
200
C
【响应参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
同请求
instCode
机构代码
A
8
M
同请求
bankCode
银行代码
A
8
M
同请求
txDate
交易日期
A
8
M
同请求
txTime
交易时间
A
6
M
同请求
seqNo
交易流水号
N
6
M
同请求
channel
交易渠道
A
6
M
000001手机APP
000002网页
000003微信
000004柜面
retCode
响应代码
A
8
M
retMsg
响应描述
A
60
M
accountId
电子账号
A
19
M
同请求
txAmount
交易金额
N
12,2
M
同请求
acqRes
请求方保留
A
200
C
同请求
2.2.4.线下充值回调
功能说明:
线下充值回调,请求参数由即信推送,平台接收到即信报文后,返回给即信“success”响应。
调用方式:
接口调用
【请求参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
offlineRechargeCall
instCode
机构代码
A
8
M
bankCode
银行代码
A
8
M
txDate
交易日期
A
8
M
YYYYMMDD
txTime
交易时间
A
6
M
hhmmss
seqNo
交易流水号
N
6
M
定长6位
channel
交易渠道
A
6
M
000001手机APP
000002网页
000003微信
000004柜面
accountId
电子账号
A
19
M
存管平台分配的账号
orgTxDate
原交易日期
A
8
M
YYYYMMDD
orgTxTime
原交易时间
A
6
M
hhmmss
orgSeqNo
原交易流水号
N
6
M
定长6位
txAmount
交易金额
N
12,2
M
还款金额
payAccountId
付款账号
A
32
M
noticeAddress
推送地址
A
256
C
name
姓名
A
60
M
txstsFlag
退汇标志
A
1
M
1:
是,0否
note
摘要
A
840
C
acqRes
请求方保留
A
200
C
【响应参数】
平台收到即信线下充值回调后,请返回“success”响应。
2.2.5.满标自动放款
功能说明:
当一个标的满标后,平台自动触发该交易,交易成功后放款金额放到借款人电子账户。
针对该标的,只能满标自动划扣一笔。
调用方式:
接口调用
【请求参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
autoLendPay
instCode
机构代码
A
8
M
bankCode
银行代码
A
8
M
txDate
交易日期
A
8
M
YYYYMMDD
txTime
交易时间
A
6
M
hhmmss
seqNo
交易流水号
N
6
M
定长6位
channel
交易渠道
A
6
M
000001手机APP
000002网页
000003微信
000004柜面
accountId
借款人电子账号
A
19
M
orderId
订单号
A
30
M
由P2P生成,必须保证唯一
txAmount
交易金额
N
12,2
M
feeAmount
手续费金额
N
12,2
M
riskAmount
风险准备金
N
12,2
M
productId
标的号
A
40
M
投资人投标成功的标的号
acqRes
请求方保留
A
200
C
【响应参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
同请求
instCode
机构代码
A
8
M
同请求
bankCode
银行代码
A
8
M
同请求
txDate
交易日期
A
8
M
同请求
txTime
交易时间
A
6
M
同请求
seqNo
交易流水号
N
6
M
同请求
channel
交易渠道
A
6
M
000001手机APP
000002网页
000003微信
000004柜面
retCode
响应代码
A
8
C
retMsg
响应描述
A
60
C
accountId
电子账号
A
19
M
同请求
orderId
订单号
A
30
C
同请求
txAmount
交易金额
N
12,2
C
同请求
feeAmount
手续费金额
N
12,2
M
同请求
riskAmount
风险准备金
N
12,2
M
同请求
productId
标的号
A
40
C
同请求
name
姓名
A
60
C
acqRes
请求方保留
A
200
C
同请求
2.2.6.满标自动放款查询
功能说明:
用于满标放款查询。
当不确认满标实时放款是否成功,可以调用该接口查询。
调用方式:
接口调用
【请求参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
autoLendPayQuery
instCode
机构代码
A
8
M
bankCode
银行代码
A
8
M
txDate
交易日期
A
8
M
YYYYMMDD
txTime
交易时间
A
6
M
hhmmss
seqNo
交易流水号
N
6
M
定长6位
channel
交易渠道
A
6
M
000001手机APP
000002网页
000003微信
000004柜面
accountId
借款人电子账号
A
19
M
lendPayOrderId
申请订单号
A
40
M
满标放款交易订单号
productId
标的编号
A
40
M
acqRes
请求方保留
A
100
C
供第三方平台使用,原样返回
【响应参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
同请求
instCode
机构代码
A
8
M
同请求
bankCode
银行代码
A
8
M
同请求
txDate
交易日期
A
8
M
同请求
txTime
交易时间
A
6
M
同请求
seqNo
交易流水号
N
6
M
同请求
channel
交易渠道
A
6
M
000001手机APP
000002网页
000003微信
000004柜面
retCode
响应代码
A
8
C
retMsg
响应描述
A
60
C
accountId
借款人电子账号
A
19
M
同请求
name
借款人姓名
A
60
C
productId
标的编号
A
40
M
同请求
txAmount
借款人入账金额
N
13,2
C
feeAmount
手续费金额
N
12,2
C
riskAmount
风险准备金
N
12,2
C
acqRes
请求方保留
A
100
C
供第三方平台使用,原样返回
2.2.7.自动购买债权
功能说明:
P2P平台自动为签约投资人购买债权,资金会实时从债权的购买方电子账户转到卖出方电子账户
调用方式:
接口调用
【请求参数】
字段名
字段描述
类型
最大长度
必填
备注
version
版本号
A
2
M
目前为10
txCode
交易代码
A
50
M
creditAutoInvest
instCode
机构代码
A
8
M
bankCode
银行代码
A
8
M
txDate
交易日期
A
8
M
YY