省號百平臺支付接口技術(shù)規(guī)范-V10

【W(wǎng)EB網(wǎng)上號百技術(shù)接口規(guī)范】V1.02011年6月湖北公眾目錄1.文檔說明 31.1文檔目標 31.2閱讀對象 31.3相關(guān)約定 31.4業(yè)務及技術(shù)支持 32.業(yè)務描述及接口開發(fā) 32.1功能說明及流程 32.2商戶接入前提 42.3參數(shù)說明 52.3.1 HTTP訂單支付請求接口 52.3.2退款接口 52.4開發(fā)提示 52.4.1商戶對支付結(jié)果的處理 53.參考資料 53.1出參類型說明 51.文檔說明1.1文檔目標本文檔的目的是為WEB網(wǎng)上支付定義一個標準接口規(guī)范，以幫助各省號百及合作商戶技術(shù)人員接入號百網(wǎng)上支付，并快速掌握號百網(wǎng)上支付相關(guān)功能，為業(yè)務開展提供支付服務。1.2閱讀對象對號百網(wǎng)上支付存在需求的公司、機構(gòu)及合作商戶的網(wǎng)上應用開發(fā)人員、維護人員和業(yè)務管理人員。1.3相關(guān)約定商戶：指已注冊成為號百用戶、并使用號百產(chǎn)品實現(xiàn)其收付費功能需求、為其用戶提供各類產(chǎn)品或者相關(guān)服務的個人。用戶：指在商戶網(wǎng)站等系統(tǒng)購物的個人。購物：指用戶在商戶網(wǎng)站購買相關(guān)產(chǎn)品或服務。1.4業(yè)務及技術(shù)支持如果您有任何業(yè)務及技術(shù)上的疑問，可聯(lián)系省號百技術(shù)人員。2.業(yè)務描述及接口開發(fā)2.1功能說明及流程WEB網(wǎng)上支付方式是指利用網(wǎng)銀賬戶，通過互聯(lián)網(wǎng)Web網(wǎng)頁操作完成支付過程的方式。此種方式下，客戶利用PC終端，通過登陸號百或合作方網(wǎng)站，進行商品或服務選購，生成并確認訂單信息，根據(jù)本人使用借記卡或貸記卡付款的要求，選擇相應銀行通過銀行網(wǎng)銀界面實現(xiàn)支付的功能。用戶向交易網(wǎng)站購物時，需要通過一定方式向商戶支付相關(guān)費用。商戶網(wǎng)站系統(tǒng)如果集成號百網(wǎng)上支付功能，則可以讓用戶安全、方便、快捷地向商戶支付選購商品及服務款項，并且商戶也可以很容易了解到款項的到帳情況及用戶購買的產(chǎn)品或服務。整體流程如下：用戶在商戶交易網(wǎng)站選擇產(chǎn)品或服務，在下訂單支付完成后，商戶網(wǎng)站會將該訂單號及對應訂單金額等相關(guān)信息提交到號百，然后跳轉(zhuǎn)到號百頁面進行支付。當支付完成后，號百將支付結(jié)果返回商戶，并且根據(jù)商戶指定的地址跳轉(zhuǎn)到商戶指定頁面。商戶系統(tǒng)后臺接收到支付結(jié)果之后，對數(shù)據(jù)庫進行相應更新，然后在顯示給用戶的頁面中作出相應提示。2.2商戶接入前提商戶接入號百平臺網(wǎng)上支付，須準備好指定網(wǎng)站供客戶上網(wǎng)瀏覽，并為用戶提供商品查詢、選購，直至下單的功能及頁面展示。以下頁面須由商戶預先實現(xiàn)方能進行號百網(wǎng)上支付接入，參考圖示如下：2.3參數(shù)說明2.3.1 HTTP訂單支付請求接口http訂單支付請求地址：/serviceInterface/do.aspx接口描述接口名稱重定向跳轉(zhuǎn)訂單支付請求接口接口描述通過調(diào)用支付接口向號百平臺發(fā)出支付請求,平臺通過支付Portal與用戶進行交互，完成支付處理后，重定向回應用系統(tǒng)（SP）接口提供者號百平臺接口使用者應用系統(tǒng)（SP）接口定義應用系統(tǒng)的請求參數(shù)定義：字段名稱長度是否必填說明BSTMERCHANTIDSP身份標識CHAR(30)是由號百平臺統(tǒng)一分配ORDERSEQ訂單號CHAR(30)是由SP提供，在sp處不能重復，用于標識一個唯一的訂單，訂單號可以在沒有支付成功的情況下，再次進行交易，但每次交易時的訂單請求交易流水號不能重復數(shù)字或字母組成ORDERREQTRANSEQ訂單請求交易流水號CHAR(30)是訂單支付請求的交易流水號每次訂單支付時，不要重復以日期時間yyyyMMddHHmmssff+號百平臺商戶代碼（由號百平臺提供），如：200610121324253500012006101213242535為日期時間0001為號百給定的商戶代碼數(shù)字或字母組成ORDERDATE訂單日期CHAR(8)是由SP提供，長度8yyyy-MM-dd格式ORDERAMOUNT訂單總金額NUMBER(10)是單位：分訂單總金額=產(chǎn)品金額+附加金額PRODUCTAMOUNT產(chǎn)品金額NUMBER(10)是單位：分ATTACHAMOUNT附加金額NUMBER(10)是單位：分VIEWURL前臺返回地址CHAR(256)是SP提供的用于接收交易返回的前臺url，不做業(yè)務處理，僅僅用于前臺頁面顯示結(jié)果DEALURL后臺返回地址CHAR(256)是SP提供的用于接收交易返回的后臺url，用于實際的業(yè)務處理USERIDSP用戶IDCHAR(40)是SP平臺用戶ID，為SP平臺用戶體系的唯一標識。REMARK備注CHAR(256)是SP平臺提供對本次訂單的描述如：“充值”或“購買了一張電影票”ATTACH附加信息CHAR(50)否SP附加信息MACMAC校驗域CHAR(256)是采用標準的MD5算法，由SP實現(xiàn)說明：1）商戶要保證訂單號的唯一性。2）在商戶提交訂單的頁面上，提交按鈕應該是點擊一次后，馬上不可用，防止用戶多次提交。3）接口方式采用表單方式，商戶將以上信息包含在表單中，直接SUBMIT到號百平臺url上4）MAC校驗，保證了交易信息到支付平臺的完整性，參與MAC運算的字符及其順序如下：BSTMERCHANTID=123456789&ORDERSEQ=20060314000001&ORDERDATE=20060314&ORDERAMOUNT=10000將上述固定順序組織的字符串，參數(shù)名均為大寫，使用標準md5算法進行摘要，然后將摘要果轉(zhuǎn)成16進制字符串，就是校驗域MAC的值，并在提交訂單時，將MAC值和訂單信息一起提交到號百平臺號百平臺的響應參數(shù)定義：字段名稱類型是否必填說明BSTUPTRANSEQ號百平臺交易流水號CHAR(50)是由號百平臺提供，SP必須保存該信息，作為對帳依據(jù)BSTTRANDATE號百平臺交易日期CHAR(8)是由號百平臺提供，SP必須保存該信息，格式：yyyy-MM-dd,商戶對賬、清算報表以此日期為準RETNCODE處理結(jié)果碼CHAR(4)是由號百平臺統(tǒng)一定義，SP需保存，作為對帳數(shù)據(jù)。結(jié)果碼為“0000”表示支付成功，其他值則表示支付失敗RETNINFO處理結(jié)果解釋碼CHAR(10)是由號百平臺統(tǒng)一定義，對支付結(jié)果的說明碼ORDERREQTRANSEQ訂單請求交易流水號CHAR(32)是從SP發(fā)送的訂單的信息中獲得，號百平臺原值傳回ORDERSEQ訂單號CHAR(32)是從SP發(fā)送的訂單的信息中獲得，號百平臺原值傳回ORDERAMOUNT訂單總金額NUMBER(10)是從SP發(fā)送的訂單的信息中獲得，號百平臺原值傳回，單位：分訂單總金額=產(chǎn)品金額+附加金額PRODUCTAMOUNT產(chǎn)品金額NUMBER(10)是從SP發(fā)送的訂單的信息中獲得，號百平臺原值傳回，單位：分ATTACHAMOUNT附加金額NUMBER(10)是從SP發(fā)送的訂單的信息中獲得，號百平臺原值傳回，單位：分USERIDSP用戶IDCHAR(40)是SP平臺用戶ID，為SP平臺用戶體系的唯一標識。號百平臺原值傳回ATTACHSP附加信息CHAR(32)否從SP發(fā)送的訂單的信息中獲得，號百平臺原值傳回SIGN數(shù)字簽名CHAR(256)是數(shù)字簽名算法由號百平臺統(tǒng)一提供，作為核查依據(jù)說明：商戶提供的后臺url，號百平臺是以post方式將支付結(jié)果提交到該url上商戶平臺在收到后臺支付結(jié)果后，請直接在應答時寫入格式為UPTRANSEQ_XXXXXX的字符串，其中UPTRANSEQ_為固定寫死，XXXXXX為號百平臺發(fā)送過去的號百平臺交易流水號號百平臺，如果在60秒鐘沒有收到應答，則會重復發(fā)送，重復次數(shù)是3次，如果還沒有應答會每隔半小時發(fā)送一次截止到第二天凌晨。號百平臺如果收到應答，則不再發(fā)送支付結(jié)果。當商戶收到號百平臺發(fā)回來的支付結(jié)果信息后，獲取支付結(jié)果和簽名的信息，然后對數(shù)字簽名進行校驗，步驟如下：1）商戶將支付結(jié)果的明文和密鑰組成一個固定順序的串，如下：BSTUPTRANSEQ=20080101000001&BSTMERCHANTID=0250000001&ORDERSEQ=2006050112564931556&ORDERAMOUNT=10000&RETNCODE=0000&RETNINFO=0000&BSTTRANDATE=20060101&KEY=123456串的順序不能改變，參數(shù)名一定要用大寫；KEY的值由號百平臺統(tǒng)一提供。2）將1）獲得的結(jié)果使用標準的MD5算法運算，再將運算結(jié)果轉(zhuǎn)成16進制字符串；3）將2）獲得值和SIGN值進行比較，如一致則數(shù)字簽名正確，說明信息沒有被篡改。2.3.2退款接口Webservices接口地址：/services方法名：Stringrefund()號百支付平臺對調(diào)用該接口的服務器地址進行綁定，在聯(lián)調(diào)前，請?zhí)峁┓掌鞯刂?。請求入?yún)⒄f明：參數(shù)含義類型長度必填備注commCode商戶代碼xsd:string20是由號百平臺統(tǒng)一分配給各接入商戶subCommCode商戶子代碼xsd:string30否商戶子代碼如沒有則填空commPwd商戶調(diào)用密碼xsd:string20是商戶執(zhí)行時需填入相應密碼oldOrderId原扣款訂單號xsd:string30是原扣款成功的訂單號oldOrderPayId原訂單請求支付流水號xsd:string30是原訂單請求支付流水號orderRefundId退款流水號xsd:string30是該流水在商戶處必須是唯一的，而且每次發(fā)起支付或退款時，都必須是唯一的transamt訂單交易金額xsd:string12是單位為元如2.00reqTime交易請求時間xsd:string14是YYYYMMDDHHMMSSmacMac校驗域xsd:string32是md5摘要為什么支付時交易金額單位是分，而在退款時時以元為單位？能否統(tǒng)一？方法返回參數(shù)類型長度必填備注xsd:String20是具體見出參類型說明返回成功即表示退款成功說明：1）商戶要保證退款流水號的唯一性。2）在商戶提交退款時，防止多次提交同一筆退款。3）接口方式采用webservices方式，key由號百支付平臺分配給各商戶。4）MAC校驗，保證了交易信息到支付平臺的完整性，參與MAC運算的字符及其順序如下：COMMCODE=123456789&COMMPWD=123456&ORDERREFUNDID=20080314000001&REQTIME=20080314&TRANSAMT=10000&KEY=DJKF34ER35D58D商戶平臺將上述固定順序組織的字符串，參數(shù)名均為大寫，使用標準md5算法進行摘要，然后將摘要果轉(zhuǎn)成16進制字符串，就是校驗域MAC的值，將MAC值和訂單信息調(diào)用接口時，一起提供給號百支付平臺附：MD5算法的.net實現(xiàn)：///<summary>///MD5加¨?密¨1///</summary>///<paramname="str">加¨?密¨1字á?符¤?</param>///<returns></returns>privatestringmd5(stringstr){returnSystem.Web.Security.FormsAuthentication.HashPasswordForStoringInConfigFile(str,"MD5");}上述算法如果在實施時遇到具體問題，可以協(xié)商解決。2.4開發(fā)提示2.4.1商戶對支付結(jié)果的處理商戶在接收到號百的支付結(jié)果之后，基于安全的考慮，請務必要判斷同一訂單號是否已經(jīng)針對支付成功的情況進行過處理。特別是對于一些使用號百提供充值功能的商戶，必須嚴格防止對同一訂單對用戶多次進行充值。如果同一訂單號，已經(jīng)按照支付成功的情況進行過處理，商戶再次接收到時則不要重復處理。因網(wǎng)絡或銀行服務器原因，號百可能第一次發(fā)送支付失敗的結(jié)果給商戶，但后來會對同一訂單號發(fā)送支付成功的信息給商戶。商戶應在保證對加密驗證串等信息嚴格驗證的前提下，對相同訂單號按照支付成功的業(yè)務邏輯進行處理。即商戶收到的支付結(jié)果通知有失敗也有成功，以成功信息為準進行支付成功相關(guān)業(yè)務處理。可能會由于網(wǎng)絡或者用戶刷新頁面的原因，商戶的頁面可能短時間內(nèi)會多次接收到支付結(jié)果信息，而支付人看到的只能是最后的頁面。商戶最好能在后續(xù)的提示中，給出讓支付人不易誤解的提示信息。3.參考資料3.1出參類型說明0本次調(diào)用成功0000本次調(diào)用成功1001商戶未注冊1002商戶已注冊，但未審批1003商戶已注冊，已審批，但未開通1004商戶已注銷1005商戶原自助服務用戶密碼錯誤1006商戶已注冊，但未開通此業(yè)務1007商戶已注冊，但未開通此接入方式1101訂單正在交易中，不允許再次交易1102訂單交易成功，不允許再次交易1103訂單交易