The following documentation was deprecated. Current version is available at developers.xsolla.com

Лутбоксы

Лутбоксы — наборы игровых предметов и/или виртуальной валюты, которые пользователь может купить или получить в качестве вознаграждения. Содержимое лутбокса формируется случайным образом и неизвестно пользователю до открытия.

Модуль лутбоксов имеет несколько вариантов интеграции и предлагает игровым проектам следующие возможности:

  • Способ выдачи лутбокса — по инициативе игры или через покупку в магазине
  • Варианты покупки лутбокса — за реальную или виртуальную валюту
  • Способ открытия лутбокса — за реальную валюту, за виртуальную валюту, с помощью ключа, купленного за реальную или виртуальную валюту
  • Настройка вероятности выпадения предмета или пакета виртуальной валюты
  • Настройка вероятности выпадения по свойству предмета
  • Анимация открытия лутбокса

Руководство по интеграции

Доступны следующие возможности:

  • Добавление лутбокса в инвентарь пользователя через покупку или событие в игре
  • Анимация добавления предметов в инвентарь пользователя
  • Анимация при открытии лутбокса
  • Удаление лутбокса из инвентаря после открытия

Для работы с лутбоксами необходимо:

  1. Зарегистрироваться в Личном Кабинете Xsolla.
  2. Создать проект.
  3. Настроить модуль.
  4. Настроить лутбоксы.
  5. Получить токен.
  6. Настроить открытие магазина.
  7. Настроить обработку оповещений.
  8. Протестировать процесс оплаты.
  9. Запустить модуль и подписать договор.

В процессе интеграции понадобятся следующие параметры:

  • ID мерчанта. Отображается в URL Личного Кабинета — https://publisher.xsolla.com/{merchant_id}/.
  • Ключ API. Генерируется в Личном Кабинете в разделе Настройки -> Компания.
  • ID проекта. Отображается в URL Личного Кабинета при переходе в настройки проекта — https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.
  • Секретный ключ проекта. Генерируется на странице настройки проекта.

Создание проекта

  1. Перейдите в раздел Проекты и нажмите кнопку Создать проект.
  2. В настройках проекта:
    a. Укажите URL оповещений.
    b. Сгенерируйте секретный ключ проекта для подписи оповещений.
    c. Включите модуль Виртуальные товары.
    d. Перейдите в раздел Пользователи и установите переключатель Хранить данные пользователей в Xsolla в положение Вкл.

Настройка модуля

Перед началом настройки лутбоксов необходимо создать каталог виртуальных товаров, которые будут входить в состав лутбоксов.

  1. Перейдите в настройки модуля Товары и нажмите кнопку Создать группу товаров. Задайте настройки группы:
    a. Место в каталоге. По умолчанию группа будет располагаться в корне.
    b. Код.
    c. Название и описание.
    d. Если группа должна отображаться в магазине, необходимо установить флажок Показывать в магазине.
  2. Нажмите кнопку Создать.
  3. Нажмите ссылку Список товаров для возврата к основным настройкам модуля и создайте другие группы, необходимые для структуры вашего каталога.
  4. Нажмите кнопку Создать товар и укажите следующие параметры:
    a. Одну или несколько групп, которым должен принадлежать товар. Товар, не принадлежащей ни одной из групп, в магазине не отображается.
    b. SKU — уникальный идентификатор.
    c. Название и краткое описание.
    d. Стоимость в реальной валюте.
    e. Изображение.
  5. Нажмите кнопку Создать.
  6. Нажмите ссылку Список товаров для возврата к основным настройкам модуля и создайте другие товары.

Настройка лутбоксов

Лутбокс — набор из нескольких позиций, или слотов. В момент открытия лутбокса каждый слот заполняется случайным предметом. Список предметов и вероятность их попадания в слот определяются заранее.

Метод CREATE LOOTBOXES позволяет создать набор лутбоксов и настроить:

  • Количество слотов лутбокса.
  • Таблицу вероятностей выпадения предметов из каждого слота.
  • Таблицу вероятностей выпадения предметов по свойству из каждого слота.
  • Вероятность попадания в лутбокс пустого слота.
  • Возможность замены дубликатов предметов количеством виртуальной валюты (процент от стоимости или конкретное значение).

Полный список методов и параметров доступен в справочнике API.

Получение токена магазина

Для интеграции магазина необходимо получить токен. Токен — это строка, в которой содержится информация об игре, пользователе и параметрах платежа. Xsolla API использует Basic HTTP-аутентификацию. Укажите свой ID мерчанта в качестве username и ключ API в качестве password.

Для получения доступа к sandbox-режиму используется параметр "mode" = "sandbox".

URL получения токена:

https://api.xsolla.com/merchant/merchants/{merchant_id}/token

В HTTP POST запросе вы можете указать параметры, которые нужно передать на платежный интерфейс. Запрос и ответ передаются в JSON формате.

Ниже указан пример получения токена на PHP с использованием Xsolla PHP SDK. Если вы разрабатываете на другом языке, можно использовать CURL пример (нажмите на кнопку CURL).

PHP
CURL
<?php

use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;

$tokenRequest = new TokenRequest($projectId, $userId);
$tokenRequest->setUserEmail('email@example.com')
    ->setExternalPaymentId('12345')
    ->setSandboxMode(true)
    ->setUserName('USER_NAME')
    ->setCustomParameters(array('key1' => 'value1', 'key2' => 'value2'));

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);
    curl -v https://api.xsolla.com/merchant/merchants/{merchant_id}/token \
    -X POST \
    -u your_merchant_id:merchant_api_key \
    -H 'Content-Type:application/json' \
    -H 'Accept: application/json' \
    -d '
    {
        "user": {
            "id": {
                "value": "1234567"
            },
            "email": {
                "value": "email@example.com"
            }
        },
        "settings": {
            "project_id": 14004,
            "mode": "sandbox"
        }
    }'

Полный список параметров доступен в справочнике API.

Открытие магазина

Доступны следующие способы открытия магазина:

  • с помощью скрипта Pay Station Embed;
  • в новом окне;
  • в iframe.

Для открытия магазина в sandbox-режиме используйте URL https://sandbox-secure.xsolla.com/.

Pay Station Embed

Скрипт Pay Station Embed определяет тип устройства и открывает магазин в lightbox (для полноэкранной версии) или в новом окне (для мобильных устройств и планшетов). Рекомендуется использовать асинхронную загрузку скрипта.

Пример асинхронной загрузки

 <script>
     var options = {
         access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
         sandbox: true //TODO please do not forget to remove this setting when going live
     };
     var s = document.createElement('script');
     s.type = "text/javascript";
     s.async = true;
     s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
     s.addEventListener('load', function (e) {
         XPayStationWidget.init(options);
     }, false);
     var head = document.getElementsByTagName('head')[0];
     head.appendChild(s);
 </script>

<button data-xpaystation-widget-open>Buy Credits</button>

Полный список параметров инициализации скрипта доступен в справочнике API.

Новое окно

Для открытия магазина в новом окне используется ссылка https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, где ACCESS_TOKEN — токен, полученный на предыдущем шаге.

Iframe

Чтобы открыть магазин в iframe, необходимо реализовать:

  • определение типа устройства (desktop или mobile) и передачу значения в токене в параметре settings.ui.version;
  • механизм postMessage для получения событий от платежного интерфейса.

Для открытия магазина в новом окне используется ссылка https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN, где ACCESS_TOKEN — токен, полученный на предыдущем шаге.

Настройка оповещений

Xsolla отправляет проекту следующие типы оповещений (webhooks):

  • Проверка существования пользователя
  • Успешный платеж
  • Изменение содержимого инвентаря
  • Отмена платежа

Чтобы подтвердить получение оповещения, ваш сервер должен вернуть 204 HTTP код без тела сообщения. Механизм работы оповещений с примерами обработки подробно описан в справочнике API.

Формирование подписи

Процесс формирования подписи включает следующие шаги:

  1. Данные, переданные в запросе от сервера Xsolla, и секретный ключ проекта (генерируется на странице настройки проекта) конкатенируются в строку.
  2. Полученная строка хешируется с помощью SHA1 хеш-алгоритма.
  3. Подпись передается в Signature заголовке.

При обработке оповещения необходимо проверить, что полученная подпись и подпись, переданная в Signature заголовке, совпадают.

Проверка существования пользователя

Сервер Xsolla посылает запрос на URL оповещений проекта, чтобы проверить существование персонажа в игре.

Пример запроса

PHP
CURL
$request = array(
    'notification_type' => 'user_validation',
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email'=> 'email@example.com',
        'id'=> '1234567',
        'country' => 'US'
    )
)
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type": "user_validation",
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "country": "US"
    }
}'

Полный список параметров доступен в справочнике API.

Успешный платеж

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

Пример запроса

PHP
CURL
$request = array(
    'notification_type' => 'payment',
    'purchase' => array(
        'virtual_items' => array(
            'items' => array(
                0 => array(
                    'sku' => 'test_item1',
                    'amount' => 1,
                    ),
                1 => array(
                    'sku' => 'test_item2',
                    'amount' => 1,
                    ),
                2 => array(
                    'sku' => 'test_item3',
                    'amount' => 1,
                    ),
            )
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        )
    )
)
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type": "payment",
    "purchase": {
        "virtual_items": {
            "items": [
                {
                    "sku": "test_item1",
                    "amount": 1
                },
                {
                    "sku": "test_item2",
                    "amount": 1
                },
                {
                    "sku": "test_item3",
                    "amount": 2
                },
            ]
        },
        "total": {
            "currency": "USD",
            "amount": 9.99
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "country": "US"
    },
    "transaction": {
        "id": 87654321,
        "payment_date": "2014-09-23T19:25:25+04:00",
        "payment_method": 1380,
        "dry_run": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 9.99
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "payout_currency_rate": 1,
        "payout": {
            "currency": "USD",
            "amount": 9.49
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 0.19
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 0.31
        }
    }
}'

Полный список параметров доступен в справочнике API.

Изменение содержимого инвентаря

Когда изменяется содержимое инвентаря пользователя (добавляются или удаляются предметы), сервер Xsolla отправляет проекту оповещение.

Пример запроса

PHP
CURL
$request = array(
    'virtual_currency_balance' => (
            'old_value' => '0',
            'new_value' => '200',
            'diff' => '200'
    ),
    'user' => (
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'inGamePurchase',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989'
);
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"200",
        "diff":"200"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"semail@example.com
    },
    "operation_type":"inGamePurchase",
    "notification_type":"user_balance_operation",
    "items_operation_type": "add",
         "items": [{
         "sku": "1468",
         "amount": "2"
         }],
    "id_operation":"66989"
}'

Полный список параметров доступен в справочнике API.

Отмена платежа

Если пользователь отменяет платеж, сервер Xsolla отправляет проекту оповещение с информацией о платеже.

Пример запроса

PHP
CURL
$request = array(
    'notification_type' => 'refund',
    'purchase' => array(
        'virtual_currency' => array(
            'name' => 'Coins',
            'quantity' => 100,
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'refund_details' => (
            'code' => 1,
            'reason' => 'Fraud'
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        )
    )
);
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
    "notification_type":"refund",
    "purchase":{
        "virtual_currency":{
            "name": "Coins",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "date_create": "2014-09-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout":{
            "currency":"USD",
            "amount":50
        },
        "virtual_items":{
            "items":[
                {
                    "sku": "test_item1",
                    "amount":1
                }
            ],
            "currency":"USD",
            "amount":50
        },
        "total":{
            "currency":"USD",
            "amount":200
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "dry_run":1,
        "agreement":1
    },
    "refund_details":{
        "code":1,
        "reason":"Fraud"
    },
    "payment_details":{
        "xsolla_fee":{
            "currency":"USD",
            "amount":"10"
        },
        "payout":{
            "currency":"USD",
            "amount":"200"
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":"20"
        },
        "payment":{
            "currency":"USD",
           "amount":"230"
        }
    }
}'

Полный список параметров доступен в справочнике API.

Тестирование оповещений

Чтобы протестировать обработчик оповещений:

  1. Откройте настройки модуля в Личном Кабинете.
  2. Перейдите на вкладку Тестирование.
  3. Введите тестовые данные и нажмите кнопку Запустить тесты: сервер Xsolla отправит все типы оповещений.
  4. Если скрипт вернул корректный ответ, тест помечается зеленым цветом, в случае ошибки — красным.

Тестирование процесса оплаты

Xsolla Sandbox ("песочница") — это автономная рабочая среда, в которой доступны все функции Live режима, кроме проведения реальных платежей. Вы можете получить доступ к Sandbox, отправив параметр "mode = "sandbox" при получении токена.

Тестирование оплаты банковской картой:

  1. Откройте магазин в sandbox-режиме.
  2. Выберите предмет покупки.
  3. Выберите группу способов оплаты Банковские карты.
  4. Введите реквизиты карты из таблицы ниже. Остальные поля могут быть заполнены любыми данными. Вы также можете указать неверные реквизиты (номер карты, срок действия или CVV) для генерации ошибки.

Список банковских карт для тестирования

Обратите внимание! Платежи банковской картой в sandbox-режиме могут быть проведены только в валюте USD, EUR, RUB, GBP, SGD, HKD или THB.

Запуск

Чтобы запустить модуль после успешно пройденного тестирования, откройте настройки модуля Виртуальные товары в Личном Кабинете, перейдите на вкладку Запуск и установите переключатель в положение Вкл.

Обратите внимание! Чтобы начать принимать реальные платежи, необходимо:

  1. Удалить "sandbox" режим.
  2. Подписать договор.

Открытие лутбокса на стороне игры

При открытии лутбокса на стороне игры доступны следующие возможности:

  • Проверка наличия лутбокса в инвентаре пользователя
  • Получение списка выпавших предметов
  • Добавление предметов в инвентарь пользователя
  • Удаление лутбокса из инвентаря после открытия

Для подключения опции, пожалуйста, обратитесь к аккаунт-менеджеру проекта.

Анимация открытия лутбокса

Если открытие лутбокса происходит на стороне Xsolla, вы можете добавить анимацию, привязанную к результатам открытия. Для подключения опции, пожалуйста, обратитесь к аккаунт-менеджеру проекта.