銀聯在線網關支付,快速接入指南
銀聯在線支付網關是中國銀聯聯合各商業銀行為持卡人提供的集成化、綜合性互聯網支付工具,主要支持輸入卡號付款、用戶登錄支付、網銀支付、迷你付(IC卡支付)等多種支付方式,為持卡人提供境內外網上購物支付服務。網關支付產品主要適用於持卡人在商戶網站B2C購物支付場景,持卡人通過點擊銀聯在線支付圖標,並跳轉銀聯頁面完成支付信息錄入,最終完成支付。
特色
安全支付
采用多重安全防控技術,強大的風險監控系統實時攔截交易。
完備的風險處置和化解機制,維護參與各方的利益。
快捷支付
持卡人無需開通網銀即可暢享網上支付服務,商戶可以直接受理帶有銀聯Logo的約40多億張銀聯卡。
全球支付
銀聯跨境網上支付服務已經覆蓋全球主要國家和地區,國內外銀聯卡均可使用,境外網上受理商戶免收貨幣轉換費,持卡人足不出戶即可
優惠樂享
銀聯在線支付與240多家銀行及萬余家商戶持續不斷的開展優惠活動,抽獎、立減、返現、返券、送話費、送積分等獎勵形式不一而足,讓持卡人樂享網上支付新生活。
下面將為大家展示在線網關支付有哪些API接口,如何快速接入在線網關支付。介紹如何從零開始,使用銀聯開放服務平臺服務端SDK快速接入網關支付產品,完成與銀聯對接的部分。
註意:以下的代碼示例和Demo是用來闡述API基本使用方法的,針對大部分基本業務場景。供商戶參考,特殊情況請按照進階功能擴展,確保符合實際業務需求。
API接口:消費接口、消費撤銷接口、退貨接口、交易狀態查詢接口、銀聯加密公鑰更新查詢接口、預授權接口、預授權撤銷、預授權完成、預授權完成撤銷、文件傳輸接口(對賬文件下載)。您可以點擊在線網關支付
第一步:申請入網
您有2種方式可以選擇:
1.在銀聯官網註冊:
您可以點擊頁面中的【我要入網】,發起自助簽約申請。
詳見入網申請流程
2.聯系服務商:
見服務商介紹
第二步:申請證書
開發者調用接口前需要先獲取三個證書:簽名證書、敏感信息加密證書、驗簽證書。
● 簽名證書
- 證書用途
商戶或機構對報文中出現簽名域(signature)之外的所有數據元采用key=value的形式按照名稱排序, 然後以&作為連接符拼接成待簽名串。其次,對待簽名串使用SHA-256算法做摘要, 再使用銀聯頒發給商戶的簽名私鑰證書中的私鑰對摘要做簽名操作(簽名時算法選擇
- 如何獲取
測試環境簽名證書接從開發包中目錄assets下獲取。
生產環境簽名證書獲取方式:入網流程走完後,銀聯業務運營中心會發送入網通知郵件給申請表中的聯系人郵箱, 請參考郵件中《證書下載、導出及上傳流程》文檔進行下載, 下載時需要的證書序列號、授權碼會在郵件正文或者附件中給出。
● 驗簽證書
- 證書用途
商戶或機構對報文中出現簽名域(signature)之外的所有數據元采用key=value的形式按照名稱升序排序,然後以&作為連接符拼接成待簽名串。 其次,對待簽名串使用 SHA-256算法做摘要,再使用商戶入網時銀聯提供的驗簽公鑰證書中的公鑰對摘要和報文中的簽名信息做簽名驗證操作。
- 如何獲取
驗簽證書直接從開發包中目錄assets下獲取。
第三步:集成並配置SDK
為了幫助開發者調用開放接口,我們提供了開放平臺服務端SDK,包含JAVA、PHP和.NET三語言版本, 封裝了簽名&驗簽、HTTP接口請求等基礎功能。請先下載對應語言版本的SDK並引入您的開發工程。
網關支付
網關支付產品包含兩類API,在設置測試、生產地址時請註意前後臺交易地址差異。
前臺交易API: 消費交易為前臺交易,需要跳轉到銀聯支付頁面進行支付。需要從前端頁面以Form表單的形式發起請求,瀏覽器會自動跳轉至銀聯的相關頁面(一般是支付或開通頁面),用戶在該頁面完成相關業務操作後再回跳到商戶指定頁面。
後臺交易API: 直接從服務端發起HTTP請求,商戶網站按照接口發送到銀聯後臺即可,不跳轉到銀聯頁面,除消費交易以外的其他交易均屬於後臺交易。
調用流程
如上圖所示,持卡人在商戶的網站下單後,商戶系統按照 消費API的參數規範生成訂單數據,然後在前端頁面通過Form表單的形式請求到銀聯前臺地址,自動將頁面跳轉至銀聯網關頁面。
持卡人在銀聯頁面完成支付後,會根據商戶在消費API中傳入的前臺通知地址frontUrl在持卡人主動點擊“返回商戶”時跳轉回商戶頁面,同時在應答報文中附帶上支付結果參數,詳細通知參數見 消費API的前臺通知。
同時,銀聯還會根據 原始消費API中傳入的異步通知地址backUrl,通過POST請求的形式將支付結果作為參數通知到商戶系統,詳情見後臺通知(異步應答)。
除了正向支付流程外,銀聯也提供交易狀態查詢、退貨以及對賬等配套API。
特別註意
● 由於前臺通知需要持卡人主動點擊“返回商戶”,存在不可靠性,前臺通知只能作為商戶支付結果頁的入口,最終支付結果必須以交易狀態查詢接口返回為準,不能僅依賴前臺通知。
● 消費的交易狀態查詢收到respCode=00同時origRespCode=00時則表示被查詢交易成功,其他表示處理中,非成功的前臺消費交易都可以繼續跳轉過來重新支付。
● 商戶系統接收到前臺通知或後臺通知以後,必須通過驗簽(驗證通知中的signature參數)來確保支付通知是由銀聯發送的。驗簽方法參考通知。
● 接收到前臺通知或後臺通知並驗簽通過後,根據通知中的orderId、txnTime、merId發起交易查詢請求查詢交易結果。
3.前臺通知應答碼
前臺通知表示成功的應答碼是00或A6,只有支付成功時才會發送前臺通知,交易失敗時(比如余額不足時)不發送。
後臺通知應答碼
後臺通知表示成功的應答碼是00或A6,網關支付只有交易成功全渠道才會發後臺通知給商戶;
其他後臺資金類交易,如退貨、消費撤銷,全渠道系統均會給請求方後臺通知,請求方也必須實現接收後臺通知。
使用SDK快速接入
網關支付com.unionpay.acp.demo.consume.Form_6_2_FrontConsume:
protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { resp.setContentType("text/html; charset="+ DemoBase.encoding); //前臺頁面傳過來的 String merId = req.getParameter("merId"); String txnAmt = req.getParameter("txnAmt"); Map<String, String> requestData = new HashMap<String, String>(); /***銀聯全渠道系統,產品參數,除了encoding自行選擇外其他不需修改***/ requestData.put("version", DemoBase.version); //版本號,全渠道默認值 requestData.put("encoding", DemoBase.encoding); //字符集編碼,可以使用UTF-8,GBK兩種方式 requestData.put("signMethod", SDKConfig.getConfig().getSignMethod()); //簽名方法 requestData.put("txnType", "01"); //交易類型 ,01:消費 requestData.put("txnSubType", "01"); //交易子類型, 01:自助消費 requestData.put("bizType", "000201"); //業務類型,B2C網關支付,手機wap支付 requestData.put("channelType", "07"); //渠道類型,這個字段區分B2C網關支付和手機wap支付;07:PC,平板 08:手機 /***商戶接入參數***/ requestData.put("merId", merId); //商戶號碼,請改成自己申請的正式商戶號或者open上註冊得來的777測試商戶號 requestData.put("accessType", "0"); //接入類型,0:直連商戶 requestData.put("orderId",DemoBase.getOrderId()); //商戶訂單號,8-40位數字字母,不能含“-”或“_”,可以自行定制規則 requestData.put("txnTime", DemoBase.getCurrentTime()); //訂單發送時間,取系統時間,格式為YYYYMMDDhhmmss,必須取當前時間,否則會報txnTime無效 requestData.put("currencyCode", "156"); //交易幣種(境內商戶一般是156 人民幣) requestData.put("txnAmt", txnAmt); //交易金額,單位分,不要帶小數點 //requestData.put("reqReserved", "透傳字段"); //請求方保留域,如需使用請啟用即可;透傳字段(可以實現商戶自定義參數的追蹤)本交易的後臺通知,對本交易的交易狀態查詢交易、對賬文件中均會原樣返回,商戶可以按需上傳,長度為1-1024個字節。出現&={}[]符號時可能導致查詢接口應答報文解析失敗,建議盡量只傳字母數字並使用|分割,或者可以最外層做一次base64編碼(base64編碼之後出現的等號不會導致解析失敗可以不用管)。 //前臺通知地址 (需設置為外網能訪問 http https均可),支付成功後的頁面 點擊“返回商戶”按鈕的時候將異步通知報文post到該地址 //如果想要實現過幾秒中自動跳轉回商戶頁面權限,需聯系銀聯業務申請開通自動返回商戶權限 //異步通知參數詳見open.unionpay.com幫助中心 下載 產品接口規範 網關支付產品接口規範 消費交易 商戶通知 requestData.put("frontUrl", DemoBase.frontUrl); //後臺通知地址(需設置為【外網】能訪問 http https均可),支付成功後銀聯會自動將異步通知報文post到商戶上送的該地址,失敗的交易銀聯不會發送後臺通知 //後臺通知參數詳見open.unionpay.com幫助中心 下載 產品接口規範 網關支付產品接口規範 消費交易 商戶通知 //註意:1.需設置為外網能訪問,否則收不到通知 2.http https均可 3.收單後臺通知後需要10秒內返回http200或302狀態碼 // 4.如果銀聯通知服務器發送通知後10秒內未收到返回狀態碼或者應答碼非http200,那麽銀聯會間隔一段時間再次發送。總共發送5次,每次的間隔時間為0,1,2,4分鐘。 // 5.後臺通知地址如果上送了帶有?的參數,例如:http://abc/web?a=b&c=d 在後臺通知處理程序驗證簽名之前需要編寫邏輯將這些字段去掉再驗簽,否則將會驗簽失敗 requestData.put("backUrl", DemoBase.backUrl); // 訂單超時時間。 // 超過此時間後,除網銀交易外,其他交易銀聯系統會拒絕受理,提示超時。 跳轉銀行網銀交易如果超時後交易成功,會自動退款,大約5個工作日金額返還到持卡人賬戶。 // 此時間建議取支付時的北京時間加15分鐘。 // 超過超時時間調查詢接口應答origRespCode不是A6或者00的就可以判斷為失敗。 requestData.put("payTimeout", new SimpleDateFormat("yyyyMMddHHmmss").format(new Date().getTime() + 15 * 60 * 1000)); ////////////////////////////////////////////////// // // 報文中特殊用法請查看 PCwap網關跳轉支付特殊用法.txt // ////////////////////////////////////////////////// /**請求參數設置完畢,以下對請求參數進行簽名並生成html表單,將表單寫入瀏覽器跳轉打開銀聯頁面**/ Map<String, String> submitFromData = AcpService.sign(requestData,DemoBase.encoding); //報文中certId,signature的值是在signData方法中獲取並自動賦值的,只要證書配置正確即可。 String requestFrontUrl = SDKConfig.getConfig().getFrontRequestUrl(); //獲取請求銀聯的前臺地址:對應屬性文件acp_sdk.properties文件中的acpsdk.frontTransUrl String html = AcpService.createAutoFormHtml(requestFrontUrl, submitFromData,DemoBase.encoding); //生成自動跳轉的Html表單 LogUtil.writeLog("打印請求HTML,此為請求報文,為聯調排查問題的依據:"+html); //將生成的html寫到瀏覽器中完成自動跳轉打開銀聯支付頁面;這裏調用signData之後,將html寫到瀏覽器跳轉到銀聯頁面之前均不能對html中的表單項的名稱和值進行修改,如果修改會導致驗簽不通過 resp.getWriter().write(html); } |
在線網關支付API的關鍵入參、關鍵通知參數等更多詳細信息可點擊鏈接:https://open.unionpay.com/tjweb/acproduct/list?apiservId=448
銀聯在線網關支付,快速接入指南