上海翻譯公司完成電子系統(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時使用

賬戶 [email protected]

財付通賬戶號，目前支持兩種格式：qq號碼和email賬戶

金額 100000 金額，默認(rèn)為RMB，以分為單位。1000表示RMB10.00

2 方案概述

2.1 行業(yè)背景

在電子商務(wù)中，商家、買家、中間服務(wù)方是交易活動中的三個環(huán)節(jié)。買家選購商品下發(fā)訂單，商家確認(rèn)訂單，買家通過中間服務(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é)果。

財付通確認(rèn)交易完成并回跳至商戶的callback_url。

2.4 頁面回跳callback_url

callback_url應(yīng)為WAP頁面，給買家展示支付結(jié)果。

2.5 結(jié)果通知notify_url

notify_url接收財付通從后臺發(fā)出的支付結(jié)果通知。

在此通知接口模式中，商戶需要確保notify_url穩(wěn)定可靠。該notify_url完成接收財付通發(fā)送的支付結(jié)果信息，交易結(jié)果信息將以GET方式傳遞至商戶。財付通只將支付成功的訂單進行返回。

3 數(shù)據(jù)格式

3.1 GET或POST

采用HTTP標(biāo)準(zhǔn)的GET或POST協(xié)議，為了保證接收方接收數(shù)據(jù)正確，傳遞的參數(shù)如果存在特殊字符（如&、=等）需要進行URL Encode。

GET或POST一般用于頁面跳轉(zhuǎn)交互模式的請求和通知、后臺系統(tǒng)調(diào)用模式的請求、后臺通知模式的請求。

3.2 XML數(shù)據(jù)格式

采用標(biāo)準(zhǔn)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=1

desc=a&b&partner=1900000109&total_fee=1

attach=&desc=a&b&partner=1900000109&test=1&total_fee=1

partner=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)= 8DB4A013A8B515349C307F1E448CE836

5 補單機制

對后臺通知交互模式，如果財付通收到商戶的應(yīng)答不是success或超時，財付通認(rèn)為通知失敗，財付通會通過一定的策略（如30分鐘共8次）定期重新發(fā)起通知，盡可能提高通知的成功率，但財付通不保證通知最終能成功。

由于存在重新發(fā)送后臺通知的情況，因此同樣的通知可能會多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復(fù)的通知。

財付通推薦的做法是，當(dāng)收到通知進行處理時，首先檢查對應(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默認(rèn)值是1.0，目前版本ver取值應(yīng)為2.0

字符集 charset 是 String(8) 1 UTF-8, 2 GB2312， 默認(rèn)為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)金支付幣種，目前只支持人民幣，默認(rè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默認(rèn)值是1.0。目前版本ver取值應(yīng)為2.0

字符集 charset 是 String(8) 字符編碼，取值：GBK、UTF-8，默認(rèn)：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默認(rèn)值是1.0。目前版本ver取值應(yīng)為2.0

字符集 charset 是 String(8) 字符編碼，取值：GB2312、UTF-8，默認(rèn)：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默認(rèn)值是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，默認(rèn)：GB2312。

簽名 sign 是 String(32) MD5簽名結(jié)果

6.3.4 應(yīng)答參數(shù)列表

數(shù)據(jù)按XML的格式實時返回

字段名 變量名 必填 類型 說明

業(yè)務(wù)參數(shù)

版本號 ver 是 String(8) 版本號，ver默認(rèn)值是1.0。目前版本ver取值應(yīng)為2.0

字符集 charset 是 String(8) 字符編碼，取值：GB2312、UTF-8，默認(rèn)：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)處理，需要返回處理成功的標(biāo)志“success”，以告知財付通不再通知

5、 notify_id的有效期是2分鐘，請商戶收到通知后盡快發(fā)起查詢