上海银行-快捷支付开发技术标准-3.6.6
上海银行-快捷支付接口规范(版本号v3.6.6) ,前言本文档介绍上海银行“快捷支付”的技术标准，此接口标准适应借记卡快捷支付及信用卡快捷支付。其中包括业务处理与系统交互方
上海银行-快捷支付
接口规范
(版本号v3.6.6)
前言
本文档介绍上海银行“快捷支付”的技术标准，此接口标准适应借记卡快捷支付及信用卡快捷支付。其中包括业务处理与系统交互方式、报文的语法与语义、网络连接方式、安全规范等。
第1章 文档概述 1.1 介绍
1.1.1 概述
本文档阐述的技术标准，为更加快捷安全的互联网支付结算提供了解决方案。
1.1.2 目标读者
本文档的主要目标读者是银行与商户的技术实施人员，也可供业务人员参考。
1.1.3 最近修订
第2章 报文结构
上海银行快捷支付报文规范规定了上海银行与商户之间交换报文的处理规范。
2.1 报文结构
快捷支付报文统一采用xml 格式。所有的快捷支付报文均以Banksh 作为根元素，每个Banksh 元素中可以包含多个Message 元素。
Message 元素中包含代表具体的业务的元素，比如CSVReq 、CSVRes 等。每个业务元素由一系列属性元素构成，不同的业务元素中包含的属性元素有所不同。
对于涉及到签约状态修改或者资金变动的业务元素，必须要有与之匹配的Signature 元素进行数字签名。
作为约定，Banksh 元素、Message 元素与业务元素均是首字母大写的CamelCase 形式，所有的属性元素均是首字母小写的CamelCase 形式。
以签约请求报文为例，报文的格式如下：
Message id 定义为不重复的随机数，以防止报文重复提交；
在下文中出现的具体报文格式描述中，“出现要求”列包含的值的含义如下表所示：
,
2.2 报文分类
快捷支付协议中的报文按照交互模式的不同，分为以下几类：
⏹ 服务请求类报文
服务请求类报文用于请求-应答交互模式，由服务使用者向服务提供者发送。服务请求类报文的命令规范是XXReq ，其中XX 是报文代表的业务的首字母缩略，Req 是Request 的缩写。比如对于支付请求报文，命名为CPReq ，代表Card Payment Request。
⏹ 服务应答类报文
服务应答类报文用于请求-应答交互模式，由服务提供者向服务使用者返回。服务应答类报文的命令规范是XXRes ，其中XX 是报文代表的业务的首字母缩略，Res 是Response 的缩写。比如对于支付应答报文，命名为CPRes ，代表
Card Payment Response 。
⏹ 通知类报文
通知类报文用于单向通知交互模式，由通知发送者向通知接收者发送。通知类报文的命令规范是XXNotify ，其中XX 是报文代表的业务的首字母缩略。
⏹ 通用报文
有两种通用报文，一种是Error 报文，用于返回处理错误；另一种是NotifyAccept ，代表单向通知已被接受。
2.3 通用报文
2.3.1 错误代码
,
2.3.2 NotifyAccept报文
⏹ 功能
用来代表单向通知已被接受。 ⏹ 消息域
下表列举了消息域的定义
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 格式如下：
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 接口实现说明
4.2身份鉴权
4.2.1业务功能
银行接收商户要求身份鉴权的交易请求，必须包含客户卡号、客户姓名、客户证件类型、客户证件号码、手机号码等信息，银行核对卡号对应的信息与客户提供的信息一致型，如一致反馈匹配，否则反馈不匹配。
4.2.2业务规则
⏹ 由于快捷支付的签约是在商户端完成的，银行只是提供身份鉴权，协助商户验证信息的匹配性。商户必须为客户身份验证承担责任，确保是持卡人本人，银行不承担责任。 ⏹ 快捷支付签约用户的必须持有手机，且手机号为用户在银行端开卡时所登记的手机号。 ⏹ 银行身份鉴权，暂定为核对卡对应的客户姓名、证件类型、证件号码、手机号码，可根据实际情况调整。
⏹ 建议商户在快捷支付签约成功后发手机短信通知客户。
4.2.3交互模式
在身份鉴权业务中，商户与上海银行通过请求-应答模式交互。
商户作为服务使用者向银行发送“身份鉴权申请”报文IAReq ，银行作为服务提供者向商户返回“签约应答”报文IARes 。
