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 заполняется 9 цифрами (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 = calculate).

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

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

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

Команда 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

Коды ответов

Система формирует XML, в котором содержится код статуса result и описание comment.

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 обратитесь к персональному менеджеру проекта или напишите на 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

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

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

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

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

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

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

• Документ присылается в кодировке UTF-8.
• Документ в формате .csv (разделитель запятая или точка с запятой).
• Документ доставляется прикрепленным к письму файлом с заранее указанного и постоянного email-адреса на адрес stats@xsolla.com.
• Тема письма: “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;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 платежной системы. После обращения к Xsolla API должна получить следующие параметры: