招行面向互聯(lián)網(wǎng)商戶接口開發(fā)指南-有密支付

1、 內(nèi)部資料 注意保密招行面向互聯(lián)網(wǎng)商戶接口開發(fā)指南修訂歷史修訂描述版本日期作者審核新建1.0徐文暉這次更新內(nèi)容： 1、iOS密碼鍵盤部分內(nèi)容更新； 2、增加了商戶開發(fā)包使用的常見問題解答文檔； 3、更新了手機端簽約的接口內(nèi)容；4、基于開發(fā)同事前期的批注修改內(nèi)容補充。1.1項目開發(fā)組1、iOS密碼鍵盤部分修改了商戶調(diào)用密碼鍵盤的方式。1.2項目開發(fā)組1、在六、API列表的簽約功能里，增加了前端交互處理部分內(nèi)容。簽約成功界面“返回商戶”按鈕和頁面頭部導(dǎo)航技術(shù)方案約定，以前的文檔由于還沒有制定方案，所以缺失。 2、在六、API列表的簽約功能里，增加了注意事項部分內(nèi)容。讓商戶對秘鑰、地址之類通過配置管

2、理，防止將來變動，不用發(fā)布程序。1.3項目開發(fā)組1、增加招行面向互聯(lián)網(wǎng)商戶接口開發(fā)指南文檔目錄。2、支付接口功能的參數(shù)部分修改成以表格形式展現(xiàn)。3、涉及到具體接口參見“XX列表”里的“XX功能”，修改成鏈接的方式，點擊后可以直接跳轉(zhuǎn)。1.4項目開發(fā)組6.2 SDK集成指引有所調(diào)整1.5朱楠輝、李海濤6.2.2 增加測試商戶地址1.6張樟、李海濤補充6.1簽約功能-前端交互處理1.7胡明艷、李海濤修改4.2參數(shù)定義和六、2.2商戶支付命令中的： 返回商戶url（MerchantRetUrl）1.8張樟、李海濤增加“六、2.3節(jié)，頁頭導(dǎo)航及返回”章節(jié)，介紹“返回機制”1.9張樟、李海濤六 API列

3、表：1 簽約功能，增加測試環(huán)境短信驗證碼獲取1.10張樟、李海濤六API列表：6密碼鍵盤SDK功能 Ios版說明一、使用方法 中的第2點，包含的頭文件改了        #import <cmbkeyboard/CMBWebViewController.h> 改成：  #import <cmbkeyboard/CMBWebKeyboard.h>   #import<cmbkeyboard/NSString+Additions.h>

4、       二、使用方法 中的第3點，在后面加了一句： 若圖片沒有加載，則顯示的密碼鍵盤頁面是透明的           三、使用方法 中的第4點 的第一行，加了一句：  需重寫webView方法，          四、公鑰配置說明中，在<key>CMBPublicKey</key>后增加了一行：  <s

5、tring>公鑰內(nèi)容</string>     指明公鑰是以string的形式。 1.112016.4.26林雪燕、李海濤目 錄招行面向互聯(lián)網(wǎng)商戶接口開發(fā)指南1一、指南說明51.閱讀對象52.版本說明5二、術(shù)語51.支付模式52.名詞解釋5三、一網(wǎng)通支付申請流程61.開戶流程62.一網(wǎng)通支付業(yè)務(wù)開戶所需資料6四、接口規(guī)則61.協(xié)議規(guī)則72.參數(shù)規(guī)定73.安全規(guī)范9五、一網(wǎng)通支付（主動）91.場景介紹92.業(yè)務(wù)流程及開發(fā)步驟支付步驟15六、API列表161.簽約功能162.主動支付接口功能213.簽約結(jié)果回調(diào)功能284.解約功能285.主

6、動支付退款功能296.密碼鍵盤SDK功能337.程序定單管理功能37七、聯(lián)系人員40一、 指南說明1. 閱讀對象本文適用于互聯(lián)網(wǎng)商戶系統(tǒng)(如交通出行平臺、在線購物平臺、自動化智能收銀系統(tǒng)或其他)集成招商銀行一網(wǎng)通支付涉及的技術(shù)架構(gòu)師，研發(fā)工程師，測試工程師，系統(tǒng)運維工程師。2. 版本說明1. 2016.1.19新增此接口開發(fā)指南。二、 術(shù)語1. 支付模式商戶APP在應(yīng)用內(nèi)調(diào)用招行H5頁面完成一網(wǎng)通支付。2. 名詞解釋一網(wǎng)通支付：是招行銀行全新推出的移動端無卡支付工具，支持用戶在商戶的移動客戶端內(nèi)進行多銀行卡支付（12家銀行儲蓄卡，10家銀行信用卡），流程便捷，實時到賬。密碼鍵盤SDK：招行自主

7、開發(fā)的基于Android和iOS平臺的安全輸入鍵盤，集成在商戶APP中，配合招行一網(wǎng)通支付使用，保護用戶的密碼安全。三、 一網(wǎng)通支付申請流程1. 開戶流程1、電子支付特約商戶結(jié)算賬戶開戶支行或分行零售銀行部負(fù)責(zé)商戶的資料收集、受理、驗證并向分行零售銀行部提交商戶接入申請，分行零售銀行部隊電子支付特約商戶進行市場調(diào)查，并驗證相關(guān)證件，由分行零售銀行部初步評估后，協(xié)助商戶填報電子渠道特約商戶開戶審批表、招商銀行一網(wǎng)通支付業(yè)務(wù)合作協(xié)議書（見附件），報分行零售銀行部審批；2、分行零售銀行部按照一網(wǎng)通支付商戶建設(shè)流程進行商戶開戶申請；3、需要提供8位的企業(yè)網(wǎng)銀編號；4、按照總行相關(guān)流程申請中間業(yè)務(wù)平臺商

8、戶號、開通協(xié)議支付、明確是否需要支持退款。2. 一網(wǎng)通支付業(yè)務(wù)開戶所需資料營業(yè)執(zhí)照副本或組織機構(gòu)代碼證副本、法定代表人或負(fù)責(zé)人身份證件、經(jīng)辦人身份證件及企業(yè)授權(quán)書、互聯(lián)網(wǎng)信息服務(wù)業(yè)務(wù)經(jīng)營許可證（ICP證）（國家不要求具備ICP證的商戶不需提供），以上資料分行應(yīng)留存復(fù)印件。四、 接口規(guī)則用戶通過手機瀏覽器瀏覽商戶商城生成定單支付頁面，支付頁面應(yīng)包括：定單內(nèi)容和招商銀行一網(wǎng)通支付按鈕。招商銀行一網(wǎng)通支付按鈕通過支付命令鏈接到支付網(wǎng)關(guān)。商戶需要自行對客戶協(xié)議開通狀況、協(xié)議號等信息進行管理)。在客戶協(xié)議未開通的情況下，需要填寫開通協(xié)議相關(guān)的信息，以保證銀行頁面能正確引導(dǎo)客戶進行協(xié)議開通并完成支付。1.

9、 協(xié)議規(guī)則傳輸方式傳輸安全控制手段采用的是安全套接層SSL。提交方式支付系統(tǒng)支持GET方式和POST方式提交支付命令，建議使用POST方式2. 參數(shù)規(guī)定參數(shù)名稱參數(shù)說明支付商戶開戶分行號請咨詢開戶的招商銀行分支機構(gòu)支付商戶號6位長數(shù)字，由銀行在商戶開戶時確定定單號6位或10位長數(shù)字，由商戶系統(tǒng)生成，一天內(nèi)不能重復(fù)定單總金額格式為：xxxx.xx元交易日期格式：YYYYMMDD與實際時間只能有一個小時誤差。商戶交易日期。日期不能跨天。如果交易日期為前一天，則要求截至?xí)r間為凌晨1點鐘。如果交易日期為后一天，當(dāng)前時間必須為23點以后定單過期時間跨度必須為大于零的整數(shù)，單位為分鐘。該請求參數(shù)為可選參數(shù)

10、，如果請求中不包含該參數(shù)，則默認(rèn)為會話有效時間（目前是30分鐘）(如果客戶在商戶端對同一筆訂單重新發(fā)起支付請求，則以商戶在后一次發(fā)起時指定的參數(shù)為準(zhǔn)。)該參數(shù)指定當(dāng)前支付請求必須在指定時間跨度內(nèi)完成，否則按過期處理。該參數(shù)適用于航空客票等對交易完成時間敏感的支付請求；支付結(jié)果通知命令Url支付結(jié)果通知命令中參數(shù)之前的部分，長度不能超過128個字節(jié)。例如： 注意：MerchantUrl自身不能帶商戶參數(shù)支付結(jié)果通知命令參數(shù)商戶需要銀行在支付結(jié)果通知中轉(zhuǎn)發(fā)的商戶參數(shù)；注意：MerchantPara參數(shù)可為空，商戶如果需要不止一個參數(shù)，可以自行把參數(shù)組合、拼裝，但組合后的結(jié)果不能帶有&字符，

11、總長不能超過128個字節(jié)。例如：MerchantPara=Ref1=12345678|Ref2=ABCDEFG|Ref3=HIJKLM商戶校驗碼每個商戶有一個“商戶密鑰”，可以自行在商戶結(jié)帳系統(tǒng)的維護。商戶校驗碼，就是使用這個商戶密鑰，對訂單的內(nèi)容做運算后得到的。訂單內(nèi)容不同，其校驗碼也不同。由于只有商戶和銀行知道“商戶密鑰”，第三方無法產(chǎn)生校驗碼。因而銀行可以通過校驗碼檢驗訂單內(nèi)容是否為商戶產(chǎn)生。詳見“商戶校驗碼.doc”說明返回商戶url支付完成后5秒后頁面將自動跳轉(zhuǎn)到MerchantRetUrl與MerchantRetPara所指定的地址。例如：MerchantRetUrl = Merc

12、hantRetPara = Para1=abc|Para2=123則，點擊“返回按鈕”，客戶瀏覽器將跳轉(zhuǎn)到： 注意：MerchantRetPara參數(shù)可為空，商戶如果需要不止一個參數(shù)，可以自行把參數(shù)組合、拼裝，但組合后的結(jié)果不能帶有&字符，總長不能超過128個字節(jié)返回商戶參數(shù)詳見上文的返回商戶url中的說明客戶協(xié)議號字符串，不超過30位。未簽約客戶，填寫新增的協(xié)議號，用于協(xié)議開通；簽約客戶，填寫客戶協(xié)議號。非空?？蛻魠f(xié)議號是商戶自己生成的，純數(shù)字0,9即可，無其他特殊要求交易時間戳交易日期+時間，格式為YYYYMMDDHHMMSS。非空協(xié)議商戶企業(yè)編號由銀行在商戶開戶時確定。非空, 8

13、位。協(xié)議開通請求流水號字符串，不超過20位。協(xié)議開通時非空協(xié)議用戶ID字符串，不超過20位協(xié)議手機號11位數(shù)字協(xié)議開通結(jié)果通知URL協(xié)議開通結(jié)果通知命令中參數(shù)之前的部分。參數(shù)規(guī)則同支付結(jié)果通知命令。字符串，長度不超過100位。協(xié)議開通時非空協(xié)議開通結(jié)果通知參數(shù)商戶需要銀行在協(xié)議開通結(jié)果通知中轉(zhuǎn)發(fā)的商戶參數(shù)，參數(shù)規(guī)則同支付結(jié)果通知命令。字符串，長度不超過128位地理位置格式為“經(jīng)度|緯度”，經(jīng)緯度兩個參數(shù)之間用豎線分開。例如：18.23445|46.000033。可以為空客戶風(fēng)險等級保留字段。填寫商戶端客戶的風(fēng)險等級，可以為空3. 安全規(guī)范支付接口安全規(guī)范見商戶校驗碼.doc。五、 一網(wǎng)通支付（

14、主動）1. 場景介紹商戶已有客戶端，用戶在商戶APP內(nèi)發(fā)起購買操作時，可以調(diào)用一網(wǎng)通支付完成下單付款的流程。l 首次支付：需一次性完成 簽約+支付兩個流程。步驟（1）：用戶完成選購，商戶在收銀臺向用戶提供“銀行卡支付”選項。步驟（2）：用戶選擇“銀行卡支付”，調(diào)起招行接口，跳轉(zhuǎn)至銀行卡號輸入頁面。步驟（3）：用戶輸入銀行卡后，點擊下一步，繼續(xù)填寫姓名、證件號、手機號等信息。步驟（4）：驗證用戶填寫的信息，并向用戶提供的手機號發(fā)送短信驗證碼進行驗證。步驟（5）：如果用戶已經(jīng)是招商銀行一網(wǎng)通用戶，則引導(dǎo)用戶輸入支付密碼進行驗證。如果用戶尚未開通招商銀行一網(wǎng)通用戶，則為用戶開通并引導(dǎo)用戶設(shè)置支付密碼

15、。至此完成簽約，商戶后臺得到簽約成功的通知。步驟（6）：用戶輸入支付密碼，完成支付。商戶后臺得到支付成功的通知。 （以上圖片為示意）l 已簽約用戶再次支付：只需輸入支付密碼即可完成支付。步驟（1）：用戶完成選購，商戶在收銀臺向用戶提供“銀行卡支付”選項。步驟（2）：用戶輸入支付密碼，完成支付。商戶后臺得到支付成功的通知。 2. 業(yè)務(wù)流程及開發(fā)步驟支付步驟商戶APP在應(yīng)用內(nèi)調(diào)用招行H5頁面完成一網(wǎng)通支付，商戶系統(tǒng)和招行一網(wǎng)通支付系統(tǒng)主要交互說明：步驟1：用戶在商戶APP中選擇商品，提交訂單，選擇“銀行卡支付”后調(diào)用招行一網(wǎng)通支付請求接口，具體接口API功能參見“API列表”里的“支付接口功能”；

16、步驟2：在支付時候查詢用戶是否簽約，如果未簽約，自動跳轉(zhuǎn)簽約業(yè)務(wù)，后臺自動調(diào)用招行簽約接口；注： 商戶可以直接調(diào)用API功能參見“API列表”里的“簽約功能”；步驟3：如果用戶已簽約則繼續(xù)做支付，需調(diào)用招行一網(wǎng)通支付接口，具體接口API功能參見“API列表”里的“支付接口功能”；步驟4：支付成功通知參見“API列表”里的“支付接口功能”；其他說明：解約參見“API列表”里的“解約功能”； 退款參見“API列表”里的“退款功能”； 清算對賬、定單查詢及退款查詢功能參見“API列表”里的“程序定單管理功能”。六、 API列表1. 簽約功能本接口適用功能：1、單獨簽約（簽約+支付不適用）編號參數(shù)名稱

17、類型長度是否必填方向說明1REQSERIALString24必填商戶輸入商戶生成的交易流水號，同一交易日期唯一2CUSTARGNOString32必填商戶輸入客戶協(xié)議號，商戶生成3MERCHANTNOString8必填商戶輸入商戶號（招行分配）/企業(yè)網(wǎng)銀編號4MOBILEString11商戶輸入手機號5USERIDString30商戶輸入商戶用戶id（商戶用戶唯一標(biāo)識）6LONdecimal10商戶輸入經(jīng)度，手機定位數(shù)據(jù)7LATdecimal10商戶輸入緯度，手機定位數(shù)據(jù)8RISKLEVELint4商戶輸入風(fēng)險等級9TIMESTAMPString14必填商戶輸入商戶交易時間（yyyyMMddH

18、Hmmss）交易時間大于手機銀行系統(tǒng)時間10分鐘拒絕交易10NOTICEURLString100必填商戶輸入商戶接收簽約設(shè)置結(jié)果url11NOTICEPARAString128商戶輸入通知需要附帶的參數(shù): xxx|xxx|xxx12SIGNString必填輸入DES密文商戶請求表單：<form action=" 如下表" method="post" ><input type="hidden" name="REQSERIAL" value="" /> <input t

19、ype="hidden" name="CUSTARGNO" value="" /> <input type="hidden" name="MERCHANTNO" value="" /> <input type="hidden" name="MOBILE" value="" /> <input type="hidden" name="USERID&quo

20、t; value="" /> <input type="hidden" name="LON" value="" /> <input type="hidden" name="LAT" value="" /> <input type="hidden" name="RISKLEVEL" value="" /> <input type="hidde

21、n" name=" TIMESTAMP" value="" /><input type="hidden" name="NOTICEURL" value="" /><input type="hidden" name="NOTICEPARA" value="" /><input type="hidden" name="SIGN " value="

22、" /></form>表單提交地址（商戶需通過配置實現(xiàn)）：測試環(huán)境簽約9:801/mobilehtml/DebitCard/M_NetPay/OneNetRegister/NP_BindCard.aspx生產(chǎn)環(huán)境簽約密文SIGN生成邏輯：1、 按順序拼接參數(shù)：REQSERIAL=XXX&CUSTARGNO=XXX&MERCHANTNO=XXX&MOBILE=XXX&USERID=XXX&LON=XXX&LAT=XXX&RISKLEVEL=XXX&TIMESTAMP=X

23、XX&NOTICEURL=XXX&NOTICEPARA=XXX2、使用秘鑰及算法加密3、參數(shù)空也需要拼接，如：&LON=&LAT=&RISKLEVEL=&TIMESTAMP=XXX，不要填充null。前端交互處理1、 簽約成功后的“返回商戶”按鈕需要商戶APP處理按鈕跳轉(zhuǎn)鏈接，自行控制動作。招行html代碼：<script type="text/javascript">function NPReturnMerChant() window.location.href = "http:/CMBNPRM&quo

24、t; </script><button onclick="javascript:NPReturnMerChant();">返回商戶</button>例如下圖簽約成功的“返回商戶”按鈕：2、 頁頭導(dǎo)航及返回由商戶APP實現(xiàn)，招行簽約html頁面已使用了橋機制，用于給商戶app返回按鈕傳值，需要商戶自定義橋?qū)崿F(xiàn)，招行配置商戶定義的橋名，然后簽約和html頁面會給商戶APP提供一個回調(diào)方法【initCmbSignNetPay】-此方法也是商戶APP注冊過的回調(diào)方法，該回調(diào)方法里面塞了一個招行html頁面回傳的json狀態(tài)值：【0-未簽約,1-已

25、簽約】，商戶通過招行給的回調(diào)方法，商戶APP獲取到此回調(diào)方法里面的狀態(tài)值做相應(yīng)的操作，注意，該兩個狀態(tài)值并不能真實反映簽約數(shù)據(jù)層面的狀態(tài)，僅僅是ui層面上的判斷，請以通知接口為準(zhǔn)；由于不同的app的返回機制不一樣，該橋機制商戶不一定需要實現(xiàn)。附：A、招行簽約的html頁面使用的公共js方法，/商戶橋返回-begin var default_data = sign_status: "0" ; var connectMerchantJSBridge = function (callback) try if (window.<%=TAG_MerchantBridgeName

26、 %>) callback(<%=TAG_MerchantBridgeName %>); else document.addEventListener("<%=TAG_MerchantBridgeName %>Ready", function () callback(<%=TAG_MerchantBridgeName %>); , false); catch (ex) ; var cmbMerchantBridge = initCmbSignNetPay: function (signData) if (!signData) sig

27、nData = default_data; connectMerchantJSBridge(function (bridge) if (typeof bridge = "undefined") return; bridge.callHandler("initCmbSignNetPay", JSON.stringify(signData); ); ; window.cmbMerchantBridge = cmbMerchantBridge; /商戶橋返回-end招行頁面調(diào)用：var signData = sign_status: "0"

28、 ; $.MReady(function () /給商戶回調(diào)方法用于返回 try cmbMerchantBridge.initCmbSignNetPay(signData); catch (ex) );B、界面展示，請關(guān)注界面左上角按鈕：以下成功頁面會返回狀態(tài)位sign_status: "1"其他非成功頁返回sign_status: "0"DES加密算法開發(fā)秘鑰key：cmbsh29i，上生產(chǎn)時約定修改算法代碼參考：public static byte DESEncrypt(byte plain, byte key) DESCryptoServicePr

29、ovider des = new DESCryptoServiceProvider(); des.Mode = CipherMode.ECB; des.Padding = PaddingMode.PKCS7; return des.CreateEncryptor(key, key).TransformFinalBlock(plain, 0, plain.Length); public static byte DESDecrypt(byte encrypt, byte key) DESCryptoServiceProvider des = new DESCryptoServiceProvider

30、(); des.Mode = CipherMode.ECB; des.Padding = PaddingMode.PKCS7; return des.CreateDecryptor(key, key).TransformFinalBlock(encrypt, 0, encrypt.Length); 調(diào)用：byte byteKey = Encoding.ASCII.GetBytes(sKey); byte baCiphertext =DESEncrypt(Encoding.UTF8.GetBytes(sBodyContent), byteKey);string sCiphertext = Con

31、vert.ToBase64String(baCiphertext);注意事項1、秘鑰及表單提交地址，商戶需通過配置管理，方便后續(xù)調(diào)整。2. 測試環(huán)境簽約流程中需要輸入短信驗證碼，請到該網(wǎng)址查詢： 9:801/GetMsgVerifyCode/Default.aspx2. 主動支付接口功能系統(tǒng)會根據(jù)商戶送過來的客戶協(xié)議號（PNo）是否已經(jīng)存在協(xié)議，判斷是否需要引導(dǎo)客戶進行協(xié)議簽署。2.1 應(yīng)用場景商戶APP發(fā)起已簽約或未簽約客戶的支付請求。2.2 商戶支付命令生產(chǎn)環(huán)境商戶支付命令格式如下：測試聯(lián)調(diào)環(huán)境支付命令格式如下：9:8

32、01/netpayment/BaseHttp.dll?PrePayEUserP?BranchID=xxxx&CoNo=xxxxxx&BillNo=xxxxxx&Amount=xxxx.xx&Date=YYYYMMDD&ExpireTimeSpan=xx&MerchantUrl=xxxxxx&MerchantPara=xxxxxx&MerchantCode=xx&MerchantRetUrl=xxxxxx&MerchantRetPara=xxxxxx參數(shù)名稱可空參數(shù)說明BranchIDN支付商戶開戶分行號，4位，請咨

33、詢開戶的招商銀行分支機構(gòu)；CoNoN支付商戶號，6位長數(shù)字，由銀行在商戶開戶時確定；/收單商戶號BillNoN定單號，6位或10位長數(shù)字，由商戶系統(tǒng)生成，一天內(nèi)不能重復(fù)；AmountN定單總金額，格式為：xxxx.xx元；ExpireTimeSpanY必須為大于零的整數(shù)，單位為分鐘。該請求參數(shù)為可選參數(shù)，如果請求中不包含該參數(shù)，則默認(rèn)為會話有效時間（目前是30分鐘）(如果客戶在商戶端對同一筆訂單重新發(fā)起支付請求，則以商戶在后一次發(fā)起時指定的參數(shù)為準(zhǔn)。)該參數(shù)指定當(dāng)前支付請求必須在指定時間跨度內(nèi)完成，否則按過期處理。該參數(shù)適用于航空客票等對交易完成時間敏感的支付請求；MerchantUrlN支付

34、結(jié)果通知命令中參數(shù)之前的部分，長度不能超過128個字節(jié)。例如： 注意：MerchantUrl自身不能帶商戶參數(shù)。MerchantParaY商戶需要銀行在支付結(jié)果通知中轉(zhuǎn)發(fā)的商戶參數(shù)；注意：MerchantPara參數(shù)可為空，商戶如果需要不止一個參數(shù)，可以自行把參數(shù)組合、拼裝，但組合后的結(jié)果不能帶有&字符，總長不能超過128個字節(jié)。例如：MerchantPara=Ref1=12345678|Ref2=ABCDEFG|Ref3=HIJKLMMerchantCodeN詳見“商戶校驗碼.doc”說明。注意以下為協(xié)議相關(guān)的字段：PNo: 客戶協(xié)議號。字符串，不超過30位。未簽約客戶，填寫新增的協(xié)

35、議號，用于協(xié)議開通；簽約客戶，填寫客戶協(xié)議號。非空。TS：交易日期+時間，格式為YYYYMMDDHHMMSS。非空。MchNo: 協(xié)議商戶企業(yè)編號。由銀行在商戶開戶時確定。非空。以下字段開通協(xié)議時需填寫：Seq：協(xié)議開通請求流水號。字符串，不超過20位。協(xié)議開通時非空。MUID：協(xié)議用戶ID。字符串，不超過20位。Mobile：協(xié)議手機號。11位數(shù)字。URL:協(xié)議開通結(jié)果通知命令中參數(shù)之前的部分。參數(shù)規(guī)則同支付結(jié)果通知命令。字符串，長度不超過100位。協(xié)議開通時非空。Para：商戶需要銀行在協(xié)議開通結(jié)果通知中轉(zhuǎn)發(fā)的商戶參數(shù)，參數(shù)規(guī)則同支付結(jié)果通知命令。字符串，長度不超過128位。LBS:地理位

36、置。格式為“經(jīng)度|緯度”，經(jīng)緯度兩個參數(shù)之間用豎線分開。例如：18.23445|46.000033。可以填空。RskLvl：客戶風(fēng)險等級。保留字段。填寫商戶端客戶的風(fēng)險等級，可以為空MerchantRetUrlN支付完成后5秒后頁面將自動跳轉(zhuǎn)到MerchantRetUrl與MerchantRetPara所指定的地址。例如：MerchantRetUrl = MerchantRetPara = Para1=abc|Para2=123則，點擊“返回按鈕”，客戶瀏覽器將跳轉(zhuǎn)到： 注意：MerchantRetPara參數(shù)可為空，商戶如果需要不止一個參數(shù)，可以自行把參數(shù)組合、拼裝，但組合后的結(jié)果不能帶有&

37、amp;字符，總長不能超過128個字節(jié)MerchantRetParaY詳見MerchantRetUrl中的說明2.3 頁頭導(dǎo)航及返回如上圖藍(lán)色框區(qū)域所示，頁頭導(dǎo)航及返回由商戶APP實現(xiàn)。支付流程涉及的html頁面已使用了橋返回機制，需要商戶自定義橋?qū)崿F(xiàn)，招行配置商戶定義的橋名，然后支付html頁面會給商戶APP提供一個回調(diào)方法【initCmbSignNetPay】-此方法也是商戶APP注冊過的回調(diào)方法，該回調(diào)方法里面存在招行html頁面回傳的json狀態(tài)值：【0-支付中,1-支付失敗,2-支付成功】，商戶APP通過招行給的回調(diào)方法，可獲取到此回調(diào)方法里面的狀態(tài)值做相應(yīng)的返回或者其他操作。支付過

38、程中的用戶簽約頁面，返回簽約狀態(tài)請參照“簽約功能”返回機制的章節(jié)。A、招行支付頁面使用的公共js方法：/商戶橋返回-beginvar default_data = pay_status: "0" ; var connectMerchantJSBridge = function (callback) try if (window. <%=TAG_MerchantBridgeName %>) callback(<%=TAG_MerchantBridgeName %>); else document.addEventListener("<%

39、=TAG_MerchantBridgeName %>Ready", function () callback(<%=TAG_MerchantBridgeName %>); , false); catch (ex) ; var cmbMerchantBridge = initCmbSignNetPay: function (payData) if (!payData) payData = default_data; connectMerchantJSBridge(function (bridge) if (typeof bridge = "undefined

40、") return; bridge.callHandler("initCmbSignNetPay", JSON.stringify(payData); ); ; window.cmbMerchantBridge = cmbMerchantBridge; /商戶橋返回-endB、招行每一次加載完一個頁面都會去連接商戶橋，并給出當(dāng)前的支付狀態(tài)【下面方法會調(diào)用上方A處的方法，從而連上商戶APP給的橋并給出相應(yīng)當(dāng)前的狀態(tài)值】 /0-支付中,1-支付失敗,2-支付成功 var payData = pay_status: "0" ; $.MReady(fu

41、nction () /給商戶(比如滴滴)回調(diào)方法用于返回 try cmbMerchantBridge.initCmbSignNetPay(payData); catch (ex) );C、界面展示：如本節(jié)開頭處的圖片的紅框區(qū)域，商戶在支付流程中通過以上方法可以獲取到支付流程中的以下幾個狀態(tài)pay_status：0：支付中1：支付失敗2：支付成功 D、注意：因界面安全性級別的問題，商戶端的支付成功結(jié)果不能以本接口返回的為準(zhǔn)，僅用于商戶界面處理依據(jù)。2.4 銀行支付結(jié)果通知命令銀行支付結(jié)果通知命令格式如下： 參數(shù)名稱可空參數(shù)說明SucceedN取值Y(成功)或N(失敗)；注意：Succeed為Y時

42、，商戶在處理支付結(jié)果通知命令時必須判斷Amount的值，該值為用戶的實際支付金額，以此金額為準(zhǔn)，不能以之前商戶系統(tǒng)產(chǎn)生定單時的金額為準(zhǔn)，防止用戶在得到支付頁面后修改支付金額CoNoN商戶號，6位長數(shù)字，由銀行在商戶開戶時確定BillNoN定單號(由支付命令送來)；注意：在正式交易中不要使用000000的定單號，因為測試接口在發(fā)通知時，定單號固定為000000AmountN實際支付金額(由支付命令送來)DateN交易日期(由支付命令送來)MerchantParaY商戶自定義參數(shù)(由支付命令送來)MsgN銀行通知商戶的支付結(jié)果消息；信息的前38個字符格式為：4位分行號6位商戶號8位銀行接受交易的日

43、期20位銀行流水號可以利用交易日期銀行流水號定單號對該定單進行結(jié)帳處理SignatureN銀行用自己的Private Key對通知命令的簽名2.5 支付命令代碼示例支付命令代碼示例：<form action=" method="post" target="_blank"><input value=" PrePayEUserP " name="MfcISAPICommand"/><input value="0755" name="BranchID&

44、quot;/><input value="000054" name="Cono"/><input value="9999000001" name="BillNo"/><input value="0.01" name="Amount"/><input value="20061231" name="Date"/><input value="30" name=&q

45、uot;ExpireTimeSpan"/><input value="6/noti" name="MerchantUrl"/><input value="Ref1=12345678|Ref2=ABCDEFG|Ref3=HIJKLM" name="MerchantPara"><input value=" name="MerchantRetUrl"/><input value="A=xxx&

46、amp;B=xxxx&C=xxxx" name="MerchantRetPara"/><input value="" name=MerchantCode></form>2.6 注意事項1、 商戶支付命令：（1） 支付系統(tǒng)支持GET方式和POST方式提交支付命令，建議使用POST方式；（2） 若MerchantUrl參數(shù)為空，不論MerchantPara參數(shù)是否為空，支付系統(tǒng)都將視為不需要通知商戶；（3） 若商戶已在使用基于Internet的網(wǎng)上支付系統(tǒng)，請選擇以下方式來生成商戶定單，以免造成PC支付系統(tǒng)和手

47、機支付系統(tǒng)的商戶定單混淆：a） 申請新的商戶號，該商戶號專用于手機支付；b） 使用同一個商戶號，但必須保證同一天內(nèi)兩種支付系統(tǒng)所使用的商戶定單號不重復(fù)；2、 處理支付結(jié)果通知命令（1） 商戶收到支付結(jié)果通知命令并處理完成后，應(yīng)及時回送消息，避免支付系統(tǒng)因未及時收到響應(yīng)而重復(fù)發(fā)送命令；（2） 若支付系統(tǒng)未及時收到響應(yīng)，將重復(fù)發(fā)送支付結(jié)果通知命令，商戶系統(tǒng)必須能夠處理重復(fù)通知的情況；（3） 由于Internet線路問題、商戶網(wǎng)絡(luò)配置改變問題、商戶服務(wù)器問題、商戶程序問題等原因，商戶最終接收銀行通知的程序可能收不到銀行通知。因此，商戶不能僅僅憑是否收到銀行通知確定是否給消費者提供服務(wù)，在商戶作系統(tǒng)設(shè)

48、計時也應(yīng)當(dāng)考慮到這個因素。商戶通知只能是獲取訂單成功的主要手段。商戶訂單查詢接口中，也提供了查詢訂單狀態(tài)的接口，商戶可以考慮用此接口進行輔助。（4） 若用戶付款后銀行系統(tǒng)或者商戶系統(tǒng)出現(xiàn)故障，則可能出現(xiàn)用戶已付款但是商戶系統(tǒng)不知道的情況，或者用戶已付款但是用戶瀏覽器未接收到結(jié)果頁的情況。商戶應(yīng)及時與銀行核對更新數(shù)據(jù)，并在系統(tǒng)設(shè)計時考慮到這種異常情況。如果這種異常情況引起付款糾紛，則商戶可通過以下方式解決糾紛：a) 若為非立即結(jié)帳商戶，并且該定單尚未結(jié)帳，可利用撤消定單功能，撤銷尚未結(jié)帳的商戶定單；b) 若該定單已經(jīng)結(jié)帳，可利用退款功能進行退款處理；遇到問題可參見商戶常見問題解答。（5） 商戶回

49、送的結(jié)果頁面將被發(fā)送給用戶手機終端瀏覽器，因此必須符合WAP標(biāo)準(zhǔn)規(guī)范；為使整個支付過程平滑無縫，建議商戶在支付命令的MerchantPara參數(shù)中附帶用戶臨時SessionID；3. 簽約結(jié)果回調(diào)功能3.1 流程簽約結(jié)果信息，異步回調(diào)通知商戶。3.2 接口參照： 招商銀行互聯(lián)網(wǎng)商戶直聯(lián)接口說明書-有密支付 簽約結(jié)果回調(diào)（BKQY)4. 解約功能4.1 流程取消客戶在招行一網(wǎng)通支付的已簽約協(xié)議4.2 接口參照： 招商銀行互聯(lián)網(wǎng)商戶直聯(lián)接口說明書-有密支付客戶電子協(xié)議取消（CMQX）5. 主動支付退款功能5.1 接口簡介專門為那些需要頻繁進行退款操作的網(wǎng)上商戶而

50、設(shè)計的。通過使用直聯(lián)退款接口，商戶可以把繁瑣的手工退款工作交給計算機完成，由計算機批量、自動地執(zhí)行退款操作。商戶還可以利用直聯(lián)退款接口，把退款功能集成到自己的電子商務(wù)系統(tǒng)中。目前直聯(lián)退款功能，只提供給使用了電子商務(wù)平臺的商戶5.2 使用方法使用直聯(lián)退款功能，必須正確完成以下兩項工作：1、 使用“系統(tǒng)管理員”登錄電子商務(wù)平臺，維護商戶密鑰。具體步驟，請參考 設(shè)置商戶密鑰方法.doc,商戶密鑰長度為16個字符，必須包含大寫字符、小寫字母和數(shù)字。2、 使用帶有直聯(lián)退款接口的商戶開發(fā)包，和其他直聯(lián)接口一樣，使用直聯(lián)退款接口之前，也必須調(diào)用開發(fā)包中的LoginC登錄，然后再調(diào)用退款A(yù)PI。執(zhí)行完退款后，

51、應(yīng)該調(diào)用Logout退出。退款直聯(lián)接口的定義：public int RefundOrder(String pszDate, String pszBillNo, String pszAmt,String pszDesc, String pszKey)參數(shù)說明：參數(shù)可空說明pszDateN定單的交易日期。格式為8位數(shù)字。例如“20050810”pszBillNoN訂單號pszAmtN退款金額。應(yīng)該帶有2位小數(shù)pszDescY退款說明。長度不應(yīng)該超過100字節(jié)pszKeyN商戶密鑰。建議把商戶密鑰作為一個配置文件保存，在調(diào)用直聯(lián)退款之前，讀取出來。返回值：返回值說明0退款成功其他操作執(zhí)行失敗。（但退款仍然有可能成功）此時應(yīng)該調(diào)用GetLastErr，取得錯誤原因描述。關(guān)于操作失敗，但退款成功的情況，可能包括：通訊失敗、通訊超時等情況因此，建議操作失敗的情況，通過GetLastErr獲取錯誤原因描述，