CTAPIV环迅支付接口.docx

CROWN TECHNOLOGY
CTAPI游戏接入接口
使用说明文档 V1.7
CTAPI游戏接入接口 1
1. 概述 2
2. 协议约定及功能接口 2
2.1 通讯规范 2
2.1.1数据结构 3
2.1.2安全验证 3
2.1.3响应规范 3
2.1.4 错误码 3
2.2 接口列表及数据约定 4
2.2.1获取会员登录URL[核心接口] 4
2.2.2获取供应商会员信息 6
2.2.3会员存款[核心接口] 6
2.2.4会员取款[核心接口] 7
2.2.5会员存取款状态查询[核心接口] 8
2.2.6在线会员列表 9
2.2.7 注销在线会员 9
2.2.8 会员状态更新 10
2.2.9 按时间查询已结算和已撤销注单[此接口仅作查询之用] 11
2.2.10 按时间查询未结算注单[此接口仅作查询之用] 12
2.2.11 获取结算/撤销注单[与2.2.12配对使用][取注单请使用此接口][核心接口] 13
2.2.12 标记结算/撤销注单[与2.2.11配对使用][核心接口] 14
2.2.13 按时间查询已结算和已撤销注单数目 14
2.2.14 按时间查询未结算注单数目 15
2.2.15按注单号查询未结算/已结算/已撤销注单 16
3. 附录 16
3.1 桌号、类型对应表 16
3.2货币列表 16
3.3语言列表 17
3.4 注单说明 17
3.5下注及输赢结果说明 17

1. 概述
本文档主要叙述CT游戏中心服务器与游戏接入商服务器之间的数据通讯协议及规范，双方的软件在此基础上达到数据高性能、高安全性进行交换与共享的目的。
[核心接口]表明此接口极为重要，如有任何疑问，请及时与供应商方面联系。
随本文档一起还有“demo_xx.txt”，“CasinoLimit_xxxxxx.xlsx”，“CtapiDemoJs”客户端Demo。
系统时区：GMT+7
系统维护时间：每周二（12：00-13：00）（GMT+7）

2. 协议约定及功能接口
2.1 通讯规范
2.1.1数据结构
http://<host>/ctapi?action=<action>&agent=<agent>&username=<username>&param=<param>
参数说明：
参数
类型
描述
action
String
命令标识符
agent
String
代理账号，由供应商提供。区分大小写。
username
String
会员账号，长度[1,16]; 只允许数字、字母与@标记符。只能使用小写。
param
String
其它信息（可选），[ ]为可以项目

2.1.2安全验证
Ø 安全码
供应商提供密文SecurityKey：由供商提供（在demo[xx..xx].txt中）
Ø 来源检查
由接入商提供，一个agent可以对应多个referer（暂时没用）。
Ø IP过滤
由接入商提供系列IP，IP跟agent进行绑定。测试机不检测IP绑定，正式机强制性检测IP绑定。

2.1.3响应规范
<?xml version="1.0"?>
<response>
<code></code>
<text></text>
<result></result>
</response>

2.1.4 错误码
通常情况下，0 表示没有错误，负数为一般错误，正数为相应操作错误。
下表为一般错误表：
错误码
文本数据
描述
-1
System maintenance
系统维护
-2
Invalid action
命令标识符错误
-3
Invalid arguments
请求参数错误
-4
IP address not allow
IP限制
-5
Invalid username
用户名或代理错误
-6
System error
系统错误

2.2 接口列表及数据约定
接入端在请求数据时，需根据接口的不同组织相应的参数为字符串，通过TCP连接发送至服务器端，服务器端通过约定以特定分隔符将字符串解析为对应参数，处理完成后，将结果组织为字符串通过TCP连接发回接入端。

在通讯过程中，为保证数据的正确性和提高程序性能，通讯过程中数据类型与字符串之间的转换按下表规范：
数据类型
描述
示例
String
Unicode字符串
如：hello，abc123
Byte
可转为标准数字
如：-123，9
范围：-128~127
Integer
可转为标准数字
如：-123，9
范围：-2147483648~2147483647
Long
可转为标准数字
如：-123，4，5099
范围：-9223372036854774808~9223372036854774807
Double
可转为标准浮点数
如：-1.23，4，5.09
范围：4.9000000e-324~1.797693e+308
Boolean
bool值
True，False
Date
以yyyy-MM-dd HH:mm:ss 形式的字符串
如：2011-01-31 19:25:34

为便于客户端与服务器端易于解析数据，以如下分隔符作为数据分隔使用的特殊字符（因此在正常数据内容中，不应包括如下特殊字符）：

第一层数据分隔符：|
第二层数据分隔符：`
第三层数据分隔符：,

客户端在接收到来自服务器端的返回数据Data，并转化为字符串时，按接口约定，对该字符串以分隔符从低层至高层拆分，得到最终数据。

2.2.1获取会员登录URL[核心接口]
操作描述
获取供会员登录到供应商进行游戏的URL。首先供应商会检测用户是否存在，若存在，返回登录URL；若不存在，供应商自动创建账号，如果创建成功，返回登录URL，如果创建失败，返回错误原因。
注意：调用完此接口，会员需使用返回的URL登录游戏大厅。
使用场景
用户登录。使用时机，会员登录前。
命令标识符
1
参数及组合格式
Lang|Currency|MaxWin|Limit|Token
例：cn|RMB|900.0|578,579,580,`589,590,588,587,`594,592,593,591,`710,712,713,714,`-1` 1151,1183,1184,1185,`1923,|b69af9287876c8cfc42096be301b233c
例：cn|RMB|900.0||b69af9287876c8cfc42096be301b233c
参数说明
参数
类型
描述
Lang
String
语言(见语言列表)
Currency
String
货币(见货币列表)
MaxWin
Double
该会员的单日最大可赢取金额。（当天12点到第二天12点）
注：
a)会员最后一笔下注有可能超过最大限额
b)负数或0表示不限制用户赢取金额
Limit
String
此处为各游戏限红[详见CasinoLimit_xxxxxx.xlsx]：
顺序为:百家乐|轮盘|赛宝|龙虎|番摊|保险百家乐|色碟 最多四条限红，
注：
a)-1为游戏不可玩
b)当Limit为空时,供应商自动提供四条最小限红
例：578,579,580,`589,590,588,587,`594,592,593,591,` 710,712,713,714,`-1`1151,1183,1184,1185,`1923,
Token
String
Md5加密生成的验证码，产生规则：Md5(“SecurityKey+Currency+Agent+UserName+Lang+MaxWin”)，（见加密算法）。
例：Md5(“sc4XgdJc85RMBLiga365usd000cn900.0”)=d4493b6a9cc9f682c52dc82bbcc14150
返回数据描述
例：code>0</code><text>Success</text><result>http://localhost:8080/api/ctapi/api/home.jsp?username=LOCALAPIusd000&amp;key=8506806436720062641</result>
例： <code>1</code><text>Locked</text><result></result>
索引
文本数据
描述
0
Success
返回登录URL，会员使用此URL登录
说明：此URL有效期1分钟，若1分钟内没有登录，这个URL就会失效
1
Locked
账户被锁定

登录步骤:
a)调用2.2.1接口
b)返回<code>0</code>，提取<result></result>内容，即登录URL
c)重定向到登录URL

2.2.2获取供应商会员信息
操作描述
获取会员在供应商的相关信息。会员在线信息，“Online”表示在线, “Offline”表示不在线。会员状态信息，“Normal”表示正常，此时会员可登录游戏大厅并可下注；“Supend”表示暂停，此时会员可登录游戏大厅但不可下注；”Closed”表示停用，此时会员不可登录游戏大厅。会员余额信息，表示用户可用于下注的金额或提取的余额。
使用场景
1#检测会员是否已存在。使用时机，调用2.2.1（获取会员登录URL）接口失败时。
2#检测会员是否在线。使用时机，调用2.2.7（注销在线会员）接口前。
3#查询会员是否正常。使用时机，调用2.2.8（会员状态更新）接口后。
4#查询会员余额。使用时机，调用2.2.4（会员取款）接口前。
命令标识符
2
参数及组合格式

返回数据描述
<online_status>Online[Offline]</online_status>
<member_status>Normal[Suspend][Closed]</member_status>
<balance>Amount</balance>
例：<code>0</code><text>User Exist</text>
<result><online_status>Online</online_status><member_status>Normal</member_status><balance>96.85</balance></result>
例：<code>1</code><text>User not exist</text>
<result><online_status></online_status><member_status> </member_status><balance></balance></result>

索引
文本数据
描述
0
User exist
用户存在且在线，返回用户信息
1
User not exist
用户不存在

2.2.3会员存款[核心接口]
操作描述
会员将接入商钱包的钱，部分或者全部提取到游戏供应商的账户上进行游戏。接入商需对并发进行控制。
使用场景
会员将钱存到CASINO，建议调用2.2.5（会员存取款状态查询）接口进行确认。
命令标识符
3
参数及组合格式
Serial|Amount|Currency|Token
例：32535|36.58|RMB|9264477335c078ca871a28b2fc8c0448
参数
类型
描述
Serial
Long
会员转账流水号(唯一)，由接入商产生。
Amount
Double
a)精度小数点两位,格式:######.00;
b)大于0;
Currency
String
货币(见货币列表)，
注：币种为空时，不作检查。
Token
String
Md5加密生成的验证码，产生规则：Md5(“SecurityKey+Amount+Agent+UserName+ Serial”)，（见加密算法）。
例：Md5(“sc4XgdJc8536.58Liga365usd00032535”)=9264477335c078ca871a28b2fc8c0448
返回数据描述
成功：返回转账金额
例：<code>0</code><text>Success</text><result>36.58</result>
例：<code>2</code><text>Duplicated serial</text><result></result>
索引
文本数据
描述
0
Success
操作成功，返回用户信息
1
User not exist
用户不存在
2
Duplicated serial
流水号存在
3
Currency error
币种错误
4
Deposit error
其它错误

2.2.4会员取款[核心接口]
操作描述
会员将游戏供应商的账户上金额转存到接入商，取款时需调用“检查用户状态”接口检查用户金额避免错误。
使用场景
会员将钱从CASINO取出，建议调用2.2.5（会员存取款状态查询）接口进行确认。
命令标识符
4
参数及组合格式
Serial|Amount|Currency|Token
例：32536|36.58|RMB|c7e1ba9f2e033e400d329793c55bcd62
参数
类型
描述
Serial
Long
会员转账流水号(唯一)，由接入商产生。
Amount
Double
a)精度小数点两位,格式:######.00;
b)大于0;
Currency
String
货币(见货币列表)，
注：币种为空时，不作检查。
Token
String
Md5加密生成的验证码，产生规则：Md5(“SecurityKey+Amount+Agent+UserName+ Serial”)，（见加密算法）。
例：Md5(“sc4XgdJc8536.58Liga365usd00032536”)=c7e1ba9f2e033e400d329793c55bcd62
返回数据描述
成功：返回转账金额
例：<code>0</code><text>Success</text><result>36.58</result>
例：<code>2</code><text>Duplicated serial</text><result></result>
索引
文本数据
描述
0
Success
操作成功，返回用户金额
1
User not exist
用户不存在
2
Duplicated serial
流水号存在
3
Currency error
币种错误
4
Withdrawal error
其它错误

2.2.5会员存取款状态查询[核心接口]
操作描述
查询指定流水号存款或取款是否成功，若成功，则返回相关信息，否则返回流水号不存在。
使用场景
确认存取款是否成功。使用时机，调用完2.2.3（会员存款）接口或2.2.4（会员取款）接口后。
命令标识符
5
参数及组合格式
Serial
注意：username此处空或任意值。
例：32536
参数
类型
描述
Serial
Long
会员转账流水号(唯一)，由接入商产生。
返回数据描述
<serial>Serial</serial>
<username>Username</username>
<amount>Amount</amount>
<datetime>Date Time</datetime>
例： <code>0</code><text>Success</text>
<result><serial>32536</serial><username>usd000</username><amount>36.58
</amount><datetime>2013-01-31 19:25:34</datetime></result>
例： <code>1</code><text>Serial not exist</text>
<result><serial>32536</serial><username></username><amount></amount>
<datetime></datetime></result>
例： <code>-6</code><text>System error</text><result>/result>
索引
文本数据
描述
0
Serial exist
流水号存在，返回用户金额
1
Serial not exist
流水号不存在

2.2.6在线会员列表
操作描述
获取所有在线用户
使用场景

命令标识符
6
参数及组合格式
注意：username此处空或任意值。
返回数据描述
<username id='1'>Username</username>
……
<username id='n'>Username</username>
例： <code>0</code><text>Success</text><result>
<username id='1'>usd000</username>
<username id='2'>usd001</username></result>
索引
文本数据
描述
0
Success
返回用户列表。

2.2.7 注销在线会员
操作描述
将正在游戏中的会员强制踢出系统。
使用场景

命令标识符
7
参数及组合格式
username 1|[ username 2]|[ username 3]|[ username 4]
注意：username此处空或任意值。param参数为空注销所有会员,。
返回数据描述
<logout id="1">
<username>Username</username><status>Success[Fail]</status></logout>
……
<logout id="n">
<username>Username</username><status>Success[Fail]</status></logout>
例： <code>0</code><text>Success</text><result>
<logout id="1"><username>usd000</username><status>Success</status></logout>
<logout id="2"><username>cc001</username><status>Fail</status></logout>
</result>
索引
文本数据
描述
0
Success
注销在线会员成功，顺序对应相应用户名
a)Success成功
b)Fail失败（参数为空，或者不在线时）

2.2.8 会员状态更新
操作描述
更新会员账号的状态。不同状态说明，详见2.2.2（获取供应商会员信息）接口。
使用场景

命令标识符
8
参数及组合格式
Username 1`Status 1|[Username 2`Status 2]
注意：username此处无用，不作处理。
例：usd000`1|usd001`2
参数
类型
描述
Type
Byte
1：激活用户
2：暂停用户
3：关闭用户
返回数据描述
<update id="1">
<username>Username</username><type></type><status>Success[Fail]</status>
</update>
……
<update id="n">
<username>Username</username><type></type><status>Success[Fail]</status>
</update>
例： <code>0</code><text>Success</text><result>
<update id="1">
<username>usd000</username><type>1</type><status>Success</status></update>
<update id="2">
<username>cc001</username><type>2</type><status>Fail</status></update>
</result>
索引
文本数据
描述
0
Success
更新状态成功，顺序对应相应用户名
a)Success成功
b)Fail失败（参数不正确、用户名不存在均会失败）

2.2.9 按时间查询已结算和已撤销注单[此接口仅作查询之用]
操作描述
此功能用来获取一段时间内的结算和撤销注单，所有注单按时间排序，最大100笔，时间差不能超过24小时且抓取注单间隔不能小于15秒，否则系统不予处理。（此功能很少用）
警告：此接口仅作查询之用，取注单请使用2.2.11号接口
使用场景
极少使用
命令标识符
9
参数及组合格式
StartTime|EndTime
例：2011-01-31 19:25:34|2011-01-31 19:27:34
注意：username为空，查询所有会员注单信息；不为空，查询单个会员下注信息。
参数
类型
描述
StartTime
Date
注单的开始时间，结算时间或撤消时间（包括此时间点）
EndTime
Date
注单的结束时间，结算时间或撤消时间（不包括此时间点）
返回数据描述
例： <code>0</code><text> Success</text><result><row><transaction_id></transaction_id><transaction_date_time></transaction_date_time><closed_time></closed_time><member_id></member_id><member_type></member_type><currency></currency><balance_start></balance_start><balance_end></balance_end><IsRevocation></IsRevocation><GameType></GameType><TableID>/TableID><ShoeID></ShoeID><PlayID></PlayID><BetPoints></BetPoints><BetPointDetail></BetPointDetail><BetResult></BetResult><BetResultDetail></BetResultDetail><WinOrLoss></WinOrLoss><betip></betip><paramid></paramid><availablebet></availablebet></row>
</result>
格式：
<row id=”1”>
<transaction_id>354030</transaction_id> --- long (注单号，指客户下注某笔记录在所有记录中的id号，如之前的记录是空此时客户test_1下了一个注单那么交易id=1，然后test_2 接着下了一笔那么test_2的id是2)
<transaction_date_time>2011-07-25 14:19:09</transaction_date_time> --- String (yyyy-MM-dd HH:mm:ss)(下注时间)
<closed_time>2011-07-25 14:20:35</closed_time>---String(yyyy-MM-dd HH:mm:ss)(结算或撤消时间，特别说明：此字段对已结算或已撤消的注单有意义；对于未结算注单，是没有意义的，此时值为1970-01-01 00:00:00)
<member_id>smt99test23</member_id> --- String (客户账号名)
<member_type>CASH</member_type> --- String (客户类型，现金或信用额)
<currency>THB</currency> --- String (币别类型)
<balance_start>10000.0</balance_start> --- double (下注之前的余额)
<balance_end>2000.0</balance_end> --- double (下注之后的余额)
<IsRevocation>1</IsRevocation> ---- int (是否计算,0:表示没计算，1:表示已经计算2，:表示结果撤销即此局作废)
<GameType>1</GameType> --- int(表示是哪种游戏 见附件)
<TableID>1</TableID> ---- int(表示是哪桌的游戏 见附件)
<ShoeID>1247</ShoeID> ---long(牌类游戏中,每洗一次牌 就是一靴,代表靴号)
<PlayID>11</PlayID> ----long(牌类游戏中指的是每一靴牌中的第几局;非牌类游戏指第几局)
<BetPoints>8000.0</BetPoints> ---double(指下注金额)
<BetPointDetail>0#8000#0#0#0#0#0#</BetPointDetail> ---String(指详细下注的信息,此注单下了哪些注 见附件)
<BetResult>1#0#0#2#^45#26#0#20#18#1#</BetResult> --String(此局结果 见附件)
<BetResultDetail>0.0#0.0#0.0^8000.0#0.0#0.0^0.0#0.0#0.0^0.0#0.0#0.0^0.0#0.0#0.0^0.0#0.0#0.0^0.0#0.0#0.0^</BetResultDetail> --String (计算结果明细,具体格式见计算的文档)
<WinOrLoss>0.0</WinOrLoss> -- Double(此局的输赢金额 注不是实际输赢还要计算,见计算说明)
<betip>60.50.82.208</betip> -- String(客户下注时所在IP)
<paramid>57</paramid> ---long (外部参数，无意义)
<availablebet>7800.0</availablebet>--double(实际有效下注,即可以计算结果的下注，此你下注了8000但是有效的只有7800)
</row>
计算说明：会员净输赢 = WinOrLoss – BetPoints
例如：
BetPoints = 100.0, WinOrLoss = 0.0, 表示会员输100.0；
BetPoints = 100.0, WinOrLoss = 100.0，表示会员没输没赢；
BetPoints = 100.0, WinOrLoss = 200.0, 表示会员赢100.0；

索引
文本数据
描述
0
Success
返回注单信息
1
Fetch time is too short
抓取注单间隔太短
2
Time interval is too long
时间差太长

2.2.10 按时间查询未结算注单[此接口仅作查询之用]
操作描述
此功能用来获取一段时间内的未结算的注单，所有注单按时间排序，最大100笔。时间差不能超过30天且抓取注单间隔不能小于15秒，否则系统不予处理。（此功能很少用）
警告：此接口仅作查询之用
使用场景
极少使用
命令标识符
10
参数及组合格式
StartTime|EndTime
例：2011-01-31 19:25:34|2011-01-31 19:27:34
注意：username为空，查询所有会员注单信息；不为空，查询单个会员下注信息。
参数
类型
描述
StartTime
Date
注单的开始时间，下注时间（包括此时间点）
EndTime
Date
注单的结束时间，下注时间（不包括此时间点）
返回数据描述
索引
文本数据
描述
0
Success
返回注单信息，格式如2.2.9
1
Fetch time is too short
抓取注单间隔太短
2
Time interval is too long
时间差太长

2.2.11 获取结算/撤销注单[与2.2.12配对使用][取注单请使用此接口][核心接口]
操作描述
此功能用来获取结算和撤销注单，所有注单按时间排序，最大100笔。抓取注单间隔不能小于15秒，否则系统不予处理。同时，由于供应商存在改注单及撤销情况，接入商需要对注单ID进行比对，及时对已存在注单进行更新。
注：重点对撤销及改注单情况进行说明：
如果接入商接收相同的注单<transaction_id></transaction_id>且该注单在之前已经标记成功，那么需要单独进行处理。
a、<IsRevocation>2</IsRevocation>表示此局已经撤销，结果无效，如果接入商开始已经接收该笔注单，需要对该笔数据重新计算。
b、<IsRevocation>1</IsRevocation>，那么表示该注单已经重新计算过。接入商需要对该笔数据进行纠正。

提醒：当调用完此接口，处理完相关业务后，务必及时调用2.2.12号接口对已成功取得的注单进行标记，否则下次调用该接口时，仍会返回之前的结果。
使用场景
固定周期抓取注单。调用此接口，可避免漏单，调用完此接口切记要调用2.2.12（标记结算/撤销注单）接口。
命令标识符
11
参数及组合格式

返回数据描述
索引
文本数据
描述
0
Success
返回注单信息，格式如2.2.9
1
Fetch time is too short
抓取注单间隔太短

操作步骤:
a)调用2.2.11接口
b)客户端业务处理
c)提取出所有transaction_id
d)调用2.2.12接口，提交这些transaction_id

2.2.12 标记结算/撤销注单[与2.2.11配对使用][核心接口]
操作描述
此功能用来标记接入商已收到的注单。接入商在收到注单，并成功处理后，请务必调用该接口对注单进行标记，避免相同注单。最大处理100条。
使用场景
调用完2.2.11（获取结算/撤销注单）接口后。
命令标识符
12
参数及组合格式
Ticket 1|[Ticket 2]|[Ticket 3]
注意：username此处无用，不作处理。
例：19851|19856|20081
参数
类型
描述
Ticket
Long
注单号，即transaction_id。
返回数据描述
例： <code>0</code><text>Success</text><result><update_num>3</update_num></result>
<update_num>3</update_num>---Integer(指本次成功标记的数目。0表示提交的Ticket不存在，或之前已标记)

索引
文本数据
描述
0
Success
标记成功。
1
Fail
标记失败。

2.2.13 按时间查询已结算和已撤销注单数目
操作描述
此功能用来获取一段时间内的结算和撤销注单数目
使用场景

命令标识符
13
参数及组合格式
StartTime|EndTime
例：2011-01-31 19:25:34|2011-01-31 19:27:34
注意：username为空，查询所有会员注单数目信息；不为空，查询单个会员注单数目信息
参数
类型
描述
StartTime
Date
注单的开始时间，结算时间或撤消时间（包括此时间点）
EndTime
Date
注单的结束时间，结算时间或撤消时间（不包括此时间点）
返回数据描述
例：<code>0</code><text>Success</text><result><ticket_count><total_count>0</total_count><detail><uncalcuated_count>0</uncalcuated_count><calcuated_count>0</calcuated_count><canceled_count>0</canceled_count></detail></ticket_count></result>
格式：
<total_count>5</total_count>---Integer(注单总数目)
<uncalcuated_count>0</uncalcuated_count>---Integer(未结算注单数目)
<calcuated_count>4</calcuated_count>---Integer(已结算注单数目)
<canceled_count>1</canceled_count>---Integer(已撤消注单数目)
等式关系：total_count = uncalcuated_count + calcuated_count + canceled_count
此处：ncalcuated_count=0

索引
文本数据
描述
0
Success
返回注单数目信息

2.2.14 按时间查询未结算注单数目
操作描述
此功能用来获取一段时间内的未结算的注单数目
使用场景

命令标识符
14
参数及组合格式
StartTime|EndTime
例：2011-01-31 19:25:34|2011-01-31 19:27:34
注意：username为空，查询所有会员注单数目信息；不为空，查询单个会员注单数目信息。
参数
类型
描述
StartTime
Date
注单的开始时间，下注时间（包括此时间点）
EndTime
Date
注单的结束时间，下注时间（不包括此时间点）
返回数据描述
等式关系：total_count = uncalcuated_count + calcuated_count + canceled_count
此处：alcuated_count =0，canceled_count = 0
索引
文本数据
描述
0
Success
返回注单数目信息，格式如2.2.13

2.2.15按注单号查询未结算/已结算/已撤销注单
操作描述
此功能用来查询指定单号的注单信息。
使用场景

命令标识符
15
参数及组合格式
Ticket 1|[Ticket 2]|[Ticket 3]
注意：username此处无用，不作处理。
例：19851