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

上海銀行-快捷支付

接口規(guī)范

(版本號(hào)v3.6.6)

前言

本文檔介紹上海銀行“快捷支付”的技術(shù)標(biāo)準(zhǔn)，此接口標(biāo)準(zhǔn)適應(yīng)借記卡快捷支付及信用卡快捷支付。其中包括業(yè)務(wù)處理與系統(tǒng)交互方式、報(bào)文的語(yǔ)法與語(yǔ)義、網(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 作為根元素，每個(gè)Banksh 元素中可以包含多個(gè)Message 元素。

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

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

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

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

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

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

2.2 報(bào)文分類(lèi)

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

? 服務(wù)請(qǐng)求類(lèi)報(bào)文

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

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

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

Card Payment Response 。

? 通知類(lèi)報(bào)文

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

? 通用報(bào)文

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

2.3 通用報(bào)文

2.3.1 錯(cuò)誤代碼

2.3.2 NotifyAccept報(bào)文

? 功能

用來(lái)代表單向通知已被接受。 ? 消息域

下表列舉了消息域的定義

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

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

2.4.1 報(bào)文解析

對(duì)XML 解析的基本要求如下： ? 版本號(hào)檢查

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

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

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

2.4.2 報(bào)文傳輸

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

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

消息請(qǐng)求基于HTTP/HTTPS的POST 方式。

? HTTP 消息頭要求

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

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

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

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

3.1 文件命名規(guī)范

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

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

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

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

CCF_20100222_01.zip （清算對(duì)賬文件）

3.2 文件壓縮

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

3.3 文件加密

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

3.4 文件摘要

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

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

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

3.5 文件下載（銀行端URL ）

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

date ——交易日期yyyymmdd 。

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

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

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

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

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

4.2身份鑒權(quán)

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

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

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

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

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

4.2.3交互模式

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

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