Xsolla Documentation - Подписки

Подписки — решение, которое позволяет предоставлять пользователю доступ к пакету услуг по заданным условиям. Основные возможности:

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

Глоссарий

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

Продукт подписки — услуга или пакет услуг, предоставляемые пользователю при подписке.

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

ПРИМЕР 1

Продукт: Доступ к игре

План подписки Silver: $10 за 1 месяц
План подписки Gold: $100 за 1 год

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

Подписка 1: Доступ к игре за $10 в месяц
Подписка 2: Доступ к игре за $100 в год

ПРИМЕР 2

Продукт 1: Доступ к игре1

Продукт 2: Доступ к игре2

План подписки: $10 за 1 месяц

Пользователь может одновременно оформить две подписки:

Подписка 1: Доступ к игре1 за $10 в месяц
Подписка 2: Доступ к игре2 за $10 в месяц

Note: Если продукт подписки не настроен, пользователь может оформить только одну подписку одновременно. Чтобы у пользователя появилась возможность оформить несколько подписок одновременно, необходимо настроить продукты.

Как это работает

Шаг 1

Шаг 2

Шаг 3

Сценарий пользователя

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

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

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

Notice: Подписку нельзя создать вручную, через API. Она создается только автоматически при совершении покупки.

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

Note: Отмена подписки может осуществляться с возвратом последнего платежа. Данная опция доступна и для партнера, и для пользователя.

Non renewing. Продление подписки отменено. Подписка будет действовать до окончания текущего платежного цикла и затем перейдет в статус Canceled. Возможные причины отмены продления:
- Изменился статус подписки через вызов API метода или настройки в Личном кабинете Иксолла.
- Пользователь отменил продление по ссылке в письме.
- Платежный аккаунт пользователя, к которому привязана данная подписка, был удален.

Сценарий интеграции

Чтобы подключить Подписки:

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

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

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

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

Настройка плана

Перейдите в настройки модуля Подписки: Проект > Магазин > Подписки.
Задайте следующие параметры:
- Название
- Платежный цикл.

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

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

Для решения Подписки необходимо реализовать обработку следующих типов оповещений:

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

Чтобы протестировать оповещения, перейдите в раздел Оповещения в настройках проекта.

Получение токена

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

API Иксоллы использует базовую HTTP-аутентификацию. Укажите свой ID продавца в качестве username и ключ API в качестве password.

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

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

Запрос на получение токена

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

Ниже указан пример получения токена на PHP с использованием PHP SDK. Если вы разрабатываете на другом языке, можно использовать CURL пример (нажмите на кнопку 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');

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);

curl -v https://api.xsolla.com/merchant/v2/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.

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

Для тестирования процесса оплаты вы можете:

использовать тестовое окружение;
провести реальный платеж, а затем сделать возврат через Личный кабинет.

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

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

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

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

Note: Платежи банковской картой в тестовом окружении могут проводиться в следующих валютах: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.

Notice: Удалите "mode":"sandbox" перед тем, как начать принимать реальные платежи.

Для тестирования оплаты на реальных платежах рекомендуется также использовать банковскую карту:

Откройте интерфейс подписок.
Выберите предмет покупки.
Выберите группу способов оплаты Банковские карты.
Введите реквизиты действующей карты.
После оплаты перейдите в Личный кабинет в раздел Поиск транзакций.
Выберите тестовую транзакцию и нажмите Возврат (транзакция должна находиться в статусе Выполнена).

Note: Для тестирования оплаты рекомендуется использовать карты Visa и MasterCard.

Открытие интерфейса подписок

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

Настройка продукта

Управление продуктами подписки осуществляется через методы API.

Способы продвижения

Купоны

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

Посмотреть рецепт

Бонусы

Бонус позволяет пользователям получать дополнительные товары, когда они покупают подписку.

Посмотреть рецепт

Рецепты

Изучите наши рецепты, чтобы попробовать расширенные возможности решения Подписки: