Ежедневные бонусы

Ежедневные бонусы — вознаграждение, которое получает пользователь в игре при покупке премиум-подписки. Каждая премиум-подписка имеет свой набор бонусов.

Пользовательский сценарий

Сценарий подключения

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

Для подключения модуля необходимо:

Зарегистрироваться в Личном Кабинете Xsolla.
Создать проект.
Настроить модуль.
Настроить бонусы для премиум-плана.
Получить токен.
Настроить открытие магазина.
Настроить обработку оповещений.
Протестировать процесс оплаты.
Запустить модуль и подписать договор.

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

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

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

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

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

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

Перейдите в настройки модуля Подписки и нажмите кнопку Создать новый план рекуррентных платежей. Задайте следующие параметры:
a. Название.
b. Платежный цикл.
Нажмите кнопку Создать.
Нажмите ссылку Вернуться к списку рекуррентных планов для возврата к основным настройкам модуля и создайте другие планы.

Обратите внимание! План создается только для одной валюты. Для каждой валюты проекта необходимо создать отдельный набор планов.

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

Вы можете включить в премиум-план следующие бонусы:

Индивидуальная скидка на товары и пакеты внутриигровой валюты в магазине.
Периодическое начисление внутриигровой валюты.
Периодическая выдача товаров. Пользователь может получать:
- Случайные товары из списка. Набор товаров и вероятность выпадения каждого товара определяются настройками проекта.
- Определенные товары в последовательности, заданной в настройках проекта.

Обратите внимание! В зависимости от выбранного бонуса необходимо дополнительно настроить модуль Виртуальные товары и/или Виртуальная валюта.

Для настройки бонусов необходимо отправить запрос на integration@xsolla.com.

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

Для интеграции магазина необходимо получить токен. Токен — это строка, в которой содержится информация об игре, пользователе и параметрах платежа. 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.

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

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

Данные, переданные в запросе от сервера Xsolla, и секретный ключ проекта (генерируется на странице настройки проекта) конкатенируются в строку.
Полученная строка хешируется с помощью SHA1 хеш-алгоритма.
Подпись передается в 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

<?php
$request = array(
    'notification_type' => 'create_subscription',
    'user' => (
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => (
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_next_charge' => '2015-01-22T19:25:25+04:00',
        'trial' =>  (
                'value' =>  90,
                'type' =>  'day'
            )
    )
);

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"create_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_next_charge":"2015-01-22T19:25:25+04:00",
            "trial": {
                    "value": 90,
                    "type": "day"
                }
        }
    }'

Полный список параметров доступен в справочнике 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

<?php
$request = array(
    'notification_type' => 'update_subscription',
    'user' => (
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => (
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_next_charge' => '2015-01-22T19:25:25+04:00'
    )
);

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"update_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_next_charge":"2015-01-22T19:25:25+04:00"
        }
    }'

Полный список параметров доступен в справочнике 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.

Отмена подписки

Если подписка была отменена, сервер Xsolla отправляет проекту оповещение.

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

PHP

CURL

<?php
$request = array(
    'notification_type' => 'cancel_subscription',
    'user' => (
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => (
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_end' => '2015-01-22T19:25:25+04:00',
    )
);

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"cancel_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_end":"2015-01-22T19:25:25+04:00"
        }
    }'

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

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

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

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

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

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

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

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

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

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

Запуск

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

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

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