API платежных терминалов v2.0

API каталога игр

API предназначена для получения каталога игр — списка всех доступных проектов в Xsolla. API предоставляет всю основную информацию по каждому проекту, такую как: название, значок проекта, параметры, необходимые для оплаты. Эта информация может быть использована для составления страницы оплаты в проекте.

API каталога игр полезен терминальным способам оплаты, желающим разместить кнопки игр в своем интерфейсе. Наличие кнопок игр вместо кнопки Xsolla в терминале позволит пользователю просто и привычно оплатить покупку в игре.

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>

Описание ошибок

Взаимодействие с агентом

Общие положения

Возможны два варианта взаимодействия:

• Кнопка Xsolla. Данная кнопка располагается у агента, оплата по ней происходит следующим образом: при выборе кнопки Xsolla пользователю требуется ввести заранее полученный номер и осуществить оплату на него. Соответственно, для оплаты на кнопку Xsolla необходимо заполнить поле account (поля project, v1, v2, v3 не заполняются). В поле account должен быть девятизначный Xsolla-номер. Для размещения кнопки Xsolla обратитесь к менеджеру для получения логотипа и номера.

• Кнопки игр. Данные кнопки располагаются у агента, каждая кнопка соответствует отдельной игре. Пользователь нажимает на кнопку конкретной игры, авторизуется и осуществляет оплату на свой аккаунт. Соответственно, для оплаты на кнопку игр необходимо заполнить поля project, v1, v2, v3 (поле account не заполняется). Возможность посылать project, v1, v2, v3 появляется после того, как в терминале будет установлена кнопка конкретного проекта (игры). Причем поля project и v1 являются обязательными, а v2 и v3 — опциональными (их наличие или отсутствие зависит от конкретного проекта). Чтобы разместить кнопки игр, обратитесь к менеджеру для получения логотипов игр, их внутренних номеров, способов авторизации (правил задания v1, v2, v3), а также другой информации по каждой игре.

Кнопка — элемент в системе агента, активация которого инициирует оплату в Xsolla.

Перед подключением агента к Xsolla необходимо уточнить:

1. Партнерский номер (type) в Xsolla. Вы можете узнать его, обратившись к вашему аккаунт-менеджеру.
2. secret_key — конфиденциальный строковый параметр, необходимый для формирования цифровой подписи (md5-строки). Его можно узнать в Личном кабинете или у персонального менеджера проекта.

Взаимодействие с API происходит путем создания HTTP-запроса к шлюзу API по адресу:

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

Любой запрос передается методами GET или POST, все параметры должны быть в кодировке UTF-8. Обращаем внимание, что использование кодировки UTF-8 важно, поскольку при использовании разных кодировок подписи сходиться не будут.

Формат запроса

Запросы к Xsolla могут выполняться для того, чтобы:

• проверить возможность проведения платежа (command = check)
• выполнить платеж (command = pay)
• проверить успешность платежа (command = status)
• рассчитать стоимость и количество игровой валюты (command = calculate)

Команда check

Команда check: идентификация пользователя по Xsolla-номеру

Команда check: идентификация пользователя по project/v1/v2/v3

Команда pay

Команда pay: идентификация пользователя по account

Команда pay: идентификация пользователя по project/v1/v2/v3

Команда status

Вы можете проверить успешность платежа либо по ID транзакции в вашей системе (параметр id), либо по ID транзакции на стороне Xsolla (параметр invoice). Если вы передаете оба параметра, они должны относиться к одному платежу; в противном случае Xsolla возвращает ошибку валидации.

Команда status: проверка успешности платежа по ID транзакции в вашей системе

Пример:

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

Команда status: проверка успешности платежа по ID транзакции на стороне Xsolla

Пример:

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 транзакции на стороне Xsolla)

 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

Ответы

Коды ответов

Xsolla формирует 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, запросах HTTP и архитектуре программного обеспечения.

Взаимодействие с API

• Работа происходит только по схеме интеграции сервер-сервер;

• Все параметры должны быть в кодировке UTF-8;

• Формат возвращения данных: csv.

Описание методов API

• Get – запрос на получение данных платежей.

URL-адрес API

Базовый URL: https://api.xsolla.com/payments/

Маска формирования URL

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

GET

Команда создает запрос на передачу данных о платежах от всех платежных систем данного контрагента за 24 часа.

Получение доступа

Для получения доступа к 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

Список кодов завершения

Сверки по транзакциям с платежной системой

Сверки через email-оповещения

Сверки по транзакциям производятся путем отправки платежной системой письма с прикрепленным документом, имеющим определенный формат. Частота проведения сверок оговаривается заранее.

Формат документа

Формат документа:

• Документ присылается в кодировке UTF-8.
• Документ в формате .csv (разделитель запятая или точка с запятой).
• Документ доставляется прикрепленным к письму файлом с заранее указанного и постоянного email-адреса на адрес [email protected].
• Тема письма: “stats registry”.
• Формат наименования документа: stats_registry_period. Период задается двумя датами в формате YYYY-MM-DD:start_dateTend_date. Если период включает в себя один день (за одни сутки), указывать 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 платежной системы. После обращения к Xsolla API должна получить следующие параметры: