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

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

2、 HYPERLINK l _Toc173203227 2.1.11支付接接口表單單定義 PAGEREF _Toc173203227 h 5 HYPERLINK l _Toc173203228 2.1.22traanDaata數(shù)數(shù)據(jù)定義義 PAGEREF _Toc173203228 h 6 HYPERLINK l _Toc173203229 2.1.33traanDaata格格式定義義 PAGEREF _Toc173203229 h 7 HYPERLINK l _Toc173203230 2.1.44表單樣樣例 PAGEREF _Toc173203230 h 8 HYPERLINK l _Toc

3、173203231 2.2通通知接口口 PAGEREF _Toc173203231 h 9 HYPERLINK l _Tooc177320032332 2.22.1通知接接口表單單定義 PAGEREF _Toc173203232 h 9 HYPERLINK l _Toc173203233 2.2.22nottifyyDatta數(shù)據(jù)據(jù)定義 PAGEREF _Toc173203233 h 10 HYPERLINK l _Toc173203234 2.2.33nottifyyDatta格式式定義 PAGEREF _Toc173203234 h 11 HYPERLINK l _TToc11732203

4、2235 2.22.4表單樣樣例 PAGEREF _Toc173203235 h 11 HYPERLINK l _Toc173203236 2.3說說明 PAGEREF _Toc173203236 h 12 HYPERLINK l _Toc173203237 第 3 章章安全APPI說明明 PAGEREF _Toc173203237 h 13 HYPERLINK l _Toc173203238 第 4 章章開發(fā)步步驟 PAGEREF _Toc173203238 h 13業(yè)務(wù)說明B2C在線線支付接接口實現(xiàn)現(xiàn)工行個人人網(wǎng)銀客客戶在工工行B22C商戶戶網(wǎng)站進(jìn)進(jìn)行消費費支付的的業(yè)務(wù)處處理。新的1.0.

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

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

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

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

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

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

11、aluue形式式；FORM表表單數(shù)據(jù)據(jù)如下：變量名稱變量命名長度定義說明接口名稱interrfacceNaameMAX(330)必輸，取值：“IICBCC_PEERBAANK_B2CC”接口版本號號interrfacceVeersiionMAX(115)必輸，取值：“”交易數(shù)據(jù)tranDDataa無限制必輸，簽名名；整合所有交交易數(shù)據(jù)據(jù)形成的的xmll明文串，并做做BASSE644編碼；具體格式定定義見下下文；注意：需有xmll頭屬性性；整個個字段使使用BAASE664編碼碼；xml明文文中沒有有回車換換行和多余空空格；訂單簽名數(shù)數(shù)據(jù)merSiignMMsg無限制必輸，商戶使用

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

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

14、的控制制。5、traanDaata交交易數(shù)據(jù)據(jù)的xmml串需需要有xxml的的頭，即即tranDDataa數(shù)據(jù)定定義變量名稱變量命名長度定義說明接口名稱interrfacceNaame16必輸，取值：“IICBCC_PEERBAANK_B2CC”接口版本號號interrfacceVeersiionMAX(115)必輸，取值：“”交易日期時時間orderrDatte=14必輸，格式為：YYYYYYMMDDDHHHmmsss要求在銀行行系統(tǒng)當(dāng)當(dāng)前時間間的前11小時和和后122小時范范圍內(nèi)，否否則判定定交易時時間非法法。訂單號orderridMAX(330)必輸，客戶支付后后商戶網(wǎng)網(wǎng)

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

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

17、oodssIDMAX(330)選輸商品名稱goodssNammeMAX(660)選輸商品數(shù)量goodssNummMAX(110)選輸已含運費金金額carriiageeAmttMAX(110)選輸商城提示merHiintMAX(1120)選輸備注字段11remarrk1MAX(1100)選輸 單位位：字節(jié)節(jié)備注字段22remarrk2MAX(1100)選輸 單位位：字節(jié)節(jié)返回商戶UURLmerURRLMAX(110244)必輸必須合法的的URLL，交易易結(jié)束，將將客戶引引導(dǎo)到商商戶的此此urll，即通通過客戶戶瀏覽器器posst交易易結(jié)果信信息到商商戶的此此URLL返回商戶變變量merVAARM

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

19、4-2113400625548220000102000ECC200000887502200002044090015002911300ZHH_CNN0001威威尼熊2200請請保留包包裝htttp:/loocallhosst:990811/Neewb22c_PPay_Merr.jssptesst通知接口通知接口表表單定義義變量名稱變量命名長度定義說明返回商戶變變量merVAAR無限制取值：商戶戶提交接接口中mmerVVAR字字段當(dāng)返返回銀行行結(jié)果時時，作為為一個隱隱藏域變變量，商商戶可以以用此變變量維護(hù)護(hù)sesssioon等等等。由客客戶端瀏瀏覽器支支付完成成后提交交通知結(jié)結(jié)果時是是明文傳傳輸，

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

21、明文文進(jìn)行簽簽名，不不是其BBASEE64編編碼后的的串；簽簽名后得得到二進(jìn)進(jìn)制數(shù)據(jù)據(jù)，對此此數(shù)據(jù)進(jìn)進(jìn)行BAASE664編碼碼得到ssignnMsggnotiffyDaata數(shù)數(shù)據(jù)定義義變量名稱變量命名長度定義說明接口名稱interrfacceNaame16取值：“IICBCC_PEERBAANK_B2CC”接口版本號號interrfacceVeersiionMAX(115)取值：“”交易日期時時間orderrDatte=14格式為：YYYYYYMMDDDHHHmmsss要求在銀行行系統(tǒng)當(dāng)當(dāng)前時間間的前11小時和和后122小時范范圍內(nèi)，否否則判定定交易時時間非法法。訂單號ord

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

23、ctMAX(119)商戶收費入入賬賬號號 （只只能交易易時指定定）。檢驗聯(lián)名標(biāo)標(biāo)志veriffyJooinFFlagg=1取值“1”：客戶戶支付時時，網(wǎng)銀銀判斷該該客戶是是否與商商戶聯(lián)名名，是則則按上送送金額扣扣帳，否否則展現(xiàn)現(xiàn)未聯(lián)名名錯誤；取值“0”：不檢檢驗客戶戶是否與與商戶聯(lián)聯(lián)名，按按上送金金額扣帳帳?？蛻袈?lián)名標(biāo)標(biāo)志JoinFFlagg=1客戶在銀行行端是否否與商城城聯(lián)名標(biāo)標(biāo)志位。11客戶聯(lián)聯(lián)名 00客戶未未聯(lián)名聯(lián)名會員號號UserNNumMAX(440)聯(lián)名客戶在在商戶的的會員號號。銀行指令序序號TranSSeriialNNoMAX(330)銀行端指令令流水號號返回通知日日期時間間no

24、tiffyDaateMAX(114)格式為：YYYYYYMMDDDHHHmmsss訂單處理狀狀態(tài)tranSStatt=11-“交易易成功，已已清算”；2-“交易易失敗”；3-“交易易可疑”錯誤描述commeentMAX(1100)錯誤描述notiffyDaata格格式定義義notiffyDaata格格式(xxml格格式固定定，選輸輸字段的的取值可可以為空空，標(biāo)簽簽需保留留)表單樣例表單數(shù)據(jù)：notiffyDaata對對應(yīng)的明明文：ICBBC_PPERBBANKK_B22C322007707225100501142000700725510550144-21134006255482

25、20000102000ECC2000008875022000020440900150029113002000707725111044001交易易成功！說明商戶可能收收到的銀銀行通知知指令成功：只能有一筆筆成功、且且要驗證證銀行簽簽名、訂訂單金額額等信息息是否與與商戶端端記錄一一致。指令失?。鹤⒁饪赡苁帐盏蕉喙P筆失敗。客客戶支付付失敗時時可以重重提此筆筆訂單到到銀行支支付。指令可疑：由于網(wǎng)銀系系統(tǒng)與后后臺業(yè)務(wù)務(wù)處理系系統(tǒng)間通通訊異常常，造成成網(wǎng)銀不不能確認(rèn)認(rèn)支付指指令結(jié)果果，則此此筆指令令為可疑疑指令；可疑指指令將被被自動批批復(fù)，商商戶、客客戶可于于第二日日查詢指指令狀態(tài)態(tài)。沒有收到客客戶瀏覽覽

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