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

Подписки

Подписки — модуль продажи подписок, который позволяет пользователю получить доступ к сервису на определенный период. Модуль имеет следующие возможности:

  • Управление подписками через личный кабинет пользователя — просмотр подробной информации, просмотр истории платежей по подпискам, смена плана, приостановка действия подписки, продление, отмена
  • Управление подписками через Личный Кабинет Xsolla - создание и настройка планов для каждой валюты, триальный период действия подписки, период отсрочки платежа по подписке, просмотр пользователей подписки, изменение статуса подписки пользователя
  • Автоматическое продление подписки по сохраненному платежному аккаунту
  • Продление подписки вручную

Статусы подписок

Подписка может находиться в одном из следующих статусов:

  • Active. Основной статус подписки. Подписка создается и активируется после первого успешного платежа. Повторные списания средств осуществляются только у активных подписок.
  • Canceled. Подписка отменена. При переходе в статус Canceled подписка перестает действовать немедленно. Возможные причины отмены:

    • Изменился статус подписки через вызов API метода или настройки в Личном Кабинете Xsolla.
    • Пользователь отменил подписку.
    • Закончился срок действия подписки (если был задан параметр expiration date).
    • Превышено максимальное количество попыток списания средств при продлении подписки (значение по умолчанию - 3, может быть изменено через обращение к аккаунт-менеджеру проекта).
    • Пользователь, у которого была данная подписка, не был найден при проверке существования пользователя в игре.
    • Платежный аккаунт пользователя, к которому привязана данная подписка, был удален.
  • Non renewing. Продление подписки отменено. Подписка будет действовать до окончания текущего платежного цикла и затем перейдет в статус Canceled. Возможные причины отмены продления:

    • Изменился статус подписки через вызов API метода или настройки в Личном Кабинете Xsolla.
    • Пользователь отменил продление по ссылке в письме.
    • Платежный аккаунт пользователя, к которому привязана данная подписка, был удален.

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

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

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

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

  • 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. Включите модуль Подписки.

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

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

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

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

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

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

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

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

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

  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. Подписать договор.

Предотвращение фрода при помощи игровых параметров

Объект custom_parameters, переданный в токене, может использоваться для отправки игровых данных пользователя и обнаружения подозрительной активности. Так, игрок с низким количеством игрового времени и высоким игровым уровнем может быть мошенником, который создал аккаунт для продажи и "прокачал" его при помощи украденных банковских карт.

Список доступных параметров

Сообщите вашему аккаунт-менеджеру, какие параметры вы планируете передавать, и значения каждого из них. Эта информация будет использована для настройки антифрод-фильтров.

Оплата выбранным способом

При открытии магазина вы можете передавать id способа оплаты в параметре settings.payment_method. В этом случае пользователь сразу перенаправляется на платежную форму выбранного способа оплаты.

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

CURL
    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"
            },
        },
        "settings": {
            "project_id": 14004,
            "payment_method": 24
        }
    }'

Список id способов оплаты можно получить в Личном Кабинете в разделе Платежные системы или с помощью метода Список платежных систем.

Покупка выбранного плана

При открытии магазина вы можете передавать ID плана в параметре purchase.subscription.plan_id. В этом случае пользователь сразу перенаправляется в платежный интерфейс.

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

CURL
    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"
            },
        },
        "settings": {
            "project_id": 14004
        },
        "purchase": {
            "subscription": {
                "plan_id": 123
                },
        }
    }'

Отмена последнего платежа при отмене подписки

При отмене подписки вы можете отменить последний совершенный платеж с помощью метода Изменение подписки, используя параметр cancel_subscription_payment. Вы также можете дать возможность пользователю возвращать последний платеж при отмене подписки. Для подключения опции, пожалуйста, обратитесь к аккаунт-менеджеру проекта.

Смена плана

Вы можете сменить план подписки с помощью метода Изменение плана. Новый план начнет действовать со следующего периода.

Смена плана невозможна, если:

  • у пользователя уже есть активная подписка с данным планом;
  • подписка находится в статусах Canceled или Non renewing;
  • период пользования подпиской - триальный.

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

Продление подписки вручную

По умолчанию продление подписки осуществляется автоматически с сохраненного платежного аккаунта пользователя. Вы можете разрешить пользователю продлевать подписки вручную с помощью способов оплаты, которые не поддерживают сохранение платежного аккаунта и автоматическое списание средств. Чтобы продлить подписку по окончании платежного цикла, пользователь будет переходить по ссылке из письма. Для подключения опции, пожалуйста, обратитесь к аккаунт-менеджеру проекта.

Использование продуктов

Если в разных подписках используются одинаковые планы, вы можете продавать подписки в составе продукта. Продукт - совокупность планов, входящих в одну группу, на которые может подписаться пользователь. Один и тот же план можно использовать для разных продуктов.

Для настройки продуктов используются следующие методы API: создание, изменение, удаление продукта, список всех продуктов.

Начисление бонусов

Модуль подписок позволяет при продлении подписки начислять пользователям бонусы: игровую валюту или товары. Для подключения опции необходимо дополнительно подключить модули Виртуальная валюта и/или Виртуальные товары и обратиться к аккаунт-менеджеру проекта.