自助终端机API v2.0

游戏目录API

该API提供游戏目录，即艾克索拉系统中所有可用项目的列表。API提供每个项目的基本信息，如项目名称、项目图标、支付参数等。上述信息可用于项目中支付页面的创建。

游戏目录API可用于通过自助终端界面的“游戏按钮”进行的支付。将常规的艾克索拉按钮替换为自助终端界面的“游戏按钮”后，用户可在其最爱的项目中以其熟悉的方式轻松完成支付。

API URL： https://api.xsolla.com/projects/list/index.php

请求形式

用于获取游戏列表的请求参数

生成签名

签名用于在支付检查和支付执行时确保安全。签名通过对字符串进行MD5散列生成，该字符串是将上述参数按下列顺序串联并以"|“分隔而形成的。

1md5(<ID>|<secret_key>)

secret_key: 交易方密钥。

示例： 针对交易方#184、密钥为"SecretKey"的签名按如下方式构成：

$sign=md5(“184|SecretKey”)=0a8d9fb24fcbac2efafec5e51045d05c

请求示例：

https://api.xsolla.com/projects/list/index.php?id=184&sign=0a8d9fb24fcbac2efafec5e51045d05c

响应形式

响应以XML格式提交，其中包含游戏列表和每个游戏的基本信息。XML结构如下：

 1<projectlist>
 2   <project>
 3       <id>12345</id>
 4       <name>Game</name>
 5       <virtual_currency>Game of currency</virtual_currency>
 6       <logo>http://static.xsolla.com/img/game/12345.gif</logo>
 7       <limits>
 8           <min>Minimum of amount game of currency</min>
 9           <max>max of amount game of currency</max>
10       </limits>
11       <prompt>enter nickname of personage</prompt>
12       <v1>nickname of personage</v1>
13   </project>
14   ...
15</projectlist>

字段描述

发生错误时的响应形式

发生错误时，API会以XML消息响应。

1<error>
2    <description>Incorrect signature</description>
3</error>

错误描述

与代理交互

概览

有两种可能的交互选项：

• 艾克索拉按钮。此按钮位于代理侧，点击此按钮后，用户会被提示输入此前收到的号码，并按此号码支付。要启用通过艾克索拉按钮支付，需要填写account字段（project、“v1”、“v2"和"v3"字段则必须留空）。account字段必须填入9位数字（艾克索拉号码）。要设置艾克索拉按钮，您必须联系经理，获取Logo和号码。
• 游戏按钮。这些按钮位于代理侧，每个按钮分别对应不同的游戏。用户点击某一游戏的按钮，然后登录并使用其帐户进行支付。要启用通过游戏按钮支付，需要填写project、“v1”、“v2"和"v3"字段（account字段则必须留空）。项目（游戏）按钮在终端配置完毕后，您就可以发送project、“v1”、“v2"和"v3"字段。project和"v1"字段为必填，“v2"和"v3"字段为选填（实际显示的字段视具体项目而定）。要设置游戏按钮，您必须联系经理，以获取游戏Logo、游戏内部ID、验证方式（“v1”、“v2"和"v3"字段的填写规则）及其他游戏信息。

按钮是代理系统的一项元素，激活按钮将引发通过艾克索拉系统进行的支付。

将代理连接到艾克索拉系统前，请明确以下信息：

1. 艾克索拉系统中的合作伙伴号码（类型）。要获取该信息，可联系您的艾克索拉客户成功经理。
2. secret_key是生成数字签名（MD5字符串）所必需的保密字符串参数。您可以通过您的客户成功经理在发布商帐户中找到此信息。

要与API交互，您可以将HTTP请求发送至API直接帐户：

1https://ps.xsolla.com/api/gate

API接受GET或POST请求。所有参数必须采用UTF-8编码，因为使用不匹配的编码会导致签名故障。

请求形式

艾克索拉直接帐户接受三种类型的请求：

• 支付可能性检查(command = check)
• 支付执行(command = pay)
• 游戏货币花费和金额计算（command = calculate)

Check命令：基于艾克索拉号码识别用户

Check命令：基于project/v1/v2/v3识别用户

Pay命令：基于帐户识别订阅者

Pay命令：基于project/v1/v2/v3识别订阅者

Calculate命令

生成MD5字段

签名用于在支付检查和支付执行时确保安全。签名通过对字符串进行MD5散列生成，该字符串是将发送的所有参数的值按其在请求中的顺序串联所得，并包含可选参数（如有），以及付款系统的私有密钥（可从您的艾克索拉客户成功经理处获得）。

Check命令

 1<?php
 2  $request['command']='check';
 3  $request['account']=1234567;
 4  $request['sum']=150.75;
 5  $request['type']=151;
 6  $request['date']='20110117000516';
 7  $md5='';
 8  foreach ($request as $value) {
 9  $md5.=$value;
10  }
11  $request['md5']=md5($md5.$secret_key);
12?>

行：

check1234567150.7515120110117000516test

MD5：

1cad5a2c3457cffa8e857a507a7050ba

Pay命令

 1<?php
 2$request['command']='pay';
 3$request['account']=1234567;
 4$request['sum']=150.75;
 5$request['id']=384957;
 6$request['type']=151;
 7$request['date']='20110117000516';
 8$md5='';
 9foreach ($request as $value) {
10$md5.=$value;
11}
12$request['md5']=md5($md5.$secret_key);
13?>

行：

pay1234567150.7538495715120110117000516test

MD5：

7cfa05abde4ae2464142bf2ac7a72f32

Calculate命令

 1<?php
 2  $request['command']='calculate';
 3  $request['project']=4783;
 4  $request['out']=12;
 5  $request['type']=151;
 6  $request['date']='20110117000516';
 7  $md5='';
 8  foreach ($request as $value) {
 9  $md5.=$value;
10  }
11  $request['md5']=md5($md5.$secret_key);
12?>

行：

calculate47831215120110117000516test

MD5：

e73e11a9cad00e205358e05254905af5

响应代码

系统生成包含状态代码（在result中）和描述（在comment中）的XML响应。

付款系统交易记录API

该文件面向如下开发者：他们希望借助付款系统交易记录API，让用户能够支付其项目中的虚拟物品和服务。该文件要求具备API、HTTP请求和软件架构方面的基本知识。

与API交互

• 此项操作必须依赖于服务器间集成；

• 所有参数必须采用UTF-8编码；

• 数据以CSV格式返回。

API方法描述

• Get - 接收支付数据。

API URL

基本URL： https://api.xsolla.com/payments/

URL掩码

1https://api.xsolla.com/payments/v<number versions>/<command>?<parameter1=value1>&<parameter2=value2

Get

创建请求，以获取指定交易方的所有付款系统在过去24小时内的支付数据。

获取API访问权限

要获取API访问权限，请联系您的客户成功经理或发送邮件至csm@xsolla.com，以获取唯一的合作伙伴ID及密钥。

请求示例

https://api.xsolla.com/payments/v1/Get?date=2013-08-20&id=1234&sign=8f683701c03b03fe49e6ef7bbfafb8fb

输入参数

响应

回复采用CSV格式，使用英文逗号”,“作为分隔符：

69927355,95188933,394,2013-08-01T06:49:25+04:00,91.0000,RUB,done

字段描述：

生成签名

参数按密钥的字母顺序排列。签名通过对字符串进行MD5散列生成，该字符串由参数值和密钥串联而成（详询帐户经理）。"|“用作分隔符。

请求示例

1date = 2013-08-20;
2id=1234;
3secret_key=password.

该字符串形式如下：

2013-08-20|1234|password

对上述字符串进行MD5散列：

e8df0ff2e4360300a5142cc28d86b422

完成代码列表

付款系统交易对账

通过电子邮件通知对账

交易对账通过来自付款系统、包含特定形式附件的电子邮件进行。对账的频繁程度必须事先商定。

对账文件的形式

对账文件采用以下形式：

• UTF-8编码
• CSV格式（以逗号或分号为分隔符）
• 由事先约定的电子邮件地址发送至stats@xsolla.com
• 邮件标题为：“stats registry”
• 附件名称为：stats_registry_period时间段包含2个日期，格式为YYYY-MM-DD：start_dateTend_date如果时间段为一整天（24小时），则"T"及其后部分可以省略

文件内容

记录示例

示例1

197035765;6654448;10.00;9.50;RUB;done;2011-09-01 13:30:45;nickname
2
397035766;6634558;150.00;145.00;RUB;done;2011-09-01 16:43:54;vassilliy@mail.ru

示例2（如果付款系统中没有pid）

1564;;10.00;9.50;RUB;done;2011-09-01 13:30:45;nickname
2
3456;;150.00;145.00;RUB;done;2011-09-01 16:43:54;vassilliy@mail.ru

示例3（如果没有desc，请留意结尾的分号）

1564;6654855;10.00;9.50;RUB;done;2011-09-01 13:30:45;
2
3456;4588554;150.00;145.00;RUB;done;2011-09-01 16:43:54;

通过付款系统API对账

您还可以使用付款系统的HTTP (HTTPS) API进行交易对账。查询API后，艾克索拉应收到以下参数：