中國某銀行網(wǎng)上銀行網(wǎng)上支付接口規(guī)范

1、網(wǎng)上銀行商戶手冊PAGE 第 PAGE 14 頁 共 NUMPAGES 14 頁網(wǎng)上銀行商戶手冊B2C支支付接口口v1.00.0.3商戶手冊中國工商商銀行軟軟件開發(fā)發(fā)中心Copyyrigght Reeserrvedd目錄TOC o 1-3 h z u HYPERLINK l _Toc173203224 第 1 章業(yè)務(wù)務(wù)說明 PAGEREF _Toc173203224 h 33 HYPERLINK l _Toc173203225 第 2 章商戶戶接口 PAGEREF _Toc173203225 h 44 HYPERLINK l _Toc173203226 2.1支支付接口口 PAGEREF _T

2、oc173203226 h 5 HYPERLINK l _Toc173203227 2.1.1支付付接口表表單定義義 PAGEREF _Toc173203227 h 5 HYPERLINK l _Toc173203228 2.1.2trranDDataa數(shù)據(jù)定定義 PAGEREF _Toc173203228 h 6 HYPERLINK l _Toc173203229 2.1.3trranDDataa格式定定義 PAGEREF _Toc173203229 h 7 HYPERLINK l _Toc173203230 2.1.4表單單樣例 PAGEREF _Toc173203230 h 88 HYP

3、ERLINK l _Toc173203231 2.2通通知接口口 PAGEREF _Toc173203231 h 9 HYPERLINK l _Toc173203232 2.2.1通知知接口表表單定義義 PAGEREF _Toc173203232 h 9 HYPERLINK l _Toc173203233 2.2.2nootiffyDaata數(shù)數(shù)據(jù)定義義 PAGEREF _Toc173203233 h 10 HYPERLINK l _Toc173203234 2.2.3nootiffyDaata格格式定義義 PAGEREF _Toc173203234 h 11 HYPERLINK l _Toc

4、173203235 2.2.4表單單樣例 PAGEREF _Toc173203235 h 111 HYPERLINK l _Toc173203236 2.3說說明 PAGEREF _Toc173203236 h 122 HYPERLINK l _Toc173203237 第 3 章安全全APII說明 PAGEREF _Toc173203237 h 133 HYPERLINK l _Toc173203238 第 4 章開發(fā)發(fā)步驟 PAGEREF _Toc173203238 h 113業(yè)務(wù)說明明B2C在在線支付付接口實實現(xiàn)工行個人人網(wǎng)銀客客戶在工工行B22C商戶戶網(wǎng)站進進行消費費支付的的業(yè)務(wù)處處理

5、。新的1.0.00.3版版本同原原先版本本的主要要區(qū)別在在于通知知消息方方式的改改變。原1.00.0.0版本本和1.0.00.1版版本（擴擴充語言言字段以以支持英英文版）在訂單單中要求求商戶選選擇通知知方式，即1、需要銀銀行通知知交易結(jié)結(jié)果，22、不需需要銀行行通知交交易結(jié)果果而是商商戶主動動查詢；當(dāng)需要要通知時時，需要要在訂單單中提供供商戶接接收銀行行通知地地址，當(dāng)當(dāng)銀行處處理結(jié)束束后，會會在銀行行的后臺臺服務(wù)器器請求商商戶的此此地址，將交易易結(jié)果用用htttp連接接posst表單單形式提提交給商商戶，然然后返回回客戶交交易結(jié)果果頁面。新的1.0.00.3版版本不再再要求商商戶選擇擇通知方方

6、式，和和接收銀銀行通知知的地址址；此版版本要求求商戶在在提交訂訂單時，提供交交易處理理后返回回商戶的的地址，即完成成客戶從從商戶轉(zhuǎn)轉(zhuǎn)向到銀銀行進行行支付，處理后后又從銀銀行定向向回商戶戶網(wǎng)站的的閉環(huán)。在從銀銀行交易易頁面返返回商戶戶時，將將交易結(jié)結(jié)果作為為表單數(shù)數(shù)據(jù)提交交到商戶戶此返回回地址。處理的優(yōu)優(yōu)點：11、強制制完成交交易閉環(huán)環(huán)；2、無需銀銀行后臺臺發(fā)送通通知，客客戶不需要等等待商戶戶接收銀銀行通知知后才能能看到交交易結(jié)果果頁面，縮短響響應(yīng)時間間；3、通知方方式不再再局限于于htttp連接接和800端口，返回商商戶的地地址可以以使用hhttpps方式式和其他他商戶支支持的端端口，提提高安

7、全全性；4、銀銀行作為為交易的的一方，支持眾眾多商戶戶和客戶戶時，存存在一定定的帶寬寬和服務(wù)務(wù)器處理理壓力，使用客客戶返回回商戶方方式提供供交易結(jié)結(jié)果，可可有效減減少交易易掉單現(xiàn)現(xiàn)象，只只要客戶戶到了銀銀行的結(jié)結(jié)果頁面面，如果果還出現(xiàn)現(xiàn)掉單問問題，則則可能是是客戶和和商戶的的通訊等等方面的的問題。以下簡述述處理流流程：客戶在商商戶網(wǎng)站站瀏覽商商品信息息，簽訂訂訂單；商戶按照照工行BB2C支付付1.00.0.3接口口形成提提交數(shù)據(jù)據(jù)，并使使用工行行提供AAPI和和商戶證證書對訂訂單數(shù)據(jù)據(jù)簽名，形成fformm表單返返回客戶戶瀏覽器器，表單單acttionn地址指指向工行行接收商商戶訂單單信息的的

8、serrvleet；客戶確認(rèn)認(rèn)使用工工行支付付后，提提交此表表單到工工行；工行網(wǎng)銀銀系統(tǒng)接接收此筆筆訂單，對訂單單信息和和商戶信信息進行行檢查；通過檢查查則顯示示工行支支付頁面面，1.00.0.3版本本會提示示客戶輸輸入交易易卡號；客戶輸入入后提交交；銀行查詢詢客戶相相關(guān)信息息；返回客戶戶在銀行行的預(yù)留留信息；客戶確認(rèn)認(rèn)；返回交易易確認(rèn)頁頁面；不同類型型客戶使使用各自自認(rèn)證方方式進行行交易確確認(rèn)，支支持靜態(tài)態(tài)支付密密碼、動動態(tài)口令令卡、證證書簽名名；銀行校驗驗后進行行支付處處理；將結(jié)果形形成通知知消息并并有銀行行端簽名名信息，返回客客戶端；引導(dǎo)客戶戶返回商商戶網(wǎng)站站，地址址是訂單單中提供供的商

9、戶戶urll，此uurl支支持htttp和和htttps及及自定義義端口；B2C在在線支付付接口版版本說明明：0（基本本支付）1（支持持英文界界面）2（內(nèi)部部保留）3（保留留1.00.0.1功能能，優(yōu)化化通知方方式）4（商戶戶訂單中中指定支支付卡，不強制制使用e卡卡支付，不不允許客客戶的支支付卡透透支支付付，專門用用于基金金商戶進進行基金金直銷業(yè)業(yè)務(wù)，同同1.00.0.3通知知方式）通知消息息模式區(qū)區(qū)別：原有模式式：支付付處理后后，后臺臺發(fā)送商商戶通知知；新增模式式：支付付完成后后或客戶戶點擊“返回商商戶”，利用用客戶瀏瀏覽

10、器跳跳轉(zhuǎn)，完完成商戶戶通知的的轉(zhuǎn)發(fā)，后臺不不再單獨獨發(fā)送商商戶通知知。對于不同同類型商戶戶接口區(qū)區(qū)別：對于購物物類型商城城只支持持使用1.0.00.0/1.00.0.1/3對于基金金直銷類類型網(wǎng)站站商城只只支持使用用1.00.0.4商戶接口口接口定義義通過接接口名稱稱和接口口版本號號來標(biāo)識識，以便便將來的的擴展；新通知知方式的的B2CC接口稱稱為新模模式B22C接口口；原有有后臺發(fā)發(fā)送htttp通通知的方方式稱為為原模式式接口；支付接口口支付接口口表單定定義新模式接接口的交交易數(shù)據(jù)據(jù)整合到到一個xxml格格式串，作為表表單的一一項整體體提交，不再同同原來每每個字段段都是kkey

11、-vallue形形式；FORMM表單數(shù)數(shù)據(jù)如下下：變量名稱稱變量命名名長度定義義說明接口名稱稱inteerfaaceNNameeMAX(30)必輸，取值：“ICBBC_PPERBBANKK_B22C”接口版本本號inteerfaaceVVerssionnMAX(15)必輸，取值：“1.00.0.3”交易數(shù)據(jù)據(jù)trannDatta無限制必輸，簽簽名；整合所有有交易數(shù)數(shù)據(jù)形成成的xmml明文文串，并做做BASSE644編碼；具體格式式定義見見下文；注意：需有xmml頭屬屬性；整整個字段段使用BBASEE64編編碼；xml明明文中沒沒有回車車換行和和多余空空格；訂單簽名名數(shù)據(jù)merSSignnMsg

12、g無限制必輸，商戶使用用工行提提供的簽簽名APPI和商商戶證書書將trranDDataa的xmml明文文串進行行簽名，得到二二進制簽簽名數(shù)據(jù)據(jù)，然后后進行BBASEE64編編碼后得得到可視視的merrSiggnMssg；注意：簽簽名時是是針對ttrannDatta的xxml明明文，不不是將ttrannDatta進行行BASSE644編碼后后的串；商城證書書公鑰merCCertt無限制必輸，商戶用二二進制方方式讀取取證書公公鑰文件件后，進進行BAASE664編碼碼后產(chǎn)生生的字符符串；注：1、數(shù)據(jù)據(jù)中不能能包含“|”、“&”、“=”，這些些字符為為銀行端端程序保保留字符符；中文文變量使使用GBBK

13、編碼碼。2、從商商戶Poost過過來的數(shù)數(shù)據(jù)，參參數(shù)名的的名稱必必須與上上表中完完全相同同，名稱稱中的字字母大小小寫均要要相同，不能進進行隨意意更改(在foorm中中的提交交按鈕中中subbmitt不能有有Namme屬性性)；此此外，如如果其他他inpput 項的NNamee中使用用了雙引引號，如如：，則一定定注意在在引號內(nèi)內(nèi)不要包包含空格格，不要要寫成“merr URRL ”，如果果拼寫錯錯誤或者者多了空空格，將將造成數(shù)數(shù)據(jù)無法法識別，無法正正常進行行支付3、接口口名稱和和版本號號一定要要和上表表中相同同.。4、商戶戶提交數(shù)數(shù)據(jù)中的的空格將將被認(rèn)為為是有效效字符被被接收，請商戶戶開發(fā)時時注意

14、對對多余空空格的控控制。5、trranDDataa交易數(shù)數(shù)據(jù)的xxml串串需要有有xmll的頭，即trannDatta數(shù)據(jù)據(jù)定義變量名稱稱變量命名名長度定義義說明接口名稱稱inteerfaaceNNamee16必輸，取值：“ICBBC_PPERBBANKK_B22C”接口版本本號inteerfaaceVVerssionnMAX(15)必輸，取值：“1.00.0.3”交易日期期時間ordeerDaate=14必輸，格式為：YYYYYMMMDDHHHmmmss要求在銀銀行系統(tǒng)統(tǒng)當(dāng)前時時間的前前1小時時和后112小時時范圍內(nèi)內(nèi)，否則則判定交交易時間間非法。訂單號ordeeriddMAX(30)必輸，

15、客戶支付付后商戶戶網(wǎng)站產(chǎn)產(chǎn)生的一一個唯一一的定單單號，該該訂單號號應(yīng)該在在相當(dāng)長長的時間間內(nèi)不重重復(fù)。工工行通過過訂單號號加訂單單日期來來唯一確確認(rèn)一筆筆訂單的的重復(fù)性性。訂單金額額amouuntMAX(10)必輸，客戶支付付訂單的的總金額額，一筆筆訂單一一個，以以分為單單位。不不可以為為零，必必需符合合金額標(biāo)標(biāo)準(zhǔn)。支付幣種種curTTypee= 3必輸，用來區(qū)分分一筆支支付的幣幣種，目目前工行行只支持持使用人人民幣（0011）支付付。取值： “0011”商戶代碼碼merIIDMAX(20)必輸，唯一確定定一個商商戶的代代碼，由由商戶在在工行開開戶時，由工行行告知商商戶。商戶賬號號merAAc

16、cttMAX(19)必輸，商戶入賬賬賬號，只能交交易時指指定。（商戶付付給銀行行手續(xù)費費的賬戶戶，可以以在開戶戶的時候候指定，也可以以用交易易指定方方式；用用交易指指定方式式則使用用此商戶戶賬號）檢驗聯(lián)名名標(biāo)志veriifyJJoinnFlaag=1必輸， 取值“11”：客戶戶支付時時，網(wǎng)銀銀判斷該該客戶是是否與商商戶聯(lián)名名，是則則按上送送金額扣扣帳，否否則展現(xiàn)現(xiàn)未聯(lián)名名錯誤；取值“00”：不檢檢驗客戶戶是否與與商戶聯(lián)聯(lián)名，按按上送金金額扣帳帳。語言版本本LangguaggeMAX(10)選輸，默默認(rèn)為中中文版取值：“EN_US”為英文文版；取值：“ZH_CN”或其他他為中文文版。注意：大大小

17、寫敏敏感。商品編號號gooddsIDDMAX(30)選輸商品名稱稱gooddsNaameMAX(60)選輸商品數(shù)量量gooddsNuumMAX(10)選輸已含運費費金額carrriaggeAmmtMAX(10)選輸商城提示示merHHinttMAX(1200)選輸備注字段段1remaark11MAX(1000)選輸 單單位：字字節(jié)備注字段段2remaark22MAX(1000)選輸 單單位：字字節(jié)返回商戶戶URLLmerUURLMAX(10224)必輸必須合法法的URRL，交交易結(jié)束束，將客客戶引導(dǎo)導(dǎo)到商戶戶的此uurl，即通過過客戶瀏瀏覽器ppostt交易結(jié)結(jié)果信息息到商戶戶的此UURL返回

18、商戶戶變量merVVARMAX(10224)選輸商戶自定定義，當(dāng)當(dāng)返回銀銀行結(jié)果果時，作作為一個個隱藏域域變量，商戶可可以用此此變量維維護seessiion等等等。由由客戶端端瀏覽器器支付完完成后提提交通知知結(jié)果時時是明文文傳輸，建議商商戶對此此變量使使用額外外安全防防范措施施，如簽簽名、bbasee64trannDatta格式式定義trannDatta格式式(xmml格式式固定，選輸字字段的取取值可以以為空，標(biāo)簽需需保留)表單樣例例表單數(shù)據(jù)據(jù)：trannDatta對應(yīng)應(yīng)的xmml明文文：IICBCC_PEERBAANK_B2CC1.0.00.3200070072551055014420007

19、0772511050014-21334066254482000011002000EC22000008775020000220400901150229133000ZH_CN0001威尼尼熊2220請保保留包裝裝hhttpp:/loccalhhostt:90081/Newwb2cc_Paay_MMer.jsppttestt通知接口口通知接口口表單定定義變量名稱稱變量命名名長度定義義說明返回商戶戶變量merVVAR無限制取值：商商戶提交交接口中中merrVARR字段當(dāng)當(dāng)返回銀銀行結(jié)果果時，作作為一個個隱藏域域變量，商戶可可以用此此變量維維護seessiion等等等。由由客戶端端瀏覽器器支付完完成后提

20、提交通知知結(jié)果時時是明文文傳輸，建議商商戶對此此變量使使用額外外安全防防范措施施，如簽簽名、bbasee64，銀行端端將此字字段原樣樣返回通知結(jié)果果數(shù)據(jù)notiifyDDataa無限制銀行通知知消息，xmll格式定定義見下下文，提交商商戶時對對xmll明文串串進行了了basse644編碼；xml串串中沒有有回車換換行和多多余空格格；包含含xmll頭屬性性，且格格式固定；銀行對通通知結(jié)果果的簽名名數(shù)據(jù)signnMsgg無限制銀行使用用自己證證書對商商戶通知知消息nnotiifyDDataa字段的的xmll格式明明文串進進行的簽簽名，然后進進行BAASE664編碼碼后的字字符串。注意：簽簽名是對對

21、nottifyyDatta的xxml明明文進行行簽名，不是其其BASSE644編碼后后的串；簽名后后得到二二進制數(shù)數(shù)據(jù)，對對此數(shù)據(jù)據(jù)進行BBASEE64編編碼得到到siggnMssgnotiifyDDataa數(shù)據(jù)定定義變量名稱稱變量命名名長度定義義說明接口名稱稱inteerfaaceNNamee16取值：“ICBBC_PPERBBANKK_B22C”接口版本本號inteerfaaceVVerssionnMAX(15)取值：“1.00.0.3”交易日期期時間ordeerDaate=14格式為：YYYYYMMMDDHHHmmmss要求在銀銀行系統(tǒng)統(tǒng)當(dāng)前時時間的前前1小時時和后112小時時范圍內(nèi)內(nèi)，

22、否則則判定交交易時間間非法。訂單號ordeeriddMAX(30)客戶支付付后商戶戶網(wǎng)站產(chǎn)產(chǎn)生的一一個唯一一的定單單號，該該訂單號號應(yīng)該在在相當(dāng)長長的時間間內(nèi)不重重復(fù)。工工行通過過訂單號號加訂單單日期來來唯一確確認(rèn)一筆筆訂單的的重復(fù)性性。訂單金額額amouuntMAX(10)客戶支付付訂單的的總金額額，一筆筆訂單一一個，以以分為單單位。不不可以為為零，必必需符合合金額標(biāo)標(biāo)準(zhǔn)。支付幣種種curTTypee= 3用來區(qū)分分一筆支支付的幣幣種，目目前工行行只支持持使用人人民幣（0011）支付付。取值： “0011”商戶代碼碼merIIDMAX(20)唯一確定定一個商商戶的代代碼，由由商戶在在工行開開

23、戶時，由工行行告知商商戶。商戶賬號號merAAccttMAX(19)商戶收費費入賬賬賬號 （只能交交易時指指定）。檢驗聯(lián)名名標(biāo)志veriifyJJoinnFlaag=1取值“11”：客戶戶支付時時，網(wǎng)銀銀判斷該該客戶是是否與商商戶聯(lián)名名，是則則按上送送金額扣扣帳，否否則展現(xiàn)現(xiàn)未聯(lián)名名錯誤；取值“00”：不檢檢驗客戶戶是否與與商戶聯(lián)聯(lián)名，按按上送金金額扣帳帳?？蛻袈?lián)名名標(biāo)志JoinnFlaag=1客戶在銀銀行端是是否與商商城聯(lián)名名標(biāo)志位位。1客客戶聯(lián)名名 0客客戶未聯(lián)聯(lián)名聯(lián)名會員員號UserrNummMAX(40)聯(lián)名客戶戶在商戶戶的會員員號。銀行指令令序號TrannSerriallNoMAX(

24、30)銀行端指指令流水水號返回通知知日期時時間notiifyDDateeMAX(14)格式為：YYYYYMMMDDHHHmmmss訂單處理理狀態(tài)trannStaat=11-“交交易成功功，已清清算”；2-“交交易失敗敗”；3-“交交易可疑疑”錯誤描述述commmenttMAX(1000)錯誤描述述notiifyDDataa格式定定義notiifyDDataa格式(xmll格式固固定，選選輸字段段的取值值可以為為空，標(biāo)標(biāo)簽需保保留)表單樣例例表單數(shù)據(jù)據(jù)：notiifyDDataa對應(yīng)的的明文：ICCBC_PERRBANNK_BB2C322007707225100501142000

25、700725510550144-2113400625548220000102000ECC2000008875022000020440900150029113002000707725111044001交易易成功！說明商戶可能能收到的的銀行通通知指令成功功：只能有一一筆成功功、且要要驗證銀銀行簽名名、訂單單金額等等信息是是否與商商戶端記記錄一致致。指令失敗敗：注意可能能收到多多筆失敗敗。客戶戶支付失失敗時可可以重提提此筆訂訂單到銀銀行支付付。指令可疑疑：由于網(wǎng)銀銀系統(tǒng)與與后臺業(yè)業(yè)務(wù)處理理系統(tǒng)間間通訊異異常，造造成網(wǎng)銀銀不能確確認(rèn)支付付指令結(jié)結(jié)果，則則此筆指指令為可可疑指令令；可疑疑指令將將被自動動

26、批復(fù)，商戶、客戶可可于第二二日查詢詢指令狀狀態(tài)。沒有收到到客戶瀏瀏覽器轉(zhuǎn)轉(zhuǎn)發(fā)的銀銀行通知知：由于客戶戶瀏覽器器端或互互聯(lián)網(wǎng)通通訊等原原因可能能造成商商戶端接接收不到到客戶瀏瀏覽器提提交的銀銀行通知知。當(dāng)沒沒有收到到銀行通通知時，可登錄錄工行商商戶服務(wù)務(wù)網(wǎng)站手手工查詢詢指令狀狀態(tài)或者者商戶調(diào)調(diào)用查詢詢接口自自動處理理。商戶提交交的訂單單信息和和銀行返返回的通通知消息息都是xxml串串，并且且進行了了BASSE644編碼；提交和返返回的xxml都都應(yīng)有xxml頭頭；安全APPI說明明為了保證證商戶提提交訂單單數(shù)據(jù)和和銀行通通知信息息數(shù)據(jù)的的完整性性，不可可抵賴性性，現(xiàn)提提供一套套用于信信息簽名名、驗簽簽和BAASE664編解解碼的函函數(shù)。商商戶開發(fā)發(fā)時使用用這套函函數(shù)和工工行頒發(fā)發(fā)的商戶戶證書進進行商戶戶訂單信信息簽名名；簽名名數(shù)據(jù)項項和順序序均固定定，具體體格式可可參見上上文的數(shù)據(jù)據(jù)定義；同時使使用這套套APII和銀行行公鑰可可以驗證證銀行通通知消息息的有效效性。安安全APPI的使使用方法法可參見見相關(guān)開發(fā)發(fā)語言的的說明和和demmo程