Tencent財(cái)付通直通車接口協(xié)議

1、亠厶 財(cái)付通直通車協(xié)議說(shuō)明書深圳市騰訊計(jì)算機(jī)系統(tǒng)有限公司文檔歷史修訂日期修訂內(nèi)容修訂版本修訂人2008-05-08創(chuàng)建0.1tencent2008-06-26添加注意事項(xiàng)().2tcnccnt2008-07-18添加常見錯(cuò)誤信息及相關(guān)錯(cuò)誤碼().3tencent2009-03-13增加游戲點(diǎn)券接入接口說(shuō)明0.4tencent2011-12-01將銷售產(chǎn)品列表單獨(dú)列出0.9tencent目錄1引言11編寫目的31-2.背景31.3. 定義31.4. 參考資料32. 協(xié)議概述42.1. 協(xié)議列表42.2. 協(xié)議的交互邏輯43. 銷售協(xié)議43.1. 協(xié)議說(shuō)明43.1.1. 標(biāo)準(zhǔn)前端接口一43.12

2、標(biāo)準(zhǔn)前端接口二51.0.0. 標(biāo)準(zhǔn)前端接口三61) 調(diào)用說(shuō)明71. 參數(shù)說(shuō)明7322.銷售業(yè)務(wù)列表83.3.返回結(jié)果說(shuō)明114. 注意事項(xiàng)及限制115. 接入常見問(wèn)題116.常見的錯(cuò)誤碼1.引言1.1編寫目的本文檔說(shuō)明了財(cái)付通直通車的接口協(xié)議等，供使用該接口的經(jīng)銷商和本項(xiàng)目的后續(xù)開發(fā) 維護(hù)人員使用。背景由于目前一些合作網(wǎng)站在銷售騰訊的會(huì)員，紅鉆，黃鉆,q幣等產(chǎn)站，為了提高用戶感和實(shí) 時(shí)性，需要實(shí)現(xiàn)自動(dòng)充值、開通服務(wù)等功能。為了滿足這些經(jīng)銷商的需求，同時(shí)保證交易的 安全性，提出了財(cái)付通直通車的概念。定義財(cái)付通直通車：在財(cái)付通系統(tǒng)上擴(kuò)展出來(lái)的，滿足冇自己銷售平臺(tái)，盂要實(shí)時(shí)實(shí)現(xiàn)q幣 充值、服務(wù)開通的

3、要求的經(jīng)銷商的快速通道。商戶號(hào)：經(jīng)銷商注冊(cè)的直通年帳號(hào)，冃前支持qq號(hào)碼，同時(shí)必須是財(cái)付通注冊(cè)用戶.14參考資料協(xié)議概述21協(xié)議列表協(xié)議名稱說(shuō)明銷售協(xié)議銷售q幣和開通服務(wù)的協(xié)議2.2 協(xié)議的交互邏輯經(jīng)銷商tencent銷售請(qǐng)求i銷售結(jié)果銷售協(xié)議協(xié)議說(shuō)明協(xié)議采用http協(xié)議，經(jīng)銷商將請(qǐng)求報(bào)文get或post到騰訊的財(cái)付通玄通車站點(diǎn)的80端i i： 80標(biāo)準(zhǔn)前端接口一調(diào)用url為：http:/bank.qq.coni/cgi-bin/pay/bank_ztc_entry.cgi?servicecode=*&qquin=*&ztcqquin=*& buycount=*&

4、;comm 1 =*&comm2=*&sign=*使用范圍：q幣、q點(diǎn)、qq會(huì)員、紅鉆、藍(lán)鉆、綠鉆等包刀類服務(wù)和qq游戲歡樂(lè)大禮包。具體請(qǐng)杳閱木文檔銷售列表的章節(jié)。保留字段的特殊說(shuō)明：字段comml, comm2為保留字段，均填整數(shù)1即可。3.1.2.標(biāo)準(zhǔn)前端接口二調(diào)用uf1為： quin=*&ztcqquin二和 *& buycount=*&comm 1 =*&comm2=*&sign=*使用范圍：游戲點(diǎn)券類業(yè)務(wù)，包括按用八充值、按大區(qū)充值和按角色充值。具體請(qǐng)查閱本文檔銷售列表的章節(jié)。保留字段的特殊說(shuō)明：點(diǎn)券類業(yè)務(wù)分為三大類，每類的保留

5、字段需要填寫內(nèi)容不同。按用戶充值即該游戲不分大區(qū)，此時(shí)comml,comm2均填整數(shù)1。按大區(qū)充值此時(shí)comml填用戶所在人區(qū)的編號(hào)，comm2填整數(shù)1。按角色充值即對(duì)特定大區(qū)里面的指定角色充值。此吋comml填用戶所在的大區(qū)編號(hào)，comm2為標(biāo)準(zhǔn)接口三(見下一節(jié)) 所返回的信息。獲取游戲大區(qū)編號(hào)游戲人區(qū)選擇有相應(yīng)代碼捉供接口來(lái)渲染htmlselect組件，每個(gè)游戲會(huì)有各自的serverselect對(duì)象，比如 cf為cfscrvcrsclcct,下面#gamcscrvcr的值就是大區(qū)編號(hào)。以cf點(diǎn)券為例：先載入通用代碼：hmp:/ base.js (gbk 編碼)，再載入 cf 對(duì)應(yīng)的對(duì)彖。在

6、頁(yè)面提供2個(gè)htmlselect組件<select id="areaserver"x/select> v!-人區(qū)選框><select id="gameserver"></select> v!-服務(wù)器選科e ->js調(diào)用如下cfserverselect.showzone( doucment.getelementbyld('areaserver'),doucment.getelementbyld(gameserver) , t:"選擇大區(qū)",v:"",op

7、t_data_array:t:”選擇服務(wù)器”,v:”);該對(duì)象提供3個(gè)渲染接口：(各游戲提供的接口屮，可選參數(shù)的順序可能有不同，詳細(xì)請(qǐng)杳看代碼)serverselect.create( select_aitay, f ext_opt_array, opt_array )serverselect.showzone( select_array, ext_opt_array, opt_array )serverselect.showzone2( select_array, ext_ opt_array, opt_array )參數(shù)說(shuō)明：select_array:必須 數(shù)組 數(shù)組元素為目標(biāo)select

8、元素的引用，opt_array：可選數(shù)組大區(qū)數(shù)據(jù)數(shù)組(一般此參數(shù)不需填寫或填null)ext_opt_array： nj'選 數(shù)組 對(duì) opt_array 的擴(kuò)展三個(gè)接口均是將大區(qū)數(shù)據(jù)渲染金給定的htmlselect組件中，其中：create方法不區(qū)別已停機(jī)的服務(wù)器，showzone方法會(huì)在已停機(jī)的服務(wù)器名字示顯示（停機(jī)）字樣，showzone2方法會(huì)將停機(jī)服務(wù)器隱藏。按角色充值示例qq121619596對(duì)“電信體驗(yàn)服”人區(qū)（編號(hào)為3）也色充值。先調(diào)用標(biāo)準(zhǔn)接口三查詢用戶所有角色。請(qǐng)求：hmp:/ ztc iole.cgi?servicecodc二-wzwd0&0ouin二 12

9、1619596&ztcoouin二 12345678&buycount= 1000&commt=3&comm2= 1 &sign=abcdefg應(yīng)答：<?xml version二"1. 0" encoding二"gb2312"?><root><sta.tus>0</status><msg>查詢成功</msg><rolelist><role name二虛空行者 data=，z6jma56m66kgm61cfj j!2mdawnd

10、qxma. /z /></rolelist></root>用戶選擇對(duì)“虛空行者”充值。此時(shí)調(diào)用標(biāo)準(zhǔn)接口二充值。請(qǐng)求：http:/bank. qq. com/cgi-bin/pay/bank ztx entry dq. cgi?servicec（）de二-wzwdq&qquin=121619596&ztcqqui n二 12345678&buycount二 1000&commt=3&conim2=6jma56ni66kgm61cfj j 12mdawdqxma. &s i gn二abedofg3.1.3.標(biāo)準(zhǔn)前端接口三

11、調(diào)用ufi為：& buycount=*&comm 1 =*&comm2=*&sign=*使用范圍：該接口用于查詢指定大區(qū)內(nèi)的所有角色信息，目前僅有【萬(wàn)王之王】一款游戲。具休請(qǐng)查閱本文檔銷售列表的章節(jié)。保留字段的特殊說(shuō)明：comm 1填用戶所在大區(qū)的編號(hào)，comm2填整數(shù)1。獲取游戲大區(qū)編號(hào)同上一節(jié)標(biāo)準(zhǔn)接口二返回結(jié)果示例<?xml version="1. 0" encoding二"gb2312"?><root><status>0</status><msg>查詢成功&

12、lt;/msg><rolelist><rolo name="虛空行者"data=，z6jma56m66kgm61cfj ji2mdawndqxma./></rolelist></root>rolelist即是用戶在指定大區(qū)內(nèi)的所有角色列表。role段是每個(gè)角色信息：name是gbk編碼的角色名稱；data是該角色充值所需要的附加信息。3.2.調(diào)用說(shuō)明3.2.1.參數(shù)說(shuō)明輸入?yún)?shù)數(shù)據(jù)類型說(shuō)明是否必填servicecodevarchar(20)產(chǎn)品類型,如q幣yqquinvarchar(lo)用戶帳號(hào)(用戶qq號(hào))yztcq

13、quinvarchar(lo)財(cái)付通帳號(hào)ybuycountint充值數(shù)址ycommlvarchar(255)交易備注一，缺省為1ycomm2varchar(255)交易備注二，缺省為1ysignchar(32)數(shù)字簽名，字母是小寫y調(diào)用說(shuō)明：所有字段中不能包含“&”和參數(shù)servicecode：業(yè)務(wù)代碼，表示產(chǎn)品類型參數(shù)qquim用戶帳號(hào)，及收貨號(hào)碼，目前都是表示qq號(hào)碼參數(shù)ztcqquim財(cái)付通帳號(hào)，及支付號(hào)碼，冃前都是表示qq號(hào)碼參數(shù)buycount：充值數(shù)量，它的意義和取值范servicecode產(chǎn)品類型有關(guān)參數(shù)comml,comm2每個(gè)標(biāo)準(zhǔn)接口含義不同，請(qǐng)杳看每個(gè)標(biāo)準(zhǔn)接口的詳細(xì)

14、說(shuō)明。參數(shù)sign：為按順序?qū)灰仔畔⒌膍d5加密簽名的32位字符串。例如：sign=md5(servicecode=*&qquin=*&ztcqquin=*&buycoun匸*&comml=*&comm2=*llenc _key),其中enc_key為注冊(cè)財(cái)付通直通車時(shí)生成的key簽名舉例：20030325的-筆交易，99999需要給用八123456充值1q幣，需要從socket讀取返回結(jié)果，雙方約定key 為!#$%a&123abcfg,則簽名算法為：sign =md5("servicecode=qqacct_save&qq

15、uin= 123456&z(cqquin=99999&buycoim匸 1&comm 1 = 1 &comm2= 111! #$%八& 123 abcfg”)最終的請(qǐng)求串為(假設(shè)最終的md5加密結(jié)果是1 e 1 cf8d9d57d48b96ad 10bc2beead6ac)http:/bank.qq.coni/cgi-bin/pay/bank_ztc_entry.cgi?servicecode=qqacct_save&qquin= 123456&ztcqquin=99999&buycount= 1 &comm 1 = 1

16、& comm2= 1 & sign= 1 e 1 cf8d9d57d48b96ad 10bc2beead6ac3.2.2.銷售業(yè)務(wù)列表名稱業(yè)務(wù)代碼購(gòu)買數(shù)量接口備注q幣qqacct save1, 1000接口一q點(diǎn) qqpoint10, 1000()接口一購(gòu)買數(shù)量必須是10的倍數(shù)qq會(huì)員ltmclub1,24接口一藍(lán)鉆xxqgame1,24接口一紅鉆xxqqf1,24接口一黃鉆xxjzgw1,24接口一綠鉆xxzxyy1,24接口一粉鉆petvip1,24接口一qq堂紫鉆xxqqt1,24接口一飛車紫鉆qqfczz1, 24接口一飛車點(diǎn)券qqkdc100, 100000接口二按人

17、區(qū)充值，購(gòu)買數(shù)量必須是100的倍數(shù)qq音速qqr2by1,24接口一512m網(wǎng)盤qtd512m1,24接口一ava點(diǎn)券-avad1000, 100000接口二按大區(qū)充值，購(gòu)買數(shù)量必需為100的倍數(shù)ava會(huì)員avavip1, 24接口一qq游戲歡 樂(lè)大禮包xxyxlb1, 24接口一炫舞紫鉆qqxwzz1,24接口一炫舞點(diǎn)券 xwdql500, 100000j接口二按大區(qū)充值，購(gòu)買數(shù)量必需為100的借數(shù)cf會(huì)員cfclub1,24接口一cf點(diǎn)券-cfdq1000, 100000接口二按大區(qū)充值，購(gòu)買數(shù)量必需為100的倍數(shù)dnf黑鉆dnfhz1,24接口一dnf點(diǎn)券-dnfdq100, 10000

18、0接口二按用戶充值，購(gòu)買數(shù)最必需為100的倍數(shù)大明龍權(quán) 點(diǎn)券dmlq100, 100000接口二按大區(qū)充值，購(gòu)買數(shù)量必須是100的倍數(shù)qq仙俠傳 元寶qqxxyb100, 100()00接口二按用戶充值，購(gòu)買數(shù)量必需為100的倍數(shù)洛克王國(guó)viplkwg1,24接口一lol點(diǎn)券loldql100, 100000j接口二按大區(qū)充值，購(gòu)買數(shù)量必需為100的借數(shù)七雄爭(zhēng)霸 qxzb10, 1 ()()()()()接口二按人區(qū)充值，購(gòu)買數(shù)量必須是10的倍數(shù)qq西游vipxyvip1,24接口一qqiffi游元 寶-tmxy100, 100000接口二按川戶充值，購(gòu)買數(shù)量必須是100的倍數(shù)萬(wàn)王z王 點(diǎn)券-w

19、zwdq100, 100()00接口二按角色充值，購(gòu)買數(shù)量必須是100的倍數(shù)九界點(diǎn)券-jjdq10, 100000接口二按人區(qū)充值，購(gòu)買數(shù)最必須是10的倍數(shù)楚河漢界 黃金-chhj10, 100000接口二按大區(qū)充值，購(gòu)買數(shù)量必須是10的倍數(shù)超級(jí)qqxxsqqm1,24接口一魔鉆mzyff1,24接口一尋仙vipxxvip1,24接口一nba會(huì)員nbavip1,24接口一漫畫vipmhvip1,24接口一讀書vipqqbookby1,24接口一尋仙仙玉 xxxy100, 10000接口二按用戶充值，購(gòu)買數(shù)量必須是100的倍數(shù)qq三國(guó)點(diǎn)-qqsgpay10, 10000接口二按用戶充值，購(gòu)買數(shù)最

20、必須是10的倍數(shù)q寵大樂(lè) 斗斗豆-qcdd100, 100000接口二按川戶充值，購(gòu)買數(shù)量必須是100的倍數(shù)天堂島 海貝-hbttd10, 1()000接口二按用戶充值，購(gòu)買數(shù)量必須是10的倍數(shù)摩登城市 云幣-pcqqc10, 10000接口二按用戶充值，購(gòu)買數(shù)最必須是10的倍數(shù)寶石總動(dòng) 員鉆石q qbslio, 10000j接口二按川戶充值，購(gòu)買數(shù)量必須是10的倍數(shù)qq仙境仙 點(diǎn) qqxjdj100, 100000接口二按用戶充值，購(gòu)買數(shù)量必須是100的倍數(shù)qq華夏點(diǎn) 券-hxfr100, 24000接口二按川戶充值，購(gòu)買數(shù)量必須是100的倍數(shù)綠色征途 點(diǎn)券-lszt100, 100000接

21、口二按用八充值，購(gòu)買數(shù)量必須是100的倍數(shù)笫九大陸 點(diǎn)券-cjdq100, 100000接口二按用戶充值，購(gòu)買數(shù)量必須是100的倍數(shù)qq特工點(diǎn) 券-qqtgsn100, 100000接口二按用戶充值，購(gòu)買數(shù)量必須是100的倍數(shù)qq水滸銀 票 qqshdq10, 1()000接口二按用戶充值，購(gòu)買數(shù)量必須是10的倍數(shù)魔幻大陸 元寶-mhdl10, 10000接口二按人區(qū)充值，購(gòu)買數(shù)量必須是10的倍數(shù)絲路英雄 幣-slyx10, 10000接口二按大區(qū)充值，購(gòu)買數(shù)量必須是10的倍數(shù)烽火戰(zhàn)國(guó) 點(diǎn)券 fhzg10, 10000接口二按大區(qū)充值，購(gòu)買數(shù)量必須是10的倍數(shù)超級(jí)明星 金幣-cjmx10, 1

22、0000接口二按人區(qū)充值，購(gòu)買數(shù)量必須是1()的倍數(shù)王朝霸域 點(diǎn)券 wcbydq10, 10000接口二按人區(qū)充值，購(gòu)買數(shù)量必須是10的倍數(shù)qq九仙元 寶-qqjx100, 100000接口二按大區(qū)充值，購(gòu)買數(shù)量必須是100的倍數(shù)江湖笑金幣-xjhx10, 10000接口二按人區(qū)充值，購(gòu)買數(shù)量必須是10的倍數(shù)星魂幣-qqxhcs10, 10000接口二按人區(qū)充值，購(gòu)買數(shù)最必須是10的倍數(shù)御龍?jiān)谔?金子-ylzt100, 100000接口二按大區(qū)充值，購(gòu)買數(shù)量必須是100的倍數(shù)幻想世界 金子 qqhxsj100, 100()00接口二按大區(qū)充值，購(gòu)買數(shù)量必須是100的倍數(shù)自由幻想-ffowy10

23、0, 100000接口二按人區(qū)充值，購(gòu)買數(shù)最必須是100的倍數(shù)彩玉藍(lán)鉆豪華 版xxzxgp1,24接口一鉆皇qqpacket1,24接口一黃鉆豪華 版xxjzghh1,24接口一情侶紅鉆qlhzhh1,24接口一斗戰(zhàn)神點(diǎn) 券 dzsdq100, 100000接口二按用戶充值，購(gòu)買數(shù)量必須是100的倍數(shù)超級(jí)會(huì)員cjclubt1,24接口一相關(guān)游戲大區(qū)選擇的js代碼列表如下：(均為gbk編碼)公用代碼： 盂要在以下代碼z前載入qq 飛車點(diǎn)券：hltpw/sdcf 點(diǎn)、券:hmp:/cfqqcom/comm-h(clocs/js/game arca/cf server selects3七雄爭(zhēng)霸元寶：

24、hmd：7qcicom/comm-htdocs/is/game_area/7_server_seiectjs4人 明龍權(quán)點(diǎn)券：5 qq 炫舞 點(diǎn)券：http:/x5qqcom/c()mmhtdocs/js/gamc_arca/x5_scrvcr_sclcctjs6. ava 點(diǎn)券：hhd：avaqqcom/commhtdocs/js/g3me_area/ava_server_selec(js7英雄聯(lián)盟點(diǎn)券:hup:/lolqqcom/commh(docs“s/game arca/lol server sclec匸is& qq 西游元寶：htb：qqxyqqcom/comnvhtdocs

25、“s/gamc_arca/ciqxy_scrvcrsclccl.js9萬(wàn)王之王 3 點(diǎn)券：http:/3qqcom/comm-htdocs/is/game_area/3_server_selectjs10九界點(diǎn)券：11 楚河漢界黃金：hg:chciqcom/comm-h(docs/is/g3me_area/ch_server_selectjs12魔幻人陸元宋：13絲路英雄幣:14烽火戰(zhàn)國(guó)點(diǎn)券：15超級(jí) 明星金幣：http:sqqcom/comm-htdocs"s/gameaea/s_servejselect.js16王朝祈域點(diǎn)券：h(td：w3ng.qqcom/commhtdocs/

26、js/game_area/wcby_server_select.js17.qq 九仙元宋：hmp:/9qqcom/comin-htdocs(is/game area/9 server_selectjs8江湖笑金 幣：hhd：/“(kbcom/comm-htdocs"s/game_area“_server_selectjs19星魂 幣：http:/xqqcom/comm-htdocs(is/game_area/x_server_selectis20.fill龍?jiān)谌私鹆耍?http:ylqqc()m/commhtcl()cs4s/game_area/ylserver_selectjs21

27、 幺j想世界金子：22.自 由幻想彩玉：33返回結(jié)果說(shuō)明返回結(jié)果是xml字符串<?xml version="1.0" encoding二"gb2312" ?><root>vstatus> 狀 態(tài) v/status><msg>結(jié)果說(shuō)明</msg><serialno> 訂單號(hào) </serialno></root>參數(shù)說(shuō)明：status :=0,表示成功，二具它，表示失敗特別說(shuō)明：當(dāng)status為-1009w,表示因網(wǎng)絡(luò)波動(dòng)，造成交易處理異常，請(qǐng)商戶登陸直通車網(wǎng)站在

28、當(dāng) 日查詢中根據(jù)收貨號(hào)碼查詢訂單是否成功，如查詢?yōu)榭沾碛唵问?，或?lián)系財(cái)付通客服msg :結(jié)果說(shuō)明，可以查看成功消息或者失敗提示serialno :訂單號(hào)，是直通車產(chǎn)生的唯一序列號(hào)，刊以根據(jù)此訂單號(hào)到http:/bank.qq.coni/ztcv2查詢4 注意事項(xiàng)及限制系統(tǒng)對(duì)同一ip的充值請(qǐng)求頻次限制在20筆交易請(qǐng)求每20秒。如果商戶的交易量超過(guò)該頻次限制的話，切 記不要把交易請(qǐng)求即調(diào)用直通車url的銷售請(qǐng)求通過(guò)同一 ip發(fā)送。系統(tǒng)對(duì)提交的充值請(qǐng)求只進(jìn)行單次處理，如果交易過(guò)程出現(xiàn)錯(cuò)誤，該筆交易被視為無(wú)效請(qǐng)求，系統(tǒng)不會(huì) 再繼續(xù)處理該交易請(qǐng)求（如已對(duì)商戶財(cái)付通進(jìn)行扌ii款的，系統(tǒng)會(huì)白動(dòng)在當(dāng)li或次口進(jìn)行全額退款）。商戶需 根據(jù)自己的實(shí)際情況確定是否再次發(fā)起充值請(qǐng)求。5 接入常見問(wèn)題返回錯(cuò)誤碼-2002,錯(cuò)誤信息“ip產(chǎn).*.