上海銀行-快捷支付接口規(guī)范(版本號v3.6.6) ,前言本文檔介紹上海銀行“快捷支付”的技術(shù)標(biāo)準(zhǔn)，此接口標(biāo)準(zhǔn)適應(yīng)借記卡快捷支付及信用卡快捷支付。其中包括業(yè)務(wù)處理與系統(tǒng)交互方

上海銀行-快捷支付

接口規(guī)范

(版本號v3.6.6)

前言

本文檔介紹上海銀行“快捷支付”的技術(shù)標(biāo)準(zhǔn)，此接口標(biāo)準(zhǔn)適應(yīng)借記卡快捷支付及信用卡快捷支付。其中包括業(yè)務(wù)處理與系統(tǒng)交互方式、報(bào)文的語法與語義、網(wǎng)絡(luò)連接方式、安全規(guī)范等。

第1章 文檔概述 1.1 介紹

1.1.1 概述

本文檔闡述的技術(shù)標(biāo)準(zhǔn)，為更加快捷安全的互聯(lián)網(wǎng)支付結(jié)算提供了解決方案。

1.1.2 目標(biāo)讀者

本文檔的主要目標(biāo)讀者是銀行與商戶的技術(shù)實(shí)施人員，也可供業(yè)務(wù)人員參考。

1.1.3 最近修訂

第2章 報(bào)文結(jié)構(gòu)

上海銀行快捷支付報(bào)文規(guī)范規(guī)定了上海銀行與商戶之間交換報(bào)文的處理規(guī)范。

2.1 報(bào)文結(jié)構(gòu)

快捷支付報(bào)文統(tǒng)一采用xml 格式。所有的快捷支付報(bào)文均以Banksh 作為根元素，每個Banksh 元素中可以包含多個Message 元素。

Message 元素中包含代表具體的業(yè)務(wù)的元素，比如CSVReq 、CSVRes 等。每個業(yè)務(wù)元素由一系列屬性元素構(gòu)成，不同的業(yè)務(wù)元素中包含的屬性元素有所不同。

對于涉及到簽約狀態(tài)修改或者資金變動的業(yè)務(wù)元素，必須要有與之匹配的Signature 元素進(jìn)行數(shù)字簽名。

作為約定，Banksh 元素、Message 元素與業(yè)務(wù)元素均是首字母大寫的CamelCase 形式，所有的屬性元素均是首字母小寫的CamelCase 形式。

以簽約請求報(bào)文為例，報(bào)文的格式如下：

Message id 定義為不重復(fù)的隨機(jī)數(shù)，以防止報(bào)文重復(fù)提交；

在下文中出現(xiàn)的具體報(bào)文格式描述中，“出現(xiàn)要求”列包含的值的含義如下表所示：

2.2 報(bào)文分類

快捷支付協(xié)議中的報(bào)文按照交互模式的不同，分為以下幾類：

? 服務(wù)請求類報(bào)文

服務(wù)請求類報(bào)文用于請求-應(yīng)答交互模式，由服務(wù)使用者向服務(wù)提供者發(fā)送。服務(wù)請求類報(bào)文的命令規(guī)范是XXReq ，其中XX 是報(bào)文代表的業(yè)務(wù)的首字母縮略，Req 是Request 的縮寫。比如對于支付請求報(bào)文，命名為CPReq ，代表Card Payment Request。

? 服務(wù)應(yīng)答類報(bào)文

服務(wù)應(yīng)答類報(bào)文用于請求-應(yīng)答交互模式，由服務(wù)提供者向服務(wù)使用者返回。服務(wù)應(yīng)答類報(bào)文的命令規(guī)范是XXRes ，其中XX 是報(bào)文代表的業(yè)務(wù)的首字母縮略，Res 是Response 的縮寫。比如對于支付應(yīng)答報(bào)文，命名為CPRes ，代表

Card Payment Response 。

? 通知類報(bào)文

通知類報(bào)文用于單向通知交互模式，由通知發(fā)送者向通知接收者發(fā)送。通知類報(bào)文的命令規(guī)范是XXNotify ，其中XX 是報(bào)文代表的業(yè)務(wù)的首字母縮略。

? 通用報(bào)文

有兩種通用報(bào)文，一種是Error 報(bào)文，用于返回處理錯誤；另一種是NotifyAccept ，代表單向通知已被接受。

2.3 通用報(bào)文

2.3.1 錯誤代碼

2.3.2 NotifyAccept報(bào)文

? 功能

用來代表單向通知已被接受。 ? 消息域

下表列舉了消息域的定義

2.4 報(bào)文的解析與傳輸

快捷支付報(bào)文的傳輸使用HTTP(S)方式，在HTTP 請求/響應(yīng)體中包含XML 形式的報(bào)文。

2.4.1 報(bào)文解析

對XML 解析的基本要求如下： ? 版本號檢查

用于表示組件支持的協(xié)議版本號。消息版本號必須表示為：n .n [.n ] ，其中 “n” 表示數(shù)字，“ ”表示一個或多個。比如1.0或1.0.1。在所有的消息中，各組件都必須填寫自身支持的協(xié)議版本號。消息版本號不能低于1.0.1。 ? xml 解析

為了可以支持后續(xù)協(xié)議版本，xml 解析的實(shí)現(xiàn)不要做嚴(yán)格的驗(yàn)證。特別是需要忽略未被確認(rèn)的域。所有xml 消息必須用“utf-8”編碼。 ? Message 域之id 屬性匹配

請求和應(yīng)答報(bào)文的Message 域之id 屬性必須相同，id 是請求方生成的唯一序列號。比如：銀行在CSReq 的Message 域設(shè)置了一個id 屬性值，則商戶在CSRes 里面的Message 域的id 屬性必須和CSReq 的Message 域之id 值相同。

2.4.2 報(bào)文傳輸

對HTTPS 傳輸?shù)幕疽笕缦拢?/p>

? 使用POST 發(fā)送消息

消息請求基于HTTP/HTTPS的POST 方式。

? HTTP 消息頭要求

HTTP 請求與響應(yīng)消息中必須按照如下要求設(shè)置頭部域：

?Content-Length:?必須設(shè)置成消息體的長度

?Content-Type:?必須設(shè)置下面的值：application/xml; charset=utf-8

第3章 文件交換規(guī)范

3.1 文件命名規(guī)范

文件命名規(guī)范對文件名稱進(jìn)行統(tǒng)一的規(guī)劃，以達(dá)到從文件名稱上區(qū)分不同業(yè)務(wù)文件的目的。文件命名規(guī)范：filetype_yyyymmdd_sequence.zip，其中：

filetype ——文件類型，如：BRF –批量退款文件；BRRF-批量退款結(jié)果文件；CCF ——清算對賬文件；INFO- 商戶信息文件；

yyyymmdd ——文件業(yè)務(wù)日

sequence ——批次號，以01，02，03遞增，與商戶一般1天交互一次，故批次號固定為“01” 例如：

CCF_20100222_01.zip （清算對賬文件）

3.2 文件壓縮

傳輸前需要壓縮成zip 格式。

3.3 文件加密

對壓縮后的文件，需要加密之后再傳輸。加密時采用三重DES 對稱加密算法3DES 。加密密鑰按事先約定方式分發(fā)。

3.4 文件摘要

對加密后的文件進(jìn)行摘要。摘要算法使用標(biāo)準(zhǔn)SHA1算法，結(jié)果表示成40位16進(jìn)制大寫字母數(shù)字串。

在商戶往銀行發(fā)送文件下載請求時需對若干域進(jìn)行摘要，具體可參考文件下載章節(jié)描述； 在銀行往商戶反饋文件時，需對文件進(jìn)行摘要，文件摘要商戶可從 https 的response 的head

域里面的Banksha1域的值獲取摘要，從Banksign 域的值獲取簽名。

3.5 文件下載（銀行端URL ）

文件采用商戶主動請求從銀行文件服務(wù)下載的方式。 例如銀行文件服務(wù)的URL 格式如下：

date ——交易日期yyyymmdd 。

filename ——遵循業(yè)務(wù)文件命名規(guī)范的文件名。 KoalB64Cert ——商戶公鑰Base64位編碼

sign ——使用certId 指定的證書對“actiontype|instId|date|filename”進(jìn)行簽名，對簽 名結(jié)果進(jìn)行Base64編碼獲得的字符串, 詳情見簽名規(guī)范。

3.6 文件下載失敗http 狀態(tài)碼

1、406：商戶標(biāo)識不匹配 2、405：操作類型不正確 3、420：銀行端驗(yàn)簽失敗 4、404：請求文件名不存在 5、409：請求文件格式不正確

第4章 接口實(shí)現(xiàn)規(guī)范 4.1 接口實(shí)現(xiàn)說明

4.2身份鑒權(quán)

4.2.1業(yè)務(wù)功能

銀行接收商戶要求身份鑒權(quán)的交易請求，必須包含客戶卡號、客戶姓名、客戶證件類型、客戶證件號碼、手機(jī)號碼等信息，銀行核對卡號對應(yīng)的信息與客戶提供的信息一致型，如一致反饋匹配，否則反饋不匹配。

4.2.2業(yè)務(wù)規(guī)則

? 由于快捷支付的簽約是在商戶端完成的，銀行只是提供身份鑒權(quán)，協(xié)助商戶驗(yàn)證信息的匹配性。商戶必須為客戶身份驗(yàn)證承擔(dān)責(zé)任，確保是持卡人本人，銀行不承擔(dān)責(zé)任。 ? 快捷支付簽約用戶的必須持有手機(jī)，且手機(jī)號為用戶在銀行端開卡時所登記的手機(jī)號。 ? 銀行身份鑒權(quán)，暫定為核對卡對應(yīng)的客戶姓名、證件類型、證件號碼、手機(jī)號碼，可根據(jù)實(shí)際情況調(diào)整。

? 建議商戶在快捷支付簽約成功后發(fā)手機(jī)短信通知客戶。

4.2.3交互模式

在身份鑒權(quán)業(yè)務(wù)中，商戶與上海銀行通過請求-應(yīng)答模式交互。

商戶作為服務(wù)使用者向銀行發(fā)送“身份鑒權(quán)申請”報(bào)文IAReq ，銀行作為服務(wù)提供者向商戶返回“簽約應(yīng)答”報(bào)文IARes 。