直通车2.0接口协议.doc

财付通直通车财付通直通车 协议说明书协议说明书 深圳市腾讯计算机系统有限公司 Tencent财付通直通车接口协议 0 文档历史文档历史 修订日期修订日期修订内容修订内容修订版本修订版本修订人修订人 2008-05-08创建0.1Tencent 2008-06-26添加注意事项0.2Tencent 2008-07-18添加常见错误信息及相关错误码0.3Tencent 2010-03-10去掉已下线产品：交友、网盘0.4Tencent Tencent财付通直通车接口协议 1 目录目录 1. 引言.3 1.1. 编写目的3 1.2. 背景3 1.3. 定义3 1.4. 参考资料3 2. 协议概述.4 2.1. 协议列表4 2.2. 协议的交互逻辑4 3. 销售协议.4 3.1. 协议说明4 3.2. 调用说明4 3.3. 返回结果说明6 4. 注意事项及限制.6 5. 接入常见问题.6 6. 常用的错误码.6 Tencent财付通直通车接口协议 2 1. 引言引言 1.1.编写目的编写目的 本文档说明了财付通直通车的接口协议等，供使用该接口的经销商和本项目的后续开 发维护人员使用。 1.2.背景背景 由于目前一些合作网站在销售腾讯的会员,红钻,黄钻,Q币等产品，为了提高用户感和实 时性，需要实现自动充值、开通服务等功能。为了满足这些经销商的需求，同时保证交易 的安全性，提出了财付通直通车的概念。 1.3.定义定义 财付通直通车：在财付通系统上扩展出来的，满足有自己销售平台，需要实时实现Q 币 充值、服务开通的要求的经销商的快速通道。 商业号：腾讯分配给经销商的帐号. 1.4.参考资料参考资料 Tencent财付通直通车接口协议 3 2. 协议概述协议概述 2.1.协议列表协议列表 协议名称协议名称说明说明 销售协议销售Q币和开通服务的协议 2.2.协议的交互逻辑协议的交互逻辑 3. 销售协议销售协议 3.1.协议说明协议说明 协议采用HTTP协议，经销商将请求报文post到腾讯的财付通直通车站点的80端口： 80 调用url为： /cgi-bin/pay/bank_ztc_entry.cgi?ServiceCode=*&QQuin=*&ZtcQQuin=* &BuyCount=*&comm1=*&comm2=*&sign=* 3.2.调用说明调用说明 参数说明：参数说明： 输入参数输入参数数据类型数据类型说明说明是否必填是否必填 ServiceCodevarchar(20)产品类型，如Q币Y QQuinvarchar(10)用户帐号(用户QQ号)Y ZtcQQuinvarchar(10)财付通帐号Y BuyCountInt充值数量Y 经销商TENCENT 销售请求 销售结果 Tencent财付通直通车接口协议 4 comm1varchar(255) 暂时保留，缺省为1N comm2varchar(255)暂时保留，缺省为1N signchar (32) 数字签名，字母是小写Y 调用说明：调用说明： 1.所有字段中不能包含 “&” 和 “=”. 2.ServiceCode：表示产品类型 QQACCT_SAVE Q 币 -QQPOINT Q 点 -去掉 LTMCLUB 会员 XXJZGW 黄钻 XXQGAME 蓝钻 XXQQF 红钻 PETVIP 粉钻 XXQQT QQ 堂紫钻 XXZXYY 绿钻 QQR2BY QQ 音速 DNFHZ 黑钻 QQFCZZ QQ 飞车紫钻 -上面数量 1-24 个月 -XXYXLB QQ 游戏欢乐大礼包 - 1 - 24 个 -DNFDQ DNF 点券 QQKDC QQ 飞车点券（comm1 表示玩家建立角色的大区，目前 1 为电信区，2 为网通区，3 为电信二区） -上面 2 个数量为 100-10000 个点券 3.QQuin：用户帐号，及收货号码，目前都是表示 QQ 号码 4.ZtcQQuin：财付通帐号，及支付号码，目前都是表示 QQ 号码 5.BuyCount：充值数量，它的意义和取值范围与 ServiceCode 产品类型有关 若产品=Q 币，则 BuyCount 表示个数，取值范围1, 1000 若产品=Q 点，则 BuyCount 表示点数，必须是 10 的整数倍，取值范围是10, 10000 若产品=包月服务，则 BuyCount 表示月数，取值范围1, 24 6.sign 为按顺序对交易信息的 MD5 加密签名的 32 位字符串： sign=md5(ServiceCode=*&QQuin=*&ZtcQQuin=*&BuyCount=*&comm1=*&comm2=*|enc _key) ，其中enc_key为注册财付通直通车时生成的key 签名举例：签名举例： 20030325的一笔交易，99999需要给用户123456充值1Q币，需要从socket读取返回结果，双方约定key 为!#$%&123ABCfg，则签名算法为： sign = Md5(“ServiceCode=QQACCT_SAVE&QQuin=123456&ZtcQQuin=99999&BuyCount=1 &comm1=1&comm2=1|!#$%&123ABCfg” ) 最终的请求串为最终的请求串为(假设最终的Md5加密结果是1e1cf8d9d57d48b96ad10bc2beead6ac) /cgi-bin/pay/bank_ztc_entry.cgi?ServiceCode=QQACCT_SAVE&QQuin=123456& ZtcQQuin=99999&BuyCount=1&comm1=1&comm2=1&sign=1e1cf8d9d57d48b96ad10bc2beead6ac Tencent财付通直通车接口协议 5 3.3.返回结果说明返回结果说明 返回结果是xml字符串 状态 结果说明 订单号 参数说明： 1 status ： =0，表示成功， =其它，表示失败 2 msg ：结果说明，可以查看成功消息或者失败提示 3 serialno ：订单号，是直通车产生的唯一序列号，可以根据此订单号到/ztcv2 查 询 4. 注意事项及限制注意事项及限制 1.系统对同一IP的充值请求频次限制在20笔交易请求每笔交易请求每20秒秒。如果商户的交易量超过该频次限制的话，切 记不要把交易请求即调用直通车url的销售请求通过同一IP发送。 5. 接入常见问题接入常见问题 1.返回错误码-2002，错误信息“IP*.*.*.*不是有效IP” 错误原因：发送请求的IP，和注册时配置的IP不符合 解决办法：登陆/ztcv2/后在配置管理里添加新IP 2.返回错误码-2003，错误信息“签名信息错误” 错误原因：Key值填写错误或请求字符串不符合要求 解决办法：正确填写key值，字符串按照接入文档的格式填写，区分大小写。 6. 常用的错误码常用的错误码 财付通直通车使用的错误码基本是-2001到-2007，-1000到-1007较少使用，其他可能透传上来的错误码可 不用记录，只记录错误信息既可。 -2001:一般是取用户信息失败，对应充值接口中各个参数具体如下 取版本号失败 取产品代码失败 Tencent财付通直通车接口协议 6 取用户号码失败 取直通车用户号码失败 取充值数量失败 取comm1失败 取comm2失败 取签名信息失败 取用户IP失败 -2002：这个是取直通车用户信息，是查找数据库出现的错误 -2003：这个是校验MD5签名的相关错误, 错误原因比较常见的是“签名信息错误” -2004：一般是查询批价时的错误，这个错误信息都是透传的，这个环节出错的比较多，常见错误如下： 您已经开通无线会员服务,不能再开通此服务 业务号码已经开通服务 您已经开通手机游戏城服务,不能再开通此服务 您已经开通网典手机超级娱乐城服务,不能再开通此服务 iProvideUin*is illegal /即充值的QQ号码*非法 您已经开通社区经典服务,不能再开通此服务 -2005：这个是发起扣款时的错误 -2006：是获取扣款结果时出错 -2007：代表发货环节失