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: Если продукт подписки не настроен, пользователь может оформить только одну подписку одновременно. Чтобы у пользователя появилась возможность оформить несколько подписок одновременно, необходимо настроить продукты.

Льготный период

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

Льготный период предусмотрен только для подписок c единоразовым платежом. Для автопродлеваемых подписок средства списываются автоматически.
Длительность льготного периода можно изменять в настройках плана подписки в Личном Кабинете Иксолла.
Система уведомляет пользователя о необходимости произвести оплату в момент активации льготного периода и каждый последующий день действия льготного периода.
При оплате пользователем подписки во время действия льготного периода, оплата производится за полный платежный период. Количество дней, которое пользователь находился в льготном периоде, вычитается из общего числа доступных пользователю дней, так как они считаются использованными.
Если в настройке плана в поле Льготный период установлено значение 0, такой план не имеет льготного периода.

Количество попыток списания

Количество попыток списания — количество попыток повторного списания средств для автоматического продления подписки. Настраивается только для автопродлеваемых подписок с сохраненным платежным аккаунтом и активируется при неудачном автоматическом списании. Особенности:

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

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

Шаг 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/paystation3/?access_token=ACCESS_TOKEN, где ACCESS_TOKEN — токен, полученный на предыдущем шаге. Для тестирования используйте URL https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.

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

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

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

Купоны

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

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

Бонусы

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

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

Рецепты

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

Спасибо за обратную связь!

Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.

Your browser is not supported. Please try a different browser

Подписки

Глоссарий

План подписки

Продукт подписки

Подписка

Льготный период

Количество попыток списания

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

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

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

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

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

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

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

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

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

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

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

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

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

Купоны

Бонусы

Рецепты