- 行業(yè)新聞
-
上海翻譯公司完成電子系統(tǒng)“財付通”開發(fā)指南中文翻譯
發(fā)布時間：2019-08-20 10:41 點擊：
上海翻譯公司完成電子系統(tǒng)“財付通”開發(fā)指南中文翻譯
1 引言1.1 文檔概述本文件描述財付通針對手機支付行業(yè)提供的支付解決方案。供內(nèi)部相關(guān)開發(fā)和技術(shù)支持人員與商戶平臺服務(wù)方技術(shù)人員使用。文檔分別從交互模式、簽名、接口、注意事項等方面詳細介紹了財付通的工作方式和開發(fā)過程，可以幫助開發(fā)人員快速入門并掌握開發(fā)技能，同時也可以作為日后接口參數(shù)以及參數(shù)類型的速查手冊。1.2 閱讀對象供財付通開發(fā)人員與商戶平臺服務(wù)方技術(shù)或業(yè)務(wù)人員參考和查詢。1.3 業(yè)務(wù)術(shù)語術(shù)語 示例 說明商戶號 1900000109 機票平臺的賬號，只用于記賬，由財付通自動分配的10位數(shù)字密鑰 9ba2380ad9b2aacb96bca514eda27ac9 為保證通訊不被篡改，財付通與商戶之間約定的32位字符串，算簽名sign時使用財付通賬戶號，目前支持兩種格式：qq號碼和email賬戶金額 100000 金額，默認為RMB，以分為單位。1000表示RMB10.002 方案概述2.1 行業(yè)背景在電子商務(wù)中，商家、買家、中間服務(wù)方是交易活動中的三個環(huán)節(jié)。買家選購商品下發(fā)訂單，商家確認訂單，買家通過中間服務(wù)方向商家支付貨款，商家發(fā)貨履行訂單。在這個過程中商家的網(wǎng)站需要集成中間服務(wù)方的支付功能，讓買家完成貨款的支付。財付通作為一家專業(yè)的中間服務(wù)方除了提供支付接口外，還提供了支付結(jié)果查詢接口和訂單查詢接口等，幫助商家記錄貨款的往來，讓商家能把更多的精力集中到商品服務(wù)上。商戶的貨款會按照合同約定以T0～T7的頻率結(jié)算到商戶的銀行賬戶，同時收取手續(xù)費。這個過程由財付通自動完成，商戶無需做相關(guān)開發(fā)工作。2.2 接口介紹接口名 請求URL 功能說明 結(jié)果說明初始化接口 https://wap.tenpay.com/cgi-bin/wappayv2.0/wappay_init.cgi 調(diào)用該接口時指定支付參數(shù)，完成買家賬戶向商家賬戶的支付，采用頁面跳轉(zhuǎn)交互模式和后臺通知交互模式 初始化wap請求，通過生成token_id來進行交互驗證。支付接口 https://wap.tenpay.com/cgi-bin/wappayv2.0/wappay_gate.cgi調(diào)用該接口時指定支付參數(shù)，完成買家賬戶向商家賬戶的支付，采用頁面跳轉(zhuǎn)交互模式和后臺通知交互模式 結(jié)果分兩路返回：一路為前臺在callback_url后添加參數(shù)返回，表現(xiàn)為頁面跳轉(zhuǎn)；一路為后臺在notify_url后添加參數(shù)返回，要求后臺notify_url收到通知后進行響應(yīng)。訂單查詢接口 http://wap.tenpay.com/cgi-bin/wapmainv2.0/wm_query_order.cgi 商戶在后臺對任意一筆訂單發(fā)起查詢，采用后臺系統(tǒng)調(diào)用交互模式 根據(jù)訂單號以XML格式返回具體的訂單內(nèi)容和狀態(tài)2.3 業(yè)務(wù)實現(xiàn)流程其中藍色直線箭頭表示系統(tǒng)調(diào)用，黑色直線箭頭表示頁面跳轉(zhuǎn)。1) 商戶請求交易初始化：商戶根據(jù)客戶的支付行為生成訂單，包括商戶號、商戶訂單號、金額、等支付要素。并提交請求進行交易初始化和獲取token_id。2) 財付通接收到商戶的交易初始化請求后，系統(tǒng)創(chuàng)建財付通交易單，同時生成token_id，并返回該token_id。3) 商戶請求WAP支付：商戶根據(jù)token_id生成WAP支付請求，通過頁面跳轉(zhuǎn)方式引導(dǎo)用戶進入到財付通手機支付中心。4) 用戶在財付通手機支付中心完成支付后，財付通調(diào)用notify_url通知商戶交易結(jié)果。5) 商戶返回通知結(jié)果：根據(jù)扣款成功通知，做發(fā)貨等邏輯處理，并返回財付通處理結(jié)果。財付通確認交易完成并回跳至商戶的callback_url。2.4 頁面回跳callback_urlcallback_url應(yīng)為WAP頁面，給買家展示支付結(jié)果。2.5 結(jié)果通知notify_urlnotify_url接收財付通從后臺發(fā)出的支付結(jié)果通知。在此通知接口模式中，商戶需要確保notify_url穩(wěn)定可靠。該notify_url完成接收財付通發(fā)送的支付結(jié)果信息，交易結(jié)果信息將以GET方式傳遞至商戶。財付通只將支付成功的訂單進行返回。3 數(shù)據(jù)格式3.1 GET或POST采用HTTP標準的GET或POST協(xié)議，為了保證接收方接收數(shù)據(jù)正確，傳遞的參數(shù)如果存在特殊字符（如&、=等）需要進行URL Encode。GET或POST一般用于頁面跳轉(zhuǎn)交互模式的請求和通知、后臺系統(tǒng)調(diào)用模式的請求、后臺通知模式的請求。3.2 XML數(shù)據(jù)格式采用標準XML協(xié)議，所有參數(shù)只存在一級節(jié)點中，不采用多級節(jié)點嵌套。<?xml version="1.0" encoding="gb2312" ?><root><retcode>0</retcode><retmsg></retmsg><partner>1900000109</partner><status>0</status><sign>8DB4A013A8B515349C307F1E448CE836</sign></root>一般有返回碼retcode參數(shù)，0表示調(diào)用成功；非0表示調(diào)用失敗，失敗時結(jié)果不簽名，只有retcode和返回信息retmsg。XML一般用于后臺系統(tǒng)調(diào)用模式的應(yīng)答。3.3 字符串格式直接以簡單字符串作為數(shù)據(jù)內(nèi)容，一般用于后臺通知模式的接口反饋，表示處理是否成功。返回結(jié)果 結(jié)果說明success 處理成功，財付通系統(tǒng)收到此結(jié)果后不再進行后續(xù)通知fail或其他字符 處理不成功，財付通收到此結(jié)果或者沒有收到任何結(jié)果，系統(tǒng)通過補單機制（詳見第6節(jié)）再次通知4 數(shù)字簽名為了保證數(shù)據(jù)傳輸過程中的數(shù)據(jù)真實性和完整性，我們需要對數(shù)據(jù)進行數(shù)字簽名，在接收簽名數(shù)據(jù)之后進行簽名校驗。數(shù)字簽名有兩個步驟，先按一定規(guī)則拼接要簽名的原始串，再選擇具體的算法和密鑰計算出簽名結(jié)果。一般失敗的結(jié)果不簽名。4.1 簽名原始串無論是請求還是應(yīng)答，無論是用get、post還是xml，簽名原始串按以下方式組裝成字符串：1、除sign字段外，所有參數(shù)按照字段名的ascii碼從小到大排序后使用QueryString的格式（即key1=value1&key2=value2…）拼接而成，空值不傳遞，不參與簽名組串。2、所有參數(shù)是指通信過程中實際出現(xiàn)的所有非空參數(shù)，即使是接口中無描述的字段，也需要參與簽名組串。如退款接口中無test字段，如果商戶請求時或財付通應(yīng)答時，test有值，test字段也得參與參與簽名組串3、簽名原始串中，字段名和字段值都采用原始值，不進行URL Encode。4、財付通返回的應(yīng)答或通知消息可能會由于升級增加參數(shù)，請驗證應(yīng)答簽名時注意允許這種情況。舉例：調(diào)用某個接口，接口有如下字段：partner、total_fee、desc、attach實際調(diào)用接口時，各字段的值：partner=1900000109，total_fee=1，desc=a&b，attach=，test=1正確的簽名原始串是：desc=a&b&partner=1900000109&test=1&total_fee=1常見的錯誤有：desc=a%26b&partner=1900000109&test=1&total_fee=1desc=a&b&partner=1900000109&total_fee=1attach=&desc=a&b&partner=1900000109&test=1&total_fee=1partner=1900000109&total_fee=1&desc=a&b&test=1注意：Wap支付接口中的返回結(jié)果參數(shù)列表（6.2.4）比較特殊，第2點不適合，即所有參數(shù)指的是文檔中描述該接口的參數(shù)。4.2 簽名算法目前暫只支持MD5簽名MD5簽名MD5 是一種摘要生成算法，通過在簽名原始串后加上商戶通信密鑰的內(nèi)容，進行MD5運算，形成的摘要字符串即為簽名結(jié)果。為了方便比較，簽名結(jié)果統(tǒng)一轉(zhuǎn)換為大寫字符。注意：簽名時將字符串轉(zhuǎn)化成字節(jié)流時指定的字符集input_charset一致。MD5簽名計算公式：sign = Md5(原字符串&key=商戶密鑰). toUpperCase如：簽名原始串是：input_charset=GBK&partner=1900000109&total_fee=1商戶密鑰是：8db4a013a8b515349c307f1e448ce836簽名的結(jié)果為：sign=md5(input_charset=GBK&partner=1900000109&total_fee=1&key=8934e7d15453e97507ef794cf7b0519d)= 8DB4A013A8B515349C307F1E448CE8365 補單機制對后臺通知交互模式，如果財付通收到商戶的應(yīng)答不是success或超時，財付通認為通知失敗，財付通會通過一定的策略（如30分鐘共8次）定期重新發(fā)起通知，盡可能提高通知的成功率，但財付通不保證通知最終能成功。由于存在重新發(fā)送后臺通知的情況，因此同樣的通知可能會多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復(fù)的通知。財付通推薦的做法是，當收到通知進行處理時，首先檢查對應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài)，判斷該通知是否已經(jīng)處理過，如果沒有處理過再進行處理，如果處理過直接返回success。在對業(yè)務(wù)數(shù)據(jù)進行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進行并發(fā)控制，以避免函數(shù)重入造成的數(shù)據(jù)混亂。6 接口6.1 初始化請求接口6.1.1 業(yè)務(wù)功能初始化wap請求，通過生成token_id來進行交互驗證。6.1.2 交互模式請求：頁面跳轉(zhuǎn)交互模式返回結(jié)果+通知：頁面跳轉(zhuǎn)交互模式+后臺通知交互模式6.1.3 請求參數(shù)列表請求url：https://wap.tenpay.com/cgi-bin/wappayv2.0/wappay_init.cgi通過get或post請求字段名 變量名 必填 類型 說明業(yè)務(wù)參數(shù)版本號 ver 是 String(8) 版本號，ver默認值是1.0，目前版本ver取值應(yīng)為2.0字符集 charset 是 String(8) 1 UTF-8, 2 GB2312， 默認為1銀行類型 bank_type 是 String(16) 銀行類型:財付通支付填0商品描述 desc 是 String(255) 商品描述，32個字符以內(nèi)買方財付通賬號 purchaser_id 否 String(20) 用戶(買方)的財付通帳戶(QQ )。若商戶沒有傳該參數(shù)，則在財付通支付頁面，買家需要輸入其財付通帳戶。商戶號 bargainor_id 是 String(10) 商戶號，由財付通統(tǒng)一分配的10位正整數(shù)(120XXXXXXX)號商戶訂單號 sp_billno 是 String(32) 商戶系統(tǒng)內(nèi)部的定單號，32個字符內(nèi)、可包含字母總金額 total_fee 是 Int 總金額，以分為單位，不允許包含任何字、符號幣種 fee_type 是 Int 現(xiàn)金支付幣種，目前只支持人民幣，默認值是1：人民幣通知地址 notify_url 是 String(255) 接收財付通通知的URL，需給絕對路徑，255字符內(nèi)格式如:http://wap.tenpay.com/tenpay.asp前臺地址 callback_url 是 String(255) 交易完成后跳轉(zhuǎn)的URL，需給絕對路徑，255字符內(nèi)格式如:http://wap.tenpay.com/tenpay.asp附加信息 attach 否 String(255) 商戶附加信息，可做擴展參數(shù)，255字符內(nèi)訂單生成時間 time_start 否 String(14) 訂單生成時間，格式為yyyymmddhhmmss，如2009年12月25日9點10分10秒表示為20091225091010。時區(qū)為GMT+8 beijing。該時間取自商戶服務(wù)器訂單超時時間 time_expire 否 String(14) 訂單失效時間，格式為yyyymmddhhmmss，如2009年12月27日9點10分10秒表示為20091227091010。時區(qū)為GMT+8 beijing。該時間取自商戶服務(wù)器簽名 sign 是 String(32) MD5簽名結(jié)果，詳見“第4章 MD5簽名規(guī)則”6.1.4 返回結(jié)果和通知參數(shù)列表數(shù)據(jù)按XML的格式實時返回字段名 變量名 必填 類型 說明業(yè)務(wù)參數(shù)動態(tài)口令 token_id 是 String(64) 財付通生成的token_id。成功示例：<?xml version="1.0" encoding="GB2312" ?><root><token_id>20081113f9d49c20e8e5c8e40b6107ec42259e41</token_id></root>出錯示例：<?xml version="1.0" encoding="GB2312" ?><root><err_info>錯誤信息</err_info></root>6.2 Wap支付接口6.2.1 業(yè)務(wù)功能用戶通過Wap支付接口完成訂單支付。6.2.2 交互模式請求：頁面跳轉(zhuǎn)交互模式返回結(jié)果：頁面跳轉(zhuǎn)交互模式通知：后臺通知交互模式6.2.3 請求參數(shù)列表請求url：https://wap.tenpay.com/cgi-bin/wappayv2.0/wappay_gate.cgi通過get或post請求字段名 變量名 必填 類型 說明業(yè)務(wù)參數(shù)動態(tài)口令 token_id 是 String(64) 財付通生成的token_id。6.2.4 返回結(jié)果參數(shù)列表頁面返回通過請求中的callback_url進行，采用get或post字段名 變量名 必填 類型 說明業(yè)務(wù)參數(shù)返回狀態(tài)碼 ver 是 String(8) 版本號，ver默認值是1.0。目前版本ver取值應(yīng)為2.0字符集 charset 是 String(8) 字符編碼，取值：GBK、UTF-8，默認：GBK。支付結(jié)果 pay_result 是 Int 支付結(jié)果：0—成功；其它—失敗財付通訂單號 transaction_id 是 String(28) 財付通交易號，28位長的數(shù)值，其中前10位為商戶號，之后8位為訂單產(chǎn)生的日期，如20090415，最后10位是流水號。商戶訂單號 sp_billno 是 String(32) 商戶系統(tǒng)內(nèi)部的定單號，32個字符內(nèi)、可包含字母總金額 total_fee 是 Int 總金額，以分為單位，不允許包含任何字、符號幣種 fee_type 是 Int 現(xiàn)金支付幣種，1-人民幣商戶號 bargainor_id 是 String(10) 賣方賬號（商戶spid）附加信息 attach 否 String(255) 商家數(shù)據(jù)包，原樣返回簽名 sign 是 String(32) MD5簽名結(jié)果只對通知返回的協(xié)議參數(shù)進行簽名。6.2.5 通知結(jié)果參數(shù)列表后臺通知通過請求中的notify_url進行，采用get或post字段名 變量名 必填 類型 說明業(yè)務(wù)參數(shù)版本號 ver 是 String(8) 版本號，ver默認值是1.0。目前版本ver取值應(yīng)為2.0字符集 charset 是 String(8) 字符編碼，取值：GB2312、UTF-8，默認：GB2312。支付結(jié)果 pay_result 是 Int 支付結(jié)果：0—成功；其它—失敗支付結(jié)果信息 pay_info 否 String(64) 支付結(jié)果信息，支付成功時為空財付通訂單號 transaction_id 是 String(28) 財付通交易號，28位長的數(shù)值，其中前10位為商戶號，之后8位為訂單產(chǎn)生的日期，如20090415，最后10位是流水號。商戶訂單號 sp_billno 是 String(32) 商戶系統(tǒng)內(nèi)部的定單號，32個字符內(nèi)、可包含字母總金額 total_fee 是 Int 總金額，以分為單位，不允許包含任何字、符號幣種 fee_type 是 Int 現(xiàn)金支付幣種，1-人民幣商戶號 bargainor_id 是 String(10) 賣方賬號（商戶spid）附加信息 attach 否 String(255) 商家數(shù)據(jù)包，原樣返回簽名 sign 是 String(32) MD5簽名結(jié)果付款銀行 bank_type 是 String(16) 銀行類型銀行訂單號 bank_billno 否 String(32) 銀行訂單號，若為財付通余額支付則為空支付完成時間 time_end 是 String(14) 支付完成時間，格式為yyyyMMddhhmmss，如2009年12月27日9點10分10秒表示為20091227091010。時區(qū)為GMT+8 beijing。該時間取自財付通服務(wù)器買家別名 purchase_alias 否 String(64) 對應(yīng)買家賬號的一個加密串6.2.6 后臺通知結(jié)果反饋財付通后臺通過notify_url通知商戶，商戶做業(yè)務(wù)處理后，需要以字符串的形式反饋處理結(jié)果，內(nèi)容如下：返回結(jié)果 結(jié)果說明success 處理成功，財付通系統(tǒng)收到此結(jié)果后不再進行后續(xù)通知fail或其它字符 處理不成功，財付通收到此結(jié)果或者沒有收到任何結(jié)果，系統(tǒng)通過補單機制（詳見第5節(jié)）再次通知6.3 訂單查詢接口6.3.1 業(yè)務(wù)功能根據(jù)商戶訂單號或者財付通訂單號查詢財付通側(cè)記錄的具體訂單信息。6.3.2 交互模式后臺系統(tǒng)調(diào)用交互模式6.3.3 請求參數(shù)列表請求url：http://wap.tenpay.com/cgi-bin/wapmainv2.0/wm_query_order.cgi通過get或post請求字段名 變量名 必填 類型 說明業(yè)務(wù)參數(shù)版本號 ver 是 String(8) 版本號，ver默認值是1.0。目前版本ver取值應(yīng)為2.0商戶號 bargainor_id 是 String(10) 賣方賬號（商戶spid）商戶訂單號 sp_billno 否 String(32) 商戶系統(tǒng)內(nèi)部的訂單號， sp_billno和transaction_id至少一個必填，同時存在時transaction_id優(yōu)先財付通訂單號 transaction_id 否 String(28) 財付通交易號， sp_billno和transaction_id至少一個必填，同時存在時transaction_id優(yōu)先。附加信息 attach 否 String(255) 商家數(shù)據(jù)包，原樣返回字符集 charset 是 String(8) 字符編碼，取值：GB2312、UTF-8，默認：GB2312。簽名 sign 是 String(32) MD5簽名結(jié)果6.3.4 應(yīng)答參數(shù)列表數(shù)據(jù)按XML的格式實時返回字段名 變量名 必填 類型 說明業(yè)務(wù)參數(shù)版本號 ver 是 String(8) 版本號，ver默認值是1.0。目前版本ver取值應(yīng)為2.0字符集 charset 是 String(8) 字符編碼，取值：GB2312、UTF-8，默認：GB2312。支付結(jié)果 pay_result 是 Int 支付結(jié)果：0—成功；其它—失敗支付結(jié)果信息 pay_info 否 String(64) 支付結(jié)果信息，支付成功時為空財付通訂單號 transaction_id 是 String(28) 財付通交易號，28位長的數(shù)值，其中前10位為商戶號，之后8位為訂單產(chǎn)生的日期，如20090415，最后10位是流水號。商戶訂單號 sp_billno 是 String(32) 商戶系統(tǒng)內(nèi)部的定單號，32個字符內(nèi)、可包含字母總金額 total_fee 是 Int 總金額，以分為單位，不允許包含任何字、符號幣種 fee_type 是 Int 現(xiàn)金支付幣種，1-人民幣商戶號 bargainor_id 是 String(10) 賣方賬號（商戶spid）附加信息 attach 否 String(255) 商家數(shù)據(jù)包，原樣返回簽名 sign 是 String(32) MD5簽名結(jié)果付款銀行 bank_type 是 String(16) 銀行類型銀行訂單號 bank_billno 否 String(32) 銀行訂單號，若為財付通余額支付則為空支付完成時間 time_end 是 String(14) 支付完成時間，格式為yyyyMMddhhmmss，如2009年12月27日9點10分10秒表示為20091227091010。時區(qū)為GMT+8 beijing。該時間取自財付通服務(wù)器買家別名 purchase_alias 否 String(64) 對應(yīng)買家賬號的一個加密串7 注意事項1、 所有涉及到金額的單位都是分，最小的單位是1分，不能有小數(shù)出現(xiàn)2、 notify_url是財付通服務(wù)器從后臺直接發(fā)起請求到商戶服務(wù)器，商戶處理時不能檢查用戶的cookie或session；商戶更新DB等發(fā)貨流程需要完整在notify_url完成，以確保掉單時，財付通補單能成功補上3、 notify_url有可能重復(fù)通知，商戶需要做去重處理，避免多次發(fā)貨4、 notify_url收到的通知，商戶處理成功或檢查訂單已經(jīng)處理，需要返回處理成功的標志“success”，以告知財付通不再通知5、 notify_id的有效期是2分鐘，請商戶收到通知后盡快發(fā)起查詢世聯(lián)翻譯-讓世界自由溝通！專業(yè)的全球語言翻譯供應(yīng)商，上海翻譯公司專業(yè)品牌。絲路沿線56種語言一站式翻譯與技術(shù)解決方案，專業(yè)英語翻譯、日語翻譯等文檔翻譯、同傳口譯、視頻翻譯、出國外派服務(wù)，加速您的全球交付。 世聯(lián)翻譯公司在北京、上海、深圳等國際交往城市設(shè)有翻譯基地，業(yè)務(wù)覆蓋全國城市。每天有近百萬字節(jié)的信息和貿(mào)易通過世聯(lián)走向全球！積累了大量政商用戶數(shù)據(jù)，翻譯人才庫數(shù)據(jù)，多語種語料庫大數(shù)據(jù)。世聯(lián)品牌和服務(wù)品質(zhì)已得到政務(wù)防務(wù)和國際組織、跨國公司和大中型企業(yè)等近萬用戶的認可。
