第三方充值平台接口开发文档..

API接口说明书

版本 3.0 2.0 1.1 1.0 参数注释 验证服务器ip 创建文档 更新内容 签名生成方式 2013.11.12 2013.07.24 2013.02.08 2012.12.21 时间

1 / 20

深圳市创盾网络科技有限公司

目录

1、API介绍 ...................................................................................................................................... 3

1.1通讯协议............................................................................................................................. 3 1.2充值流程............................................................................................................................. 3 1.3权限版本 （power） ........................................................................................................ 3 1.4版本号 （ver） ................................................................................................................. 4 1.5时间戳 （timestamp） ..................................................................................................... 4 1.6订单号 （orderid） ........................................................................................................... 4 1.7数字签名（sign和signkey） ............................................................................................ 4 2、API调用说明 .............................................................................................................................. 5

2.1在线充值............................................................................................................................. 5 2.2订单回调............................................................................................................................. 7 2.3商品进价表 ......................................................................................................................... 7 2.4渠道商信息 ......................................................................................................................... 9 2.5游戏区服表 ....................................................................................................................... 11 2.6用户余额........................................................................................................................... 12 2.7手机号码归属地 ............................................................................................................... 12 2.8系统时间戳 ....................................................................................................................... 13 2.9销售软件........................................................................................................................... 13 2.10激活码开通软件 ............................................................................................................. 14 2.11下级用户列表 ................................................................................................................. 15 2.12财务记录......................................................................................................................... 16 2.13订单记录......................................................................................................................... 17 2.14转账 ................................................................................................................................ 19 3、注意事项................................................................................................................................... 19 4、通用状态码 ............................................................................................................................... 20 5、附录 .......................................................................................................................................... 20

5.1全国省份直辖市ID对照表 ............................................................................................. 20

2 / 20

深圳市创盾网络科技有限公司

1、API介绍

1.1通讯协议

1. 联系速度达技术（QQ：1551369420）获取密钥KEY，及接口地址。 2. 接口采用GET/POST方式提交请求

3. 返回XML或JSON，传入参数增加format=xml或者format=json

1.2充值流程

一次请求 保存在本地

1

请求时间戳

系统启动，获取服务器时间戳 [api/sys_now] 2

请求产品表、渠道表、区服表

获取充值产品表 [api/product]、渠道表

[api/product_channel]、区服表 [api/product_area](该步骤执行一次存储在本地即可) 3

选择产品

根据所要充值的业务需要先调用本地数据(游戏充值需调用区服表、手机充值需调用渠道表并请求归属地 [api/sys_phone])，然后选择产品。 4

提交订单

多次请求

将充值订单提交到充值接口 [api/recharge]。其中productid就是api/product的 i ；area的值就是手机号码归属地对应的值（见附录）如果是游戏则是api/product_area的i。 5

回调订单状态

回调订单状态 [api/status]。

1.3权限版本 （power）

13代表普及版 15代表专业版

3 / 20

深圳市创盾网络科技有限公司

16 代表豪华版 17 代表旗舰版

1.4版本号 （ver）

固定值等于3，每个api接口必须要传的参数。

1.5时间戳 （timestamp）

时间戳是自 1970 年 1 月 1 日（00:00:00 GMT）至当前时间的总秒数。时间戳的有效期为10分钟。如果您的本机时间为准确的“北京时间”，可使用本机时间戳，否则可通过接口获取当前服务器的时间戳，以它为基本，开始自动计时。时间戳是很多接口必须要传的一个参数。时间戳的目的是为了使一个接口产生的URL在10分钟后失效，提高安全性。

1.6订单号 （orderid）

为防止重复提交，很多接口都必须传入订单号。 建议按如下方法生成：

取系统当前时间按年月日小时分钟秒毫秒，再与用户编号用字母“v”相连。生成如： 20131112170125156v123456

1.7数字签名（sign和signkey）

sign 以时间戳作为秘钥 signkey 以KEY值和时间戳作为秘钥 如下请求为例，来说明signkey生成步骤

http://***.sududa.com/api/recharge?count=1&orderid=1384243215449v9631&productid=1139×tamp=1384243215&to=13800138000&username=test4@sududa.com&ver=3&signkey=d38d6a9180d9d7791fb11f187813c105

将除“signkey”外的所有参数按key进行字典升序排列，将接口名和排序后的参数(key=value)用&拼接起来。 例如：

/api/recharge?count=1&orderid=1384243215449v9631&productid=1139×tamp=1384243215&to=13800138000&username=test4@sududa.com&ver=3&

将上面生成的字符串连上用户设置的秘钥进行URLencode转码，把转码后的字符串进行MD5加密，即是signkey。

signkey=md5(URLencode(/api/recharge?count=1&orderid=1384243215449v9631&productid=1139×tamp=1384243215&to=13800138000&username=test4@sududa.com&ver=3&用户秘钥))

sign则是以/api/recharge?count=1&orderid=1384243215449v9631&productid=1139×tamp=1384243215&t

4 / 20

深圳市创盾网络科技有限公司

o=13800138000&username=test4@sududa.com&ver=3进行进行URLencode转码，把转码后的字符串进行MD5加密。

sign=md5(URLencode(/api/recharge?count=1&orderid=1384243215449v9631&productid=1139×tamp=1384243215&to=13800138000&username=test4@sududa.com&ver=3))

2、API调用说明

2.1在线充值 http://***.sududa.com/api/recharge

参数名称 username orderid productid to area shop count ip timestamp ver signkey 数据类型 Varchar(50) Varchar(50) long Varchar(50) NVARCHAR2(25) int int Varchar2(25) long int Varchar2(32) 说明 速度达用户名 订单号 产品ID 充值对象 地区ID/区服ID（手机充值详见附录1） 购买数量（件数） 用户的真实IP 时间戳 接口版本号 签名串(不参与加密) 是否必填 Y Y Y Y N N Y N Y Y Y 返回参数说明： 参数名称 balance status tips 数据类型 float int String 说明 用户余额 -1 表示余额未变化 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/api/recharge?count=1&ip=10.10.10.10&orderid=1384243215449v9631&productid=1139×tamp=1384243215&to=13800138000&area=1&username=test4@sududa.com&ver=3&signkey=d38d6a9180d9d7791fb11f187813c105 < <69.46 充值后用户所剩余额 <1 状态码 <：0(状态已更新！) 提示 响应示例 5 / 20

深圳市创盾网络科技有限公司

使用下表商品ID充值话费，area值可传0（无需判断号码归属地）。 中国移动（全国） 1元 2元 3元 4元 5元 6元 7元 8元 9元 商品ID 18 369 370 371 24 372 373 374 375 中国联通（全国） 1元 2元 3元 4元 5元 6元 7元 8元 9元 商品ID 1089 1090 1091 1092 1093 1094 1095 1096 1097 中国电信（全国） 10元 20元 30元 50元 100元 商品ID 1582 1583 1130 1131 1132 全国固话（全国） 10元 20元 30元 50元 100元 商品ID 1699 1698 1700 1701 1702

6 / 20

深圳市创盾网络科技有限公司

2.2订单回调 (建议下单成功1分钟后调用) http://***.sududa.com/api/status 参数名称 username orderid timestamp ver sign 数据类型 Varchar(50) Varchar(50) long int Varchar2(32) 说明 速度达用户名 订单号 时间戳 接口版本号 签名串(不参与加密) 是否必填 Y Y Y Y Y

返回参数说明：

参数名称 balance status tips 数据类型 float int String 说明 用户余额 -1 表示余额未变化 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/api/status?orderid=1384243215449v9631×tamp=1384243215&username=test4@sududa.com&ver=3&sign=d38d6a9180d9d7791fb11f187813c105 < <69.46 充值后用户所剩余额-1表示余额未变 <1 状态码 <：0(状态已更新！) 提示 响应示例

2.3商品进价表 http://***.sududa.com/api/product

参数名称 username power 数据类型 NVARCHAR2(25) int 说明 要获取的用户名 对应自己的版本 豪华版：16 旗舰版：17 是否必填 Y Y timestamp gzip ver sign long Varchar2(10) int Varchar2(32) 时间戳 gzip=true时返回加密后的GZIP串 接口版本号 签名串(不参与加密) Y N Y Y

返回参数说明：

7 / 20

深圳市创盾网络科技有限公司

参数名称 ver i b f u t 数据类型 int int String float String int 说明 商品进价表版本号 产品ID 充值时传给服务器 产品名称 面值 单位 小分类 移动是100，联通是101，电信是102，固话是103 QQ业务是200，Q币Q点是201 游戏是大等于300 c v q s o m int int int int int String 渠道ID 省份ID 详见“全国省份直辖市ID对照表” 商品大类 话费业务是1，QQ业务是2，游戏业务是3 库存 大于0均表示库存充足 排序 限购数量 如：1-1 目前话费业务不支持倍充 p16 status tips float int String 豪华版进价 旗舰版是p17 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/api/product?gzip=true&power=17×tamp=1374646885&username=test@sududa.com&ver=3&sign=aead108686817115f31592a4061fa570 < < <30 版本号 < < <1349 产品ID，充值时传给服务端 <浙江电信(手机) 产品名称 <50 面值 <元 单位 <102 小分类，移动是100,联通是101,电信是102，固话是103 <11 渠道ID <33 省份 <1 1表示手机，2表示QQ业务，3是游戏。 8 / 20

响应示例

深圳市创盾网络科技有限公司

<99 库存 <2 排序，值越小越靠前 <1 1 提交件数限止 <49.3 <49.3 普及版充值报价 <49.3 <49.3 专业版充值报价 <49.3 豪华版充值报价 <49.3 < *…… （数据返回量大，为避免本文档冗余，有删节） l> <340 <湖北联通(手机) <100 <元 <101 <12 <42 <1 <99 <3 <1 1 <98.6 <98.6 <98.6 <98.6 <98.6 <98.6 <1 状态码

2.4渠道商信息 http://***.sududa.com/api/product_channel

参数名称 username 数据类型 NVARCHAR2(25) 说明 要获取的用户名 是否必填 Y 9 / 20

深圳市创盾网络科技有限公司

timestamp gzip ver sign long Varchar2(10) int Varchar2(32) 时间戳 gzip=true时返回加密后的GZIP串 接口版本号 签名串(不参与加密) Y N Y Y 返回参数说明：

参数名称 i c r status tips 数据类型 int String String int String 说明 渠道商ID 对应产品进价表的c 渠道名称 备注 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/api/product_channel?gzip=true×tamp=1374646885&username=test@sududa.com&ver=3&sign=aead108686817115f31592a4061fa570 < < <1 渠道ID。对应product中的C <腾讯 渠道名称 < 备注 …… 响应示例 （数据返回量大，为避免本文档冗余，有删节） < <203 <网易 < <获取成功！ 提示 <1 状态码 10 / 20

深圳市创盾网络科技有限公司

2.5游戏区服表 http://***.sududa.com/api/product_area

参数名称 gzip Username timestamp ver sign 数据类型 Varchar2(10) Varchar2(50) long int Varchar2(32) 说明 gzip=true时返回加密后的GZIP串 用户名 时间戳 接口版本号 签名串(不参与加密) 是否必填 N Y Y Y Y 返回参数说明： 参数名称 i t v status tips 数据类型 int String String int String 说明 产品ID 对应产品进价表的i 游戏区服名称 游戏区服值 充值接口的area 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/api/product_area?gzip=flase×tamp=1374649868&username=test@sududa.com&ver=3&sign=2ce3613c5c6472dd9dff8012b78614e2 < < <1209 产品ID。对应product中的i <华夏电信7-8区 名称 <556 area ID …… （数据返回量大，为避免本文档冗余，有删节） 响应示例 < <1531 <网通一区-黎明港湾 <1915 < 11 / 20

深圳市创盾网络科技有限公司

<获取成功！ 提示 <1 状态码

2.6用户余额 http://***.sududa.com/api/userinfo

参数名称 username timestamp ver signkey 数据类型 NVARCHAR2(50) long int Varchar2(32) 说明 要获取的用户名 时间戳 接口版本号 签名串(不参与加密) 是否必填 N Y Y Y 返回参数说明：

参数名称 blance balance_lock power_text status tips 数据类型 float float String int String 说明 用户余额 未确认余额 用户类型 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/api/userinfo?timestamp=1374636555&username=test@sududa.com&ver=3&signkey=b8ba311d3e31dd25bb6e10df81752f61 < <50.0 用户余额 <0.0 未确认余额 <豪华版 用户类型 <获取成功！ 提示 <1 状态码 响应示例

2.7手机号码归属地 http://***.sududa.com/api/sys_phone

参数名称 username phone timestamp ver 数据类型 NVARCHAR2(50) long long int 说明 要获取的用户名 要获取的手机号 时间戳 接口版本号 是否必填 N Y Y 12 / 20

深圳市创盾网络科技有限公司

sign Varchar2(32) 签名串(不参与加密) Y 返回参数说明：

参数名称 type city areacode zipcode status tips 数据类型 String String String String int String 说明 号码运营商 归属地 区号 邮编 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/api/sys_phone?phone=13811054321×tamp=1374640131&username=test@sududa.com&ver=3&sign=774260412a95b0732df408855e6a7141 <中国移动GSM 号码运营商 <北京 北京 归属地 <010 区号 <100000 邮编 <获取成功！ 提示 <1 状态码 响应示例 2.8系统时间戳 http://***.sududa.com/api/sys_now

参数名称 请求示例 响应示例 数据类型 说明 是否必填 http://***.sududa.com/api/sys_now < <1387437191 系统时间戳 <获取成功！ 提示 <1 状态码

2.9销售软件 http://***.sududa.com/exe/agent_open

参数名称 username

数据类型 Varchar(50) 说明 速度达用户名 是否必填 Y 13 / 20 深圳市创盾网络科技有限公司

orderid open power timestamp ver signkey Varchar(50) Varchar(50) int long int Varchar2(32) 订单号 要开通用户名 权限版本号 时间戳 接口版本号 签名串(不参与加密) Y Y Y Y Y Y

返回参数说明：

参数名称 income balance status tips 数据类型 float float int String 说明 此次扣费金额 用户余额 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/exe/agent_open?open=test5@sududa.com&orderid=1384244221043v9631&power=16×tamp=1384244221&username=test4@sududa.com&ver=3&signkey=73d5ec1f79f71239e8cd52afd1331f43 < in-270 此次扣费金额 <69.46 用户余额 <1 状态码 <开通成功！ 提示 响应示例

2.10激活码开通软件 http://***.sududa.com/exe/activation_agent_open

参数名称 username code open power timestamp ver signkey 数据类型 Varchar(50) Varchar(50) Varchar(50) int long int Varchar2(32) 说明 速度达用户名 激活码 要开通用户名 权限版本号 时间戳 接口版本号 签名串(不参与加密) 是否必填 Y Y Y Y Y Y Y

返回参数说明：

参数名称 power_text status 数据类型 String int 说明 开通版本名称 状态 详见“通用状态码” 14 / 20

深圳市创盾网络科技有限公司

tips String 状态提示信息 请求示例 http://***.sududa.com/exe/activation_agent_open?code=DA13P639AC23BB8350F81VQY4XHOW9&open=test5@sududa.com×tamp=1384246055&username=test4@sududa.com&ver=3&sign=614299ea5174a76220941a532ca2d517 < < 普及版 开通版本 响应示例 激活成功！ 提示 1 状态码 2.11下级用户列表 http://***.sududa.com/es/agent_list

参数名称 username date1 date2 key page line timestamp ver signkey 数据类型 Varchar(50) Varchar2(10) Varchar2(10) Varchar(50) Int Int long int Varchar2(32) 说明 速度达用户名 开始时间2013-11-01 结束时间2013-11-22 下级速度达账号 第几页 每页几行 默认25行 时间戳 接口版本号 签名串(不参与加密) 是否必填 Y Y Y N N N Y Y Y 返回参数说明：

参数名称 username time power power_text status tips 数据类型 String String int String int String 说明 开通的用户名 开通时间 开通的版本 开通版本名称 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/es/agent_list?date1=2013-11-01&date2=2013-11-22&line=10&page=1×tamp=1385111838&username=test4@sududa.com&ver=3&signkey=e86e9e8ee97962cfef081fadc1d2c7a3 15 / 20

响应示例

深圳市创盾网络科技有限公司

test5@sududa.com 2013-11-12 16:47:53 13 普及版 1 共几页 1 总行数 获取成功！ 1 2.12财务记录 http://***.sududa.com/es/finance_list

参数名称 username do date1 date2 param page line timestamp ver signkey 数据类型 Varchar(50) Varchar2(20) Varchar2(10) Varchar2(10) Varchar(50) Int Int long int Varchar2(32) 说明 速度达用户名 search 开始时间2013-11-01 结束时间2013-11-22 订单编号/交易对方账号/加款账号 第几页 每页几行 默认25行 时间戳 接口版本号 签名串(不参与加密) 是否必填 Y Y Y Y N N N Y Y Y 返回参数说明： 参数名称 o i b t r status tips 数据类型 String float float String String int String 说明 财务流水号 收/支 余额 交易时间 交易备注 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/es/finance_list?date1=2013-11-01&date2=2013-11-22&do=search&line=10&page=1×tamp=1385112072&username=test4@sududa.com&ver=3&signkey=431797b941087 16 / 20

深圳市创盾网络科技有限公司

085221f720b5b5d2f8b 响应示例 1385024843700123 29878.0 29878.0 2013-11-21 17:08 来自1@1.com的转账(士大夫) 20131121170706215v9631 财务流水号 -29878.5 收/支 0.1 余额 2013-11-21 17:07 交易时间 转账至1@1.com 备注 …… 4 共几页 37 总行数 获取成功！ 1 2.13订单记录 http://***.sududa.com/es/recharge_list

参数名称 username do date1 date2 param page line timestamp ver signkey 数据类型 Varchar(50) Varchar2(20) Varchar2(10) Varchar2(10) Varchar(50) Int Int long int Varchar2(32) 说明 速度达用户名 search 开始时间2013-11-01 结束时间2013-11-22 订单编号/充值号码 第几页 每页几行 默认25行 时间戳 接口版本号 签名串(不参与加密) 是否必填 Y Y Y Y N N N Y Y Y 返回参数说明：

参数名称 o e

数据类型 String String 说明 订单编号 备注 17 / 20

深圳市创盾网络科技有限公司

p b a s_text t t_ok c s y f status tips float String String String String String String String String String int String 价格 充值号码 买家 状态描述 下单时间 订单成功时间 渠道 客户端 业务类型 数量 状态 详见“通用状态码” 状态提示信息 请求示例 http://***.sududa.com/es/finance_list?date1=2013-11-01&date2=2013-11-22&do=search&line=10&page=1×tamp=1385112072&username=test4@sududa.com&ver=3&signkey=431797b941087085221f720b5b5d2f8b 20131218144937900959v9631 订单编号 Q币1个 备注

0.92元×1件＝0.92元

响应示例

深圳市创盾网络科技有限公司

2.14转账 http://***.sududa.com/es/transfer_accounts

参数名称 username orderid to amount remark timestamp ver signkey 数据类型 Varchar(50) Varchar(50) Varchar(50) float Varchar2(50) long int Varchar2(32) 说明 速度达用户名 订单号 收款方速度达用户名 转账金额 备注 时间戳 接口版本号 签名串(不参与加密) 是否必填 Y Y Y Y N Y Y Y 请求示例 http://***.sududa.com/es/transfer_accounts?amount=100&orderid=1384244221143v9631&remark=×tamp=1387439522&to=1@1.com&username=test4@sududa.com&ver=3&signkey=91a13755f9ada861e159e966a7343c83 < <69.46 用户余额 <1 状态码 <开通成功！ 提示 响应示例 3、注意事项

1. 2.

系统对同一IP的充值请求频次限制在30秒90次。如果商户的交易量超过该频次限制的话，切记不要把系统对提交的充值请求只进行单次处理，如果交易过程出现错误，该笔交易被视为无效请求，系统不交易请求通过同一IP发送。

会再继续处理该交易请求（如已对商户进行扣款的，系统会自动在当日或次日进行退款）。商户需根据自己的实际情况确定是否再次发起充值请求。 3. 4. 5. 6.

如部分订单未及时退款的，请商户联系我们的在线客服查单退款。 本系统所有参数及MD5加密串均为小写。

因速度达API接口基于Linux+Java架构，所以URL区分大小写。 所有请求接口都需传入username参数

URLEncode转码注意各语言的差异，本系统采用的是java.net.URLEncode.encode()，相对应的c#用Uri.EscapeDataString()。

7.

19 / 20

深圳市创盾网络科技有限公司

4、通用状态码

状态码 -9 -1 1 0 5 9 10 说明 订单未提交，未扣款（提示各种异常） 已扣款，将提交供货商 成功 处理中 疑似成功 部分退款 全额退款 5、附录

5.1全国省份直辖市ID对照表

ID 0 11 12 13 14 15 21 22 23 31 32 33 34 35 36 37 全国 北京 天津 河北 山西 内蒙古 辽宁 吉林 黑龙江 上海 江苏 浙江 安徽 福建 江西 山东 text 41 42 43 44 45 46 50 51 52 53 54 61 62 63 64 65 ID 河南 湖北 湖南 广东 广西 海南 重庆 四川 贵州 云南 西藏 陕西 甘肃 青海 宁夏 新疆 text

20 / 20