中國工商銀行網上銀行B2C線上支付介面說明
一、B2C流程說明：
1、客戶在商戶網站瀏覽商品資訊，簽訂訂單；
2、商戶按照工行B2C訂單資料規範形成提交資料，並使用工行提供API和商戶證書對訂單資料簽名，形成form表單返回客戶瀏覽器，表單action地址指向工行接收商戶B2C訂單資訊的servlet；
3、客戶確認使用工行支付後，提交此表單到工行；
4、工行網銀系統接收此筆B2C訂單，對訂單資訊和商戶資訊進行檢查，通過檢查則顯示工行B2C支付頁面；
5、客戶在此頁面可以查詢客戶在銀行的預留資訊；也可以輸入支付卡號、支付密碼、驗證碼進行B2C支付；
6、工行檢查客戶資訊，通過檢查後顯示確認頁面；客戶確認提交後工行進行支付指令處理；
7、工行進行支付指令處理後，如果商戶需要工行實時通知，則工行將處理結果使用
8、工行進行支付指令處理後，如果商戶不需要工行實時通知，則工行直接顯示交易結果給客戶。
二、B2C介面資料說明：
介面資料格式定義通過介面名稱和介面版本號來標識，以便將來的擴充套件；以下資料格式為“
2.1 B2C商戶提交表單介面定義：
|
變數名稱 |
變數命名 |
長度定義 |
說明 |
|
介面名稱 |
interfaceName |
MAX(30) |
必輸，簽名， 取值：“ICBC_PERBANK_B2C” |
|
介面版本號 |
interfaceVersion |
MAX(15) |
必輸，簽名， 取值：“1.0.0.0” |
|
訂單號 |
orderid |
MAX(30) |
必輸，簽名， 客戶支付後商戶網站產生的一個唯一的定單號，該訂單號應該在相當長的時間內不重複。工行通過訂單號加訂單日期來唯一確認一筆訂單的重複性。 |
|
訂單金額 |
amount |
MAX(10) |
必輸，簽名， 客戶支付訂單的總金額，一筆訂單一個，以分為單位。不可以為零，必需符合金額標準。 |
|
支付幣種 |
curType |
=3 |
必輸，簽名， 用來區分一筆支付的幣種，目前工行只支援使用人民幣（001）支付。 取值：“001” |
|
商戶程式碼 |
merID |
MAX(20) |
必輸，簽名， 唯一確定一個商戶的程式碼，由商戶在工行開戶時，由工行告知商戶。 |
|
商城賬號 |
merAcct |
MAX(19) |
必輸，簽名， 商城收費入賬賬號（只能交易時指定）。 |
|
檢驗聯名標誌 |
verifyJoinFlag |
=1 |
必輸，簽名。 取值“1”：客戶支付時，網銀判斷該客戶是否與商戶聯名，是則按上送金額扣帳，否則展現未聯名錯誤； 取值“0”：不檢驗客戶是否與商戶聯名，按上送金額扣帳。 |
|
通知型別 |
notifyType |
=2 |
必輸，簽名， 在交易轉賬處理完成後把交易結果通知商戶的處理模式。 取值“HS”：在交易完成後實時將通知資訊以HTTP協議POST方式，主動傳送給商戶，傳送地址為商戶端隨訂單資料提交的接收工行支付結果的URL即表單中的merURL欄位； 取值“AG”：在交易完成後不通知商戶。商戶需使用瀏覽器登入工行的B2C商戶服務網站，或者使用工行提供的客戶端程式API主動獲取通知資訊。 |
|
接收支付結果資訊通知程式地址 |
merURL |
MAX (200) |
選輸，簽名， 使用HS通知型別的商戶用來接收工行訂單支付結果的URL；銀行使用HTTP協議POST方式向此地址傳送通知資訊；目前只支援80埠。 使用“AG”通知型別的商戶,該欄位可以為空或者不上送該欄位；但在簽名資料中必須包含此項，取值可為空。 取值舉例：http://www.mer.com/getICBCPayResult.jsp |
|
結果傳送型別 |
resultType |
=1 |
選輸，簽名。 取值“0”：無論支付成功或者失敗，銀行都向商戶傳送交易通知資訊； 取值“1”，銀行只向商戶傳送交易成功的通知資訊。 只有通知方式為HS時此值有效，如果使用AG方式，可不上送此項，但簽名資料中必須包含此項，取值可為空。 |
|
商品編號 |
goodsID |
MAX(30) |
選輸 |
|
商品名稱 |
goodsName |
MAX(60) |
選輸 |
|
商品數量 |
goodsNum |
MAX(10) |
選輸 |
|
已含運費金額 |
carriageAmt |
MAX(10) |
選輸 |
|
商城提示 |
merHint |
MAX(120) |
選輸 |
|
交易日期時間 |
orderDate |
=14 |
必輸，簽名， 格式為：YYYYMMDDHHmmss 要求在銀行系統當前時間的前1小時和後12小時範圍內，否則判定交易時間非法。 |
|
訂單簽名資料 |
merSignMsg |
無限制 |
必輸， 商戶使用工行提供的簽名API介面和商戶證書將交易資料按一定格式進行簽名，然後進行BASE64編碼後得到的字串。（格式單獨說明） |
|
商城證書公鑰 |
merCert |
無限制 |
必輸， 商戶用二進位制方式讀取證書公鑰檔案後，進行BASE64編碼後產生的字串。 |
|
備註欄位1 |
remark1 |
MAX(100) |
選輸 |
|
備註欄位2 |
remark2 |
MAX(100) |
選輸 |
注：
1、資料中不能包含“|”“&”“=”，此字元為銀行端程式保留字元；中文變數使用GBK編碼，另請注意與C2C介面定義欄位名稱和大小寫有區分
2、從商戶Post過來的資料，引數名的名稱必須與上表中完全相同，名稱中的字母大小寫均要相同，不能進行隨意更改(在form中的提交按鈕<input type=”submit”……>中submit不能有Name屬性)；此外，如果其他input 項的Name中使用了雙引號，如：<input type=text name="merURL "value="http://www.merchant.com/ICBCPay/">，則一定注意在引號內不要包含空格，不要寫成“mer URL”，如果拼寫錯誤或者多了空格，將造成資料無法識別，無法正常進行支付
3、介面名稱和版本號一定要和上表中相同.。
4、商戶提交資料中的空格將被認為是有效字元被接收，請商戶開發時注意對多餘空格的控制。
2.2 商戶提交表單簽名merSignMsg格式：
1、組織要簽名的資料串(順序固定；被商戶簽名的串為各輸入項的值)：
介面名稱的值+介面版本號的值+商城程式碼的值+商城賬號的值+通知地址的值+結果傳送型別的值+訂單號的值+訂單金額的值+支付幣種的值+通知型別的值+交易日期時間的值+校驗聯名標誌的值
2、舉例：
以下是需要簽名的資料名稱及對應值
interfaceName=ICBC_PERBANK_B2C&interfaceVersion=1.0.0.0&merID=0200EC20000012&merAcct=0200029109000030106&merURL=http://www.geticbcmsg.com.cn/servlet¬ifyType=HS&orderid=000000001&amount=100&curType=001&resultType=0&orderDate=20050801192556&verifyJoinFlag=0
需要簽名的明文
ICBC_PERBANK_B2C1.0.0.00200EC200000120200029109000030106http://www.geticbcmsg.com.cn/servletHS0000000011000010200508011925560
簽名後（用測試私鑰user.key ）
merSignMsg為
SFVdS3Kca6d/wetLFwynBl1q5nDIyxxEUXCzniIa47mhxs1BM9mPsnRc2lOqqrfwBdwBjSE82jS/iBHYKolf2sppjEyOImVZycv96321QPDgPA1yleO83K1XA1rmB3zxsIuwLKIICSWwdttn1XPYOQLJ/WAtZ5DFYFog7J8pXw0=
merCert為（用測試證書user.crt）
MIICVjCCAb+gAwIBAgIKI9fKEDP6AAAO3DANBgkqhkiG9w0BAQUFADA0MRgwFgYDVQQDEw9wYmouaWNiYy5jb20uY24xGDAWBgNVBAoTD3Biai5pY2JjLmNvbS5jbjAeFw0yMDA5MjAwOTI3NDFaFw0yMTA5MjAwOTI3NDFaMEMxGDAWBgNVBAMTD2JpYW5sdTIyLmUuMDIwMDENMAsGA1UECxMEMDIwMDEYMBYGA1UEChMPcGJqLmljYmMuY29tLmNuMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDG+u/C5pad0ZbwvAk9Gv1rr+SpknfFUsTMhJLcI2KiYa+XLSf5vCib0OclOoDDXKIWPt/hkMEz+ED8YukQpsstXHvnxVFxVtPh23dubQjB8/kJ7X5EbwngsHMLFEXqr3UvNfcGZHuAFqMRPtr8ys3YnL3UG43Xienc3cD8jXFdQQIDAQABo2AwXjBLBgNVHR8ERDBCMECgPqA8pDowODEOMAwGA1UEAxMFY3JsMTMxDDAKBgNVBAsTA2NybDEYMBYGA1UEChMPcGJqLmljYmMuY29tLmNuMA8GA1UdYwQIAwYA/wAAAAAwDQYJKoZIhvcNAQEFBQADgYEAQe6tLhKaNX8OPNT2XzH7dTXIFmTm37hSvmbEL/Q/pWV386KVrNSCnyN3fowanMt5TE9qZFn9enVvyDJw4nAUx38F2PFn2Tt7JUtzt/pNKC5FiebpFJH48AXIP1Xt5GjdcBx0oXM9QNBtYvY0189t357EH4UaBfO+c+L8fkOt37o=
2.3 B2C通知商戶交易結果介面定義：
|
變數名稱 |
變數命名 |
長度定義 |
說明 |
|
介面名稱 |
interfaceName |
MAX(30) |
取值：“ICBC_PERBANK_B2C” |
|
介面版本號 |
interfaceVersion |
MAX(15) |
取值：“1.0.0.0” |
|
訂單號 |
orderid |
MAX(30) |
客戶支付後商戶網站產生的一個唯一的定單號，該訂單號應該在相當長的時間內不重複。工行通過訂單號加訂單日期來唯一確認一筆訂單的重複性。 |
|
銀行指令序號 |
TranSerialNo |
MAX(30) |
銀行端指令流水號 |
|
訂單金額 |
amount |
MAX(10) |
客戶支付訂單的總金額，一筆訂單一個，以分為單位。不可以為零，必需符合金額標準。 |
|
支付幣種 |
curType |
=3 |
用來區分一筆支付的幣種，目前工行只支援使用人民幣（001）支付。 取值：“001” |
|
商戶程式碼 |
merID |
MAX(20) |
唯一確定一個商戶的程式碼，由商戶在工行開戶時，由工行告知商戶。 |
|
商城賬號 |
merAcct |
MAX(19) |
商城收費入賬賬號（只能交易時指定）。 |
|
檢驗聯名標誌 |
verifyJoinFlag |
=1 |
取值“1”：客戶支付時，網銀判斷該客戶是否與商戶聯名，是則按上送金額扣帳，否則展現未聯名錯誤； 取值“0”：不檢驗客戶是否與商戶聯名，按上送金額扣帳。 |
|
客戶聯名標誌 |
JoinFlag |
=1 |
客戶在銀行端是否與商城聯名標誌位。1客戶聯名 0客戶未聯名 |
|
聯名會員號 |
UserNum |
MAX(40) |
聯名客戶在商戶的會員號。 |
|
結果傳送型別 |
resultType |
=1 |
取值“0”：無論支付成功或者失敗，銀行都向商戶傳送交易通知資訊； 取值“1”，銀行只向商戶傳送交易成功的通知資訊。 |
|
交易日期時間 |
orderDate |
=14 |
格式為：YYYYMMDDHHmmss 要求在銀行系統當前時間的前1小時和後12小時範圍內，否則判定交易時間非法。 |
|
返回通知日期時間 |
notifyDate |
MAX(14) |
格式為：YYYYMMDDHHmmss |
|
訂單處理狀態 |
tranStat |
=1 |
1-“交易成功，已清算”； 2-“交易失敗”； 3-“交易可疑” |
|
錯誤描述 |
comment |
MAX(100) |
錯誤描述 |
|
備註1 |
remark1 |
MAX(100) |
備註 |
|
備註2 |
remark2 |
MAX(100) |
備註 |
|
通知訊息銀行簽名資料 |
signMsg |
無限制 |
銀行使用自己證書對商戶通知訊息按照一定格式進行的簽名,然後進行BASE64編碼後的字串。（格式單獨描述） |
（注意與C2C通知介面定義變數名區分）
2.4 通知訊息銀行簽名資料signMsg格式：
1、組織要簽名的資料串(順序固定；銀行通知訊息簽名的串為以下格式，請注意與商戶簽名串的格式不同)：
介面名稱=值&介面版本號=值&訂單號=值&指令序號=值&訂單金額=值&支付幣種=值&商城程式碼=值&商城賬號=值&校驗聯名標誌=值&客戶聯名標誌=值&聯名會員號=值&結果傳送型別=值&交易日期時間=值&返回通知日期時間=值&訂單處理狀態=值&錯誤描述=值&備註1=值&備註2=值
interfaceName=值&interfaceVersion=值&orderid=值&TranSerialNo=值&amount=值&curType=值&merID=值&merAcct=值&verifyJoinFlag=值&JoinFlag=值&UserNum=值&resultType=值&orderDate=值¬ifyDate=值&tranStat=值&comment=值&remark1=值
&remark2=值
舉例：
以下是需要驗籤的資料串明文
interfaceName=ICBC_PERBANK_B2C&interfaceVersion=1.0.0.0&orderid=000000001&TranSerialNo=&amount=100&curType=001&merID=0200EC20000012&merAcct=0200029109000030106&verifyJoinFlag=0&JoinFlag=&UserNum=&resultType=0&orderDate=20050801192556¬ifyDate=20050824165910&tranStat=2&comment=failure,Error_code:32147ErrorMsg:提交支付表單時間資料不在有效時間範圍。&remark1=&remark2=
簽名後signMsg為
Yp4CVHY5rHtcQ9kOxHc70k1PKgpv1jXk0LZgSH0O+iEcFA3KKxBRjAhvCvV0hDc9X0WXswMfcGuaKMoCJSMHmdq3lVTYr2hfT1/K3nPI6IdCGmo4wJWha8ha4ujyLkQFa36f+7C1g9keBro59GPIBHHaRs1Ggmnb2aNimdMAAiM=
2.5 商戶可能收到的銀行通知：
指令成功：
只能有一筆成功、且要驗證銀行簽名、訂單金額等資訊是否與商戶端記錄一致。
指令失敗：
注意可能收到多筆失敗。客戶支付失敗時可以重提此筆訂單到銀行支付。
指令可疑：
由於網銀系統與後臺業務處理系統間通訊異常，造成網銀不能確認支付指令結果，則此筆指令為可疑指令；可疑指令將被自動批覆，商戶、客戶可於第二日查詢指令狀態。
沒有收到銀行通知：
由於銀行、商戶兩端伺服器或者網際網路通訊等原因可能造成商戶端接收不到銀行通知。當沒有收到銀行通知時，可登入工行商戶服務網站手工查詢指令狀態或者商戶呼叫查詢介面自動處理。
2.6商戶返回取貨地址：
取貨地址（也可稱為商戶收到銀行成功支付後的商戶端確認地址）：
如果有取貨地址則及時返回取貨地址，沒有取貨地址需及時關閉連線；因為銀行端先進行訂單支付清算，然後給商戶傳送通知，在商戶返回取貨地址或者關閉連線後，才顯示交易結果給客戶，整個過程是序列的；如果商戶在收到銀行通知後，不及時返回或關閉連線，將可能造成客戶端等待超時，無法顯示最終的交易結果頁面。
三、安全API說明：
為了保證商戶提交訂單資料和銀行通知資訊資料的完整性，不可抵賴性，現提供一套用於資訊簽名、驗籤和BASE64編解碼的函式。商戶開發時使用這套函式和工行頒發的商戶證書進行商戶訂單資訊簽名；簽名資料項和順序均固定，具體格式可參見上一節的資料定義；同時使用這套API和銀行公鑰可以驗證銀行通知訊息的有效性。
安全API的使用方法可參見【開發API介面】目錄中不同開發語言的說明和demo程式；
四、開發步驟
商戶程式需在銀行模擬測試環境上進行聯調後，再投產，以下說