上海銀行-快捷支付接口規范(版本號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 。