Cash Kiosks API v2.0

Game catalog API

The API is designed to provide a game catalog, i.e. the list of all projects available in the Xsolla system. The API provides basic information on each project such as project name, project icon, payment parameters, etc. The above-mentioned information can be used to create payment pages for the projects.

The game catalog API can be useful for payments via cash kiosks and placing so-called “game buttons” in their UIs. Replacing the usual Xsolla button replaced with a “game button” on a cash kiosk’s screen allows users to make payments in their favorite projects in an easy and habitual way.

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

Request format

Request parameters for obtaining game list

Generating signature

A signature ensures security when checking and making payments. It is created by MD5-hashing a string taht is a concatenation of the above parameters, separated by “|”, in the order shown below.

1md5(<ID>|<secret_key>)

secret_key: Counterparty’s secret key.

Example: The signature for counterparty #184 with the secret key “SecretKey” is formed as follows:

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

Request Example:

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

Response format

The response is in XML format and contains both the game list and basic information about each game. The XML has the following structure:

 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>

Field description

Response format in case of error

In case of an error, the API will respond with an XML message.

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

Error description

Interaction with agent

Overview

There are two possible interaction options:

• Xsolla button. This button is placed at the agent side. After clicking the button, the user is prompted to enter a number they have received before and make the payment to this number. To enable payments via the Xsolla button, fill in the account field (project, v1, v2, v3 fields must remain empty). The account field must contain the 9-digit Xsolla number. To set up a Xsolla button, contact the manager to obtain a logo and the number.

• Game buttons. These buttons are placed at the agent side, each corresponding to a different game. The user clicks on the button of a particular game and then logs in to make a payment to their own account. To enable payments via game-specific buttons, fill the project, v1, v2 and v3 fields (leave account field empty). You will be able to send project, v1, v2 and v3 fields after the particular project (game) button is configured at the terminal. The project and v1 fields are mandatory, while v2 and v3 are optional and depend on each specific project. To set up game buttons, contact the manager to obtain game logos, game’s internal ids and authorization methods (rules for filling out the v1, v2, v3 fields) and other information for each game.

A button is an element of the agent’s system that initiates a payment through the Xsolla system.

Before connecting the agent to the Xsolla system, make sure to clarify the following:

1. Partner number (type) in the Xsolla system. You can get it by contacting your Customer Success Manager at Xsolla.
2. secret_key, a confidential string parameter that is required to generate the digital signature (MD5 string). You can find it in Publisher Account through your Customer Success Manager.

You can interact with the API by sending HTTP requests to the API gateway at:

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

The API accepts GET or POST requests. All parameters must be UTF-8-encoded, as using non-matching encodings will result in signature issues.

Request format

The requests to Xsolla can be done in the following cases:

• to check whether payment is possible (command = check)
• to make a payment (command = pay)
• to check if the payment was successful (command = status)
• to calculate the cost and amount of game currency (command = calculate)

Check command

Check command: identify user by Xsolla number

Check command: identify user by project/v1/v2/v3

Pay command

Pay command: identify subscriber by account

Pay command: identify subscriber by project/v1/v2/v3

Status command

You can check if the payment was successful either by the transaction ID in your system (the id parameter), or by the transaction ID on the Xsolla side (the invoice parameter). If you pass both parameters, they must belong to the same payment; otherwise, Xsolla returns a validation error.

Status command: check payment success by transaction ID in your system

Example:

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

Status command: check payment success by transaction ID on Xsolla side

Example:

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

Calculate command

Generating MD5 field

The signature ensures secure payments and payment checks. It is generated by taking an MD5 hash of a string derived by concatenating the values of all the parameters transmitted, in the same order in which they follow in request, including optional parameters, if any, and the private key of the payment system, which you can get from your your Xsolla Customer Success Manager.

Check command

 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?>

Line:

check1234567150.7515120110117000516test

MD5:

1cad5a2c3457cffa8e857a507a7050ba

Pay command

 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?>

Line:

pay1234567150.7538495715120110117000516test

MD5:

7cfa05abde4ae2464142bf2ac7a72f32

Status command signature generation (check by transaction ID in your system)

 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);

Line:

statusxsollaid215120110117000516+secret_key

MD5:

7cfa05abde4ae2464142bf2ac7a72f32 (example)

Status command signature generation (check by transaction ID on Xsolla side)

 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);

Line:

status98765432115120110117000516+secret_key

MD5:

7cfa05abde4ae2464142bf2ac7a72f32 (example)

Calculate command

 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?>

Line:

calculate47831215120110117000516test

MD5:

e73e11a9cad00e205358e05254905af5

Responses

Response codes

Xsolla generates an XML containing the status code in result and the description in comment.

Example of response containing error:

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

Successful response codes

If 0 is returned in result, the response also contains the payment block with detailed information about the payment. The payment status is passed in the code in the status parameter.

Example of successful response to Status command:

 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>

Payment system transaction registry API

The document is intended for developers who want to use the payment system transaction registry API to let their users pay for virtual items and services of their project. The document requires basic knowledge of APIs, HTTP requests, and software architectures.

Interacting with API

• The work is only possible via server-server integration;

• All parameters should be UTF-8-encoded;

• Data is returned in CSV format.

Description of API methods

• Get – receive payment data.

API URL

Basic URL: https://api.xsolla.com/payments/

URL mask

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

Get

Creates a request to get data on payments from all payment systems of the given counterparty for the last 24 hours.

Getting API access

To get API access, contact your Customer Success Manager or email to [email protected] to get a unique partner ID and secret key.

Request example

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

Input parameters

Response

The reply is provided in the CSV format, with “,” used as the separator:

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

Field description:

Generating the Signature

The parameters are sorted alphabetically by keys. The signature is an MD5 hash of a string that is a concatenation of parameter values and the secret key (you can learn one from the manager). The separator is “|”.

Request Example

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

The string will look as follows:

2013-08-20|1234|password

MD5 of the above string:

e8df0ff2e4360300a5142cc28d86b422

List of completion codes

Transaction reconciliation with payment systems

Reconciliation via email notification

Transaction reconciliation consists in the payment system’s sending an email with an attachment of a particular format. The frequency of reconciliation must be negotiated in advance.

Reconciliation document format

The reconciliation document has the following format:

• UTF-8 encoding
• CSV format (comma or semicolon as the delimeter)
• Sent from a previously agreed email to [email protected]
• Email subject: “stats registry”
• Attachment file name: stats_registry_period, where period is determined by start_dateTend_date in format YYYY-MM-DD. If the period consists of one day (24 hours), the portion including and after T can be omitted

Document content

Registry example

Example 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]

Example 2 (if there is no pid in the payment system)

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]

Example 3 (if there is no desc — note the semicolon at the end)

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;

Reconciliation via payment system API

Transaction reconciliation can also be done via the payment system’s HTTP (HTTPS) API. After querying the API, Xsolla must receive the following parameters: