某银行快捷支付接口规范DOCX 38页.docx
《某银行快捷支付接口规范DOCX 38页.docx》由会员分享，可在线阅读，更多相关《某银行快捷支付接口规范DOCX 38页.docx（63页珍藏版）》请在冰豆网上搜索。
某银行快捷支付接口规范DOCX38页
某银行快捷支付接口规范（DOCX38页）
上海银行-快捷支付
接口规范
（版本号v3.6.6）
前言
本文档介绍上海银行“快捷支付”的技术标准，此接口标准适应借记卡快捷支付及信用卡快捷支付。
其中包括业务处理与系统交互方式、报文的语法与语义、网络连接方式、安全规范等。
第1章文档概述
1.1介绍
1.1.1概述
本文档阐述的技术标准，为更加快捷安全的互联网支付结算提供了解决方案。
1.1.2目标读者
本文档的主要目标读者是银行与商户的技术实施人员，也可供业务人员参考。
1.1.3最近修订
版本号
作者
内容提要
核准人
发布日期
1.0
黄敦迪
定义上海银行快捷支付接口规范
蔡红林
2012-06-1
2.0
黄敦迪
删除快捷支付业务概述；调整错误代码；重定义身份鉴权报文头；删除单笔提现接口；删除批量交易明细查询，新增单笔交易明细查询
黄敦迪
2012-6-13
3.0
黄敦迪
增加批量交易明细查询，修改错误代码
黄敦迪
2013-3-11
3.1
黄敦迪
修改身份鉴权、网上支付、单笔退款、批量退款接口，加入了卡代号等
2013-3-12
3.2
黄敦迪
鉴权需中账户姓名改为必输
2013-4-11
3.3
黄敦迪
接口实现说明中批量交易查询改为非必须实现的接口。
批量交易查询请求报文中加入订单号列表
2013-4-19
3.4
彭小波
修改身份鉴权接口，CVV2、有效期改为可选字段，增加KoalB64Cert;修改网上支付接口CVV2、有效期改为可选字段，返回报文银行卡改为卡代号，
黄敦迪
2013-4-22
3.5.1
彭小波
批量交易查询增加爱业务规则：
订单最多支持10笔;
查询的多条订单只返回符合条件的记录。
2013-4-28
3.5.2
彭小波
为单笔退款增加错误代码：
4045
2013-5-2
3.5.3
黄敦迪
单笔交易明细查询应答报文中status枚举值调整及定义errorCode的取值；批量交易查询应答报文TradeInfo清单中的signNo改为cardNo
2013-5-11
3.5.4
彭小波
错误码不再分类别
扩展鉴权的证件类别
鉴权中增加校验规则，手机号码必须为11位
明确单笔订单查询中的交易日期和时间
2013-5-17
3.5.5
彭小波
调整错误码描述：
3006对应描述改为卡号不存在或不支持的银行卡
3016对应描述改为银行账户交易失败
批量交易查询的交易状态进行调整：
0000成功；0001失败
2013-5-18
3.5.6
彭小波
3003的errormessage从“身份证号码不匹配”改为“身份证件号码不匹配”
2013-5-21
3.5.7
彭小波
针对信用卡的CVV2和有效期，增加对应的错误码：
3050和3051
2013-5-24
3.5.8
彭小波
身份鉴权增加业务逻辑：
CVV2和有效期需同时输入或同时都不输入
2013-5-24
3.5.9
彭小波
网上支付去除：
CVV2和有效期
2013-5-27
3.6
黄敦迪
删除二级商户信息同步接口，增加单笔撤消接口
2013-6-20
3.6.1
彭小波
批量交易查询响应报文中交易信息列表tradeInfoList签名要求由”Y”变更为”N”
2013-6-26
3.6.2
彭小波
新增错误码：
4046清算的订单不能做撤销处理
2013-6-27
3.6.3
彭小波
银行流水号由char（19）统一更改为char（20）,修改点：
网上支付、单笔退款、单笔撤消
2013-6-27
3.6.4
彭小波
清算对账中文件格式中银行卡号修正为银行卡代号
2013-7-1
3.6.5
彭小波
单笔撤消上送报文增加交易金额，同时增加校验：
交易金额必须和原订单交易金额一致
2013-7-2
3.6.6
彭小波
清算对账增加业务规则：
信用卡撤消及对应原订单不在清算对账文件内。
2013-7-5
第2章报文结构
上海银行快捷支付报文规范规定了上海银行与商户之间交换报文的处理规范。
2.1报文结构
快捷支付报文统一采用xml格式。
所有的快捷支付报文均以Banksh作为根元素，每个Banksh元素中可以包含多个Message元素。
Message元素中包含代表具体的业务的元素，比如CSVReq、CSVRes等。
每个业务元素由一系列属性元素构成，不同的业务元素中包含的属性元素有所不同。
对于涉及到签约状态修改或者资金变动的业务元素，必须要有与之匹配的Signature元素进行数字签名。
作为约定，Banksh元素、Message元素与业务元素均是首字母大写的CamelCase形式，所有的属性元素均是首字母小写的CamelCase形式。
以签约请求报文为例，报文的格式如下：
…
…
…
…
…
…
…
…
…
…
| … |
…
…
……
Messageid定义为不重复的随机数，以防止报文重复提交；
在下文中出现的具体报文格式描述中，“出现要求”列包含的值的含义如下表所示：
含义
请求方约束
服务方约束
R
Required
必须包含该域
必须校验该域是否存在和内容的合法性
C
Conditional
如果条件符合必须包含该域
●当条件满足时，必须校验该域是否存在
●当该域存在时，必须检查其内容的合法性
O
Optional
该域可选
当该域存在时，必须检查其内容的合法性
2.2报文分类
快捷支付协议中的报文按照交互模式的不同，分为以下几类：
⏹服务请求类报文
服务请求类报文用于请求-应答交互模式，由服务使用者向服务提供者发送。
服务请求类报文的命令规范是XXReq，其中XX是报文代表的业务的首字母缩略，Req是Request的缩写。
比如对于支付请求报文，命名为CPReq，代表CardPaymentRequest。
⏹服务应答类报文
服务应答类报文用于请求-应答交互模式，由服务提供者向服务使用者返回。
服务应答类报文的命令规范是XXRes，其中XX是报文代表的业务的首字母缩略，Res是Response的缩写。
比如对于支付应答报文，命名为CPRes，代表CardPaymentResponse。
⏹通知类报文
通知类报文用于单向通知交互模式，由通知发送者向通知接收者发送。
通知类报文的命令规范是XXNotify，其中XX是报文代表的业务的首字母缩略。
⏹通用报文
有两种通用报文，一种是Error报文，用于返回处理错误；另一种是NotifyAccept，代表单向通知已被接受。
2.3通用报文
2.3.1错误代码
⏹银行返回的错误代码说明：
错误代码
错误描述
解释
0000
无效的根元素
根元素无法识别
0001
未定义的消息域
消息不是CSReq、CSRes等；或者消息发送给了一个错误的组件
0002
必填域缺失
0003
根据规范，一个或多个域不符合格式要求
例如，非数字，或者不是有效的日期格式等等。
0004
商户标识不正确
instId域中的商户标识不正确
0005
签名无效
报文签名校验不通过
0006
验证证书有效性失败
商户证书过期或失效
1000
文件格式不正确
商户批处理业务上传文件不正确
1001
文件不存在
下载文件时，找不到指定的文件
1002
文件已处理
对于不允许重复处理的业务的文件，如果已处理过，就发生此错误
1003
文件无法解压缩
上传的文件无法正确解压缩
1004
文件摘要不正确
文件上传通知报文中的文件摘要不正确
2001
支付流水重复
重复的网上支付流水
2002
原支付流水不存在
申请退货的原支付流水不存在
2003
查询范围太大
查询时间跨度太大
2004
退款订单日期错误
退款订单日期小于原订单日期
2005
当日撤销必须为全额退款
业务要求：
当日撤销必须为全额
3001
真实姓名不正确
真实姓名与商户端登记的不一致
3002
证件类型不正确
证件类型与商户端登记的不一致
3003
身份证件号码不匹配
身份证件号码与商户端登记的身份证件号码不匹配
3004
手机号不匹配
3005
不支持的银行卡类型
3006
卡号不存在或不支持的银行卡
3007
未鉴权的银行卡
未做过鉴权的银行卡（卡代号不存在时）
3008
认证信息不匹配
认证信息与商户通过认证的信息不匹配
3009
银行卡状态不正确
银行卡状态不正确
3011
原支付申请流水不存在
支付申请流水不存在（用于退款）
3013
金额超限
支付金额超过每日限额（退款时超出原订单金额也用这个）
3014
余额不足
银行账户中的余额不足以完成支付
3015
银行交易处理中
该笔交易在银行前置系统中状态未知
3016
银行账户交易失败
银行系统的错误返回。
3050
有效期错误或卡已过期
对信用卡有效期的校验，信用卡有效期输错，或信用卡已过有效期
3051
CVV2错误
信用卡CVV2的校验
4045
未清算的订单不能做退款处理
不支持当日退款
4001
快捷支付渠道关闭
没有开通快捷支付业务
4002
服务没有开通
请求的业务没有开通
4046
清算的订单不能做撤销处理
清算的订单不允许做撤销处理
9000
暂时系统异常
通用性错误
2.3.2NotifyAccept报文
⏹功能
用来代表单向通知已被接受。
⏹消息域
下表列举了消息域的定义
中文域名
对应DTD元素
类型
出现要求
签名要求
说明
版本号
version
char（7）
R
N
目前版本号：
”1.0.1”
商户标识
instId
char（15）
R
Y
报文发送方的商户标识
流水号
orderNum
char（30）
R
Y
原商户提交的信息流水号
交易日期和时间
date
char（17）
R
Y
YYYYMMDDHH:
MM:
SS
结果代码
errorCode
char（4）
R
Y
SUCC表示成功
其他均为失败
错误描述
errorMessage
char（256）
O
N
消息扩展
extension
O
N
2.4报文的解析与传输
快捷支付报文的传输使用HTTP（S）方式，在HTTP请求/响应体中包含XML形式的报文。
2.4.1报文解析
对XML解析的基本要求如下：
⏹版本号检查
用于表示组件支持的协议版本号。
消息版本号必须表示为：
n+.n+[.n+]，其中“n”表示数字，“+”表示一个或多个。
比如1.0或1.0.1。
在所有的消息中，各组件都必须填写自身支持的协议版本号。
消息版本号不能低于1.0.1。
⏹xml解析
为了可以支持后续协议版本，xml解析的实现不要做严格的验证。
特别是需要忽略未被确认的域。
所有xml消息必须用“utf-8”编码。
⏹Message域之id属性匹配
请求和应答报文的Message域之id属性必须相同，id是请求方生成的唯一序列号。
比如：
银行在CSReq的Message域设置了一个id属性值，则商户在CSRes里面的Message域的id属性必须和CSReq的Message域之id值相同。
2.4.2报文传输
对HTTPS传输的基本要求如下：
⏹使用POST发送消息
消息请求基于HTTP/HTTPS的POST方式。
⏹HTTP消息头要求
HTTP请求与响应消息中必须按照如下要求设置头部域：
‘Content-Length:
’必须设置成消息体的长度
‘Content-Type:
’必须设置下面的值：
application/xml;charset=utf-8
第3章文件交换规范
3.1文件命名规范
文件命名规范对文件名称进行统一的规划，以达到从文件名称上区分不同业务文件的目的。
文件命名规范：
filetype_yyyymmdd_sequence.zip，其中：
filetype——文件类型，如：
BRF–批量退款文件；BRRF-批量退款结果文件；CCF——清算对账文件；INFO-商户信息文件；
yyyymmdd——文件业务日
sequence——批次号，以01，02，03递增，与商户一般1天交互一次，故批次号固定为“01”
例如：
CCF_20100222_01.zip（清算对账文件）
3.2文件压缩
传输前需要压缩成zip格式。
3.3文件加密
对压缩后的文件，需要加密之后再传输。
加密时采用三重DES对称加密算法3DES。
加密密钥按事先约定方式分发。
3.4文件摘要
对加密后的文件进行摘要。
摘要算法使用标准SHA1算法，结果表示成40位16进制大写字母数字串。
在商户往银行发送文件下载请求时需对若干域进行摘要，具体可参考文件下载章节描述；
在银行往商户反馈文件时，需对文件进行摘要，文件摘要商户可从https的response的head域里面的Banksha1域的值获取摘要，从Banksign域的值获取签名。
3.5文件下载（银行端URL）
文件采用商户主动请求从银行文件服务下载的方式。
例如银行文件服务的URL格式如下：
http（s）:
//&actiontype=download&date=20100204&finename=SCF_20100222_01.zip
&KoalB64Cert=xxxxxx&sign=xxxxxx，其中：
http（s）:
//
actiontype——操作类型（如：
upload表示上传、download表示下载）。
instId——商户标识。
date——交易日期yyyymmdd。
filename——遵循业务文件命名规范的文件名。
KoalB64Cert——商户公钥Base64位编码
sign——使用certId指定的证书对“actiontype|instId|date|filename”进行签名，对签
名结果进行Base64编码获得的字符串,详情见签名规范。
3.6文件下载失败http状态码
1、406：
商户标识不匹配
2、405：
操作类型不正确
3、420：
银行端验签失败
4、404：
请求文件名不存在
5、409：
请求文件格式不正确
第4章接口实现规范
4.1接口实现说明
序号
接口类型
交易类型
描述
必须
1
身份鉴权
实时
商户发起的实名签约验证
Y
2
网上支付
实时
Y
3
单笔退款
实时
Y
4
批量退款
批量
N
5
单笔交易明细查询
实时
Y
6
批量交易查询
实时
N
7
清算对帐
批量
Y
8
单笔撤消
实时
N
4.2身份鉴权
4.2.1业务功能
银行接收商户要求身份鉴权的交易请求，必须包含客户卡号、客户姓名、客户证件类型、客户证件号码、手机号码等信息，银行核对卡号对应的信息与客户提供的信息一致型，如一致反馈匹配，否则反馈不匹配。
4.2.2业务规则
⏹由于快捷支付的签约是在商户端完成的，银行只是提供身份鉴权，协助商户验证信息的匹配性。
商户必须为客户身份验证承担责任，确保是持卡人本人，银行不承担责任。
⏹快捷支付签约用户的必须持有手机，且手机号为用户在银行端开卡时所登记的手机号。
⏹银行身份鉴权，暂定为核对卡对应的客户姓名、证件类型、证件号码、手机号码，可根据实际情况调整。
⏹建议商户在快捷支付签约成功后发手机短信通知客户。
4.2.3交互模式
在身份鉴权业务中，商户与上海银行通过请求-应答模式交互。
商户作为服务使用者向银行发送“身份鉴权申请”报文IAReq，银行作为服务提供者向商户返回“签约应答”报文IARes。
涉及到以下交互：
1、商户将数据发送到银行的身份鉴权服务接口，商户需调用银行API利用数字证书进行加密，签名。
（见数字签名）
2、银行端校验通过核实客户信息，并在同一个连接中返回IARes报文告诉银行商户验证情况。
银行会对返回数据进行加密，签名。
3、商户端接口银行应答报文后，验签、解析报文后做后续处理。
4.2.4报文格式
⏹鉴权请求报文IAReq（IdentityAuthenticationRequest）
IAReq是从商户向银行发起的签约请求报文。
中文域名
对应DTD元素
类型
出现要求
签名要求
说明
版本号
version
char（7）
R
N
目前版本号：
”1.0.1”
商户标识
instId
char（15）
R
Y
由银行分配固定值,请求报文中需填写
交易日期和时间
date
char（17）
R
Y
YYYYMMDDHH:
MM:
SS
客户姓名
name
char（30）
R
Y
签约银行卡号
cardNo
char（20）
R
Y
签约银行卡类型
cardType
char
（1）
R
Y
1借记卡2贷记卡
证件类型
certType
char
（1）
R
Y
1：
身份证；
2：
护照；
3：
军官证；
4：
士兵证；
5：
户口本；
6：
警官证；
7：
台胞证
证件号码
certNo
char（30）
R
Y
手机号
mobilePhone
Char（20）
R
Y
持卡人在银行留的手机号
手机号必须为11位
CVV2
cvv2
Char（3）
O
N
卡背面签名栏的后三位数字
CVV2和有效期需同时输入或同时都不输入
有效期
validity
Char（4）
O
N
MMYY
CVV2和有效期需同时输入或同时都不输入
经过Base64处理的商户证书代码
KoalB64Cert
/
R
N
商户端读取本地商户证书文件后，再使用上海银行提供的API进行Base64编码后产生的商户证书数据字串。
消息扩展
extension
O
N
⏹签约应答报文IARRes（IdentityAuthenticationResponse）
IARRes银行返回给商户的应答。
中文域名
对应DTD元素
类型
出现要求
签名要求
说明
版本号
version
char（7）
R
N
目前版本号：
”1.0.1”
商户标识
instId
char（15）
R
Y
报文发送方的商户标识
银行卡号
cardNo
char（20）
R
Y
银行卡代码
cardCode
Char（20）
R
Y
唯一区分银行卡代码
交易日期和时间
date
char（17）
R
Y
YYYYMMDDHH:
MM:
SS
结果代码
errorCode
char（4）
R
Y
成功SUCC，失败见错误代码
错误描述
errorMessage
char（256）
O
N
消息扩展
extension
O
N
4.3网上支付
4.3.1业务功能
商户负责验证客户持卡人身份与服务权限，并请求银行划拨客户的资金用于互联网交易的支付；银行负责验证由商户发出的支付指令是否在快捷支付签约的业务范围与银行控制的快捷支付支付限额内，并实时扣减签约银行卡内的余额。
由于网上支付引起的银行与商户间的资金清算方法由快捷支付清算标准规定。
4.3.2业务规则
该交易在执行中需要满足以下约束条件：
⏹支付必须由客户请求，从合作商户发起（可以网上、网点等渠道）。
⏹商户控制支付的资金只能从快捷支付签约时确定的签约银行卡账户中支出。
银行端做无磁无密交易。
⏹支付时客户在签约银行卡账户中的资金只能转移到商户指定的清算账户中。
⏹同一支付订单号的支付交易，银行端限定只能执行一次，永不重复。
⏹银行与商户需要保存支付相关报文的日志作为解决资金清算不一致的依据。
4.3.3处理流程
4.3.4交互模式
在支付业务中，商户与银行通过请求-应答模式交互。
商户作为服务使用者向银行发送“支付”请求报文CPReq，银行作为服务提供者向商户返回“网上支付”应答报文CPRes。
4.3.5报文格式
⏹“网上支付”请求报文CPReq（CardPaymentRequest）
网上支付报文请求CPReq（CardPaymentRequest）是从商户向银行发起的支付请求。
中文域名
对应DTD元素
类型
出现要求
签名要求
说明
版本号
version
char（7）
R
N
目前版本号：
”1.0.1”
商户标识
instId
char（15）
R
Y
报文发送方的商户标识
二级商户代码
twoId
char（15）
C
N
二级商户代码
适用于有些商户需银行在账单或明细查询中显示其平台的二级商户名称
订单号
orderNum
char（30）
R
Y
商户支付订单号/流水号,永不重复
交易日期和时间
date
char（17）
R
Y
YYYYMMDDHH:
MM:
SS
卡代号
cardCode
char（20）
R
Y
鉴权时返回的卡代码
手续费
charge
Long（12）
O
N
预留字段，见金额格式说明
交易金额
amount
Long（12）
R
Y
见金额格式说明
交易货币代码
currency
char（3）
R
Y
见快捷支付货币代码表
经过Base64处理的商户证书代码
Koal
升级会员 