自助终端机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 = status）
• 计算游戏货币的价格和数量（command = calculate）

check命令

check命令：按艾克索拉号码识别用户

check命令：按project/v1/v2/v3识别用户

pay命令

pay命令：按帐户识别用户

pay命令：按project/v1/v2/v3识别用户

status命令

您可以通过您系统中的交易ID（id参数）或艾克索拉侧的交易ID（invoice参数）检查支付是否成功。如果同时传递这两个参数，它们必须对应同一笔支付；否则，艾克索拉会返回验证错误。

status命令：按您系统中的交易ID检查支付是否成功

示例：

1https://ps.xsolla.com/api/gate?command=status&id=xsollaid2&type=151&date=20060425180622&md5=0a8d9fb24fcbac2efafec5e51045d05c

status命令：按艾克索拉侧交易ID检查支付是否成功

示例：

1https://ps.xsolla.com/api/gate?command=status&invoice=987654321&type=151&date=20060425180622&md5=0a8d9fb24fcbac2efafec5e51045d05c

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

status命令签名生成（按您系统中的交易ID检查）

 1$request['command'] = 'status';
 2$request['id']      = 'xsollaid2';
 3$request['type']    = 151;
 4$request['date']    = '20110117000516';
 5
 6$md5 = '';
 7foreach ($request as $value) {
 8    $md5 .= $value;
 9}
10$request['md5'] = md5($md5 . $secret_key);

字符串：

statusxsollaid215120110117000516+secret_key

MD5：

7cfa05abde4ae2464142bf2ac7a72f32（示例）

status命令签名生成（按艾克索拉侧交易ID检查）

 1$request['command'] = 'status';
 2$request['invoice'] = 987654321;
 3$request['type']    = 151;
 4$request['date']    = '20110117000516';
 5
 6$md5 = '';
 7foreach ($request as $value) {
 8    $md5 .= $value;
 9}
10$request['md5'] = md5($md5 . $secret_key);

字符串：

status98765432115120110117000516+secret_key

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

响应

响应代码

艾克索拉会生成XML响应，其中result包含状态代码，comment包含状态描述。

错误响应示例：

1<response>
2  <result>7</result>
3  <comment>md5 error</comment>
4</response>

成功响应代码

如果result返回0，响应还会包含payment区块，提供该笔支付的详细信息。支付状态由status参数中的代码表示。

status命令成功响应示例：

 1<response>
 2  <payment>
 3    <invoice>123456789</invoice>
 4    <id>xsollaid2</id>
 5    <sum>100.98</sum>
 6    <project>4783</project>
 7    <v1>XsollaUser</v1>
 8    <date>2026-01-23 12:34:56</date>  <!-- present only when status is succeeded -->
 9    <status>1</status>
10    <comment>succeeded</comment>
11    <statusKioskUrl>https://secure.xsolla.com/pages/status-kiosk?id=123456789&key=9e07b3…</statusKioskUrl>
12  </payment>
13  <result>0</result>
14</response>

支付系统交易记录API

本文档面向希望接入支付系统交易记录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访问权限，请联系您的客户成功经理，或发送邮件至[email protected]，以获取唯一合作伙伴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格式（以逗号或分号作为分隔符）
• 从预先约定的电子邮箱发送至[email protected]
• 邮件主题：“stats registry”
• 附件文件名：stats_registry_period，其中period由start_dateTend_date确定，日期格式为YYYY-MM-DD。如果对账周期为一整天（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;[email protected]

示例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;[email protected]

示例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后，艾克索拉必须收到以下参数：