Перейти к содержимому

Subscriptions API (2.0)

Введение

  • Версия: 2.0
  • Серверы: https://api.xsolla.com/merchant/v2/

Этот справочник API описывает методы для управления подписками, купонами и акциями. Подробная информация о продукте Subscriptions приведена в руководстве по продукту и глоссарии.

Скачать описание OpenAPI
index.json
index.yaml
Языки
Серверы
Mock server
https://xsolla.redocly.app/_mock/ru/api/subscriptions/

Токен

Операции

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

Запрос

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

Если какой-либо параметр отправлен в неправильном формате или имеет неправильный тип, токен выдан не будет. Вы получите HTTP-код 422 с описанием ошибки в JSON-формате. В extended_message вы получите информацию о том, какие именно параметры были отправлены неправильно.

Внимание

Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах.

Безопасность
basicAuth
Путь
merchant_idintegerобязательный

ID продавца.

Телоapplication/jsonобязательный
custom_parametersobject

Вы можете передавать в токене в объекте custom_parameters дополнительные параметры, которые могут использоваться для настройки антифрод-фильтров. Рекомендуемые параметры приведены в раскрывающемся списке. Подробнее в документации по продукту Pay Station.

custom_parameters.​active_datestring

Дата последнего посещения согласно стандарту ISO 8601.

custom_parameters.​additional_verificationboolean

Использует ли игрок дополнительные способы защиты аккаунта.

custom_parameters.​character_customizedboolean

Настраивал ли игрок персонажа.

custom_parameters.​chat_activityboolean

Пишет ли игрок в чате.

custom_parameters.​completed_tasksinteger

Количество выполненных заданий.

custom_parameters.​forum_activityboolean

Пишет ли игрок в форуме.

custom_parameters.​items_usedboolean

Использует ли игрок купленные в игре предметы.

custom_parameters.​karma_pointsinteger

Карма игрока.

custom_parameters.​last_change_password_datestring

Дата последней смены пароля согласно стандарту ISO 8601.

custom_parameters.​non_premium_currencyinteger(float)

Сумма непремиальной валюты игрока.

custom_parameters.​notifications_enabledboolean

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

custom_parameters.​profile_completedboolean

Добавил ли игрок дополнительную информацию в профиль.

custom_parameters.​profile_image_addedboolean

Загрузил ли игрок изображение профиля.

custom_parameters.​pvp_activityboolean

Участвует ли игрок в PvP.

custom_parameters.​registration_datestring

Дата регистрации аккаунта согласно стандарту ISO 8601.

custom_parameters.​session_timestring

Период времени, который пользователь проводит в игре, согласно стандарту ISO 8601.

custom_parameters.​social_networks_addedboolean

Подключил ли игрок профили в социальных сетях.

custom_parameters.​total_bansinteger

Количество банов игрока в чате/на форуме.

custom_parameters.​total_charactersinteger

Количество персонажей игрока.

custom_parameters.​total_clansinteger

Количество кланов, в которых состоит игрок.

custom_parameters.​total_friendsinteger

Количество друзей игрока.

custom_parameters.​total_game_eventsinteger

Количество внутриигровых событий, в которых участвовал игрок.

custom_parameters.​total_giftsinteger

Количество подарков, отправленных или полученных игроком.

custom_parameters.​total_hoursinteger

Общее количество часов, проведенных в игре.

custom_parameters.​total_inventory_valueinteger(float)

Суммарная стоимость инвентаря во внутриигровой валюте.

custom_parameters.​total_suminteger(float)

Общая сумма платежей.

custom_parameters.​tutorial_completedboolean

Завершил ли игрок обучение в игре.

custom_parameters.​unlocked_achievementsinteger

Количество разблокированных умений.

custom_parameters.​user_levelinteger

Уровень игрока, репутация или ранг.

custom_parameters.​win_rateinteger

Рейтинг побед игрока.

purchaseobject

Объект с информацией о заказе.

Пример: {"checkout":{"amount":10,"currency":"USD"},"subscription":{"gift":{"email":"recipient_email@email.com","recipient":"test_recipient_v1"}}}
purchase.​checkoutobject

Объект с информацией о заказе.

Пример: {"amount":10,"currency":"USD"}
purchase.​checkout.​amountinteger(float)

Сумма заказа.

Пример: 10
purchase.​checkout.​currencystring

Валюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.

Пример: "USD"
purchase.​subscriptionobject

Объект с данными о подписке.

Пример: {"gift":{"email":"recipient_email@email.com","recipient":"test_recipient_v1"}}
purchase.​subscription.​available_plansArray of strings

Массив с данными о планах подписок. Только планы из этого списка будут показаны в платежном интерфейсе.

purchase.​subscription.​currencystring

Валюта рекуррентного плана в заказе, на основе которой будут сделаны все расчеты.

purchase.​subscription.​giftobject

Информация о подаренной подписке.

Пример: {"email":"recipient_email@email.com","recipient":"test_recipient_v1"}
purchase.​subscription.​gift.​anonymousboolean

Отправлен ли подарок анонимно. Если значение true, имя отправителя будет скрыто в email-уведомлении. По умолчанию false.

purchase.​subscription.​gift.​emailstringобязательный

Email-адрес получателя.

Пример: "recipient_email@email.com"
purchase.​subscription.​gift.​messagestring

Сообщение для получателя.

purchase.​subscription.​gift.​recipientstringобязательный

ID получателя.

Пример: "test_recipient_v1"
purchase.​subscription.​gift.​redirect_urlstring

Ссылка на страницу с дополнительной информацией о подаренной подписке или страницу создания учетной записи. Получатель подарка сможет перейти на эту страницу из email-уведомления о подаренной подписке.

purchase.​subscription.​operationstring

Тип операции, применяемой к плану подписки пользователя. Чтобы изменить план подписки, передайте в параметре значение change_plan. В параметре purchase.subscription.plan_id необходимо передать ID нового плана подписки.

purchase.​subscription.​plan_idstring

Внешний ID плана подписки. Вы можете найти этот параметр в Личном кабинете в разделе Subscriptions > Планы подписки.

purchase.​subscription.​product_idstring

ID рекуррентного продукта.

purchase.​subscription.​trial_daysinteger

Количество дней триального периода.

settingsobject

Объект, содержащий настройки проекта.

Пример: {"currency":"USD","language":"en","project_id":16184,"ui":{"components":{"virtual_currency":{"custom_amount":true}},"desktop":{"virtual_item_list":{"button_with_price":true,"layout":"list"}},"size":"medium"}}
settings.​currencystring

Предпочтительная валюта платежа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.

Пример: "USD"
settings.​external_idstring

Идентификатор транзакции в игре. Должен быть уникальным для каждого платежа пользователя.

settings.​languagestring

Язык интерфейса. Используется двухбуквенное обозначение (в нижнем регистре).

Пример: "en"
settings.​modestring

Передайте значение sandbox, чтобы провести тестовые платежи. Обратите внимание, что URL для страницы оплаты будет https://sandbox-secure.xsolla.com.

settings.​payment_methodinteger

ID способа оплаты.

settings.​payment_widgetstring

Виджет оплаты. Принимает значения paybycash или giftcard. При передаче этого параметра пользователь перенаправляется на виджет Pay with Cash или Gift Cards.

Перечисление"paybycash""giftcard"
settings.​project_idintegerобязательный

Game’s Xsolla ID. Can be found in Publisher Account.

Пример: 16184
settings.​redirect_policyobject

Настройки политики редиректа.

settings.​redirect_policy.​autoredirect_from_status_pageboolean

Перенаправлять ли пользователя автоматически со страницы статуса платежа.

settings.​redirect_policy.​delayinteger

Задержка (в секундах), после которой пользователь автоматически перенаправляется на return URL.

settings.​redirect_policy.​manual_redirection_actionstring

Действие, которое совершает платежный интерфейс, когда пользователь закрывает окно платежного интерфейса или нажимает кнопку Back to the Game. Может принимать значения redirect (по умолчанию) и postmessage. Если указано значение redirect, пользователь перенаправляется на URL-адрес, указанный в токене или в Личном кабинете. Если указано значение postmessage, при закрытии окна платежного интерфейса отправляется событие close, при нажатии Back to the Game — событие return.

Перечисление"redirect""postmessage"
settings.​redirect_policy.​redirect_button_captionstring

Текст кнопки для ручного перенаправления.

settings.​redirect_policy.​redirect_conditionsstring

Статус платежа, при котором пользователь перенаправляется на return URL. Принимает значение none, successful, successful_or_canсeled или any.

Перечисление"none""successful""successful_or_canceled""any"
settings.​redirect_policy.​status_for_manual_redirectionstring

Статус платежа, при котором появляется кнопка для возврата на return URL. Принимает значение none, successful, successful_or_canсeled или any.

Перечисление"none""successful""successful_or_canceled""any"
settings.​return_urlstring

Пользователь будет перенаправлен на данную страницу после совершения платежа. Параметры user_id, foreigninvoice, invoice_id и status будут автоматически добавлены к ссылке.

settings.​uiobject

Объект с настройками интерфейса.

Пример: {"components":{"virtual_currency":{"custom_amount":true}},"desktop":{"virtual_item_list":{"button_with_price":true,"layout":"list"}},"size":"medium"}
settings.​ui.​componentsobject

Объект с данными настройки пунктов меню.

Пример: {"virtual_currency":{"custom_amount":true}}
settings.​ui.​components.​subscriptionsobject

Объект с данными настройки меню подписок.

settings.​ui.​components.​subscriptions.​hiddenboolean

Должна ли вкладка отображаться в меню.

settings.​ui.​components.​subscriptions.​orderinteger

Место вкладки в меню.

settings.​ui.​components.​virtual_currencyobject

Объект с данными настройки меню виртуальной валюты.

Пример: {"custom_amount":true}
settings.​ui.​components.​virtual_currency.​custom_amountboolean

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

Пример: true
settings.​ui.​components.​virtual_currency.​hiddenboolean

Должна ли вкладка отображаться в меню.

settings.​ui.​components.​virtual_currency.​orderinteger

Место вкладки в меню.

settings.​ui.​components.​virtual_itemsobject

Объект с данными настройки меню предметов.

settings.​ui.​components.​virtual_items.​hiddenboolean

Должна ли вкладка отображаться в меню.

settings.​ui.​components.​virtual_items.​orderinteger

Место вкладки в меню.

settings.​ui.​components.​virtual_items.​selected_groupstring

Группа, которая будет выбрана при открытии вкладки.

settings.​ui.​components.​virtual_items.​selected_itemstring

Предмет, который будет выбран при открытии вкладки. Должен быть передан артикул предмета.

settings.​ui.​desktopobject

Объект с данными настроек для desktop-версии.

Пример: {"virtual_item_list":{"button_with_price":true,"layout":"list"}}
settings.​ui.​desktop.​headerobject

Объект с настройками хедера.

settings.​ui.​desktop.​header.​close_buttonboolean

Показывать ли кнопку Закрыть в настольной версии платежного интерфейса. Нажатие на кнопку закрывает платежный интерфейс и перенаправляет пользователя на адрес, указанный в параметре settings.return_url. false по умолчанию.

settings.​ui.​desktop.​header.​is_visibleboolean

Whether to show the header in the payment UI.

settings.​ui.​desktop.​header.​typestring

Внешний вид хедера. Может принимать значения compact (название игры и ID пользователя не будут показываться в хедере) или normal.

Перечисление"compact""normal"
settings.​ui.​desktop.​header.​visible_logoboolean

Если значение true, то логотип будет отображаться в хедере (необходимо сначала прислать файл с логотипом персональному менеджеру проекта).

settings.​ui.​desktop.​header.​visible_nameboolean

Whether to show the project name in the header.

settings.​ui.​desktop.​header.​visible_purchaseboolean

Должно ли описание покупки (purchase.description.value) отображаться в хедере, по умолчанию true.

settings.​ui.​desktop.​subscription_listobject

Объект с данными настройки списка подписок.

settings.​ui.​desktop.​subscription_list.​descriptionstring

Здесь вы можете передать текст про подписки. Текст появится перед списком рекуррентных планов в интерфейсе оплаты.

settings.​ui.​desktop.​subscription_list.​display_local_priceboolean

Если значение true и если локальная валюта пользователя отличается от базовой валюты плана, пользователь будет видеть две цены: цену в локальной валюте и цену в базовой валюте плана.

settings.​ui.​desktop.​subscription_list.​layoutstring

Шаблон списка. Принимает значения list (по умолчанию) или grid.

Перечисление"list""grid"
settings.​ui.​desktop.​virtual_currency_listobject

Объект с данными настройки списка пакетов виртуальной валюты.

settings.​ui.​desktop.​virtual_currency_list.​button_with_priceboolean

Если значение true, то цена за предмет будет показана внутри кнопки. Если false, то цена будет слева от кнопки. false по умолчанию.

settings.​ui.​desktop.​virtual_currency_list.​descriptionstring

Здесь вы можете передать текст про виртуальную валюту. Текст появится перед списком пакетов виртуальной валюты в интерфейсе оплаты.

settings.​ui.​desktop.​virtual_item_listobject

Объект с данными настройки списка предметов.

Пример: {"button_with_price":true,"layout":"list"}
settings.​ui.​desktop.​virtual_item_list.​button_with_priceboolean

Если значение true, то цена за предмет будет показана внутри кнопки. Если false, то цена будет слева от кнопки. false по умолчанию.

Пример: true
settings.​ui.​desktop.​virtual_item_list.​layoutstring

Шаблон списка. Принимает значения list (по умолчанию) или grid.

Перечисление"list""grid"
Пример: "list"
settings.​ui.​desktop.​virtual_item_list.​viewstring

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

Перечисление"horizontal_navigation""vertical_navigation"
settings.​ui.​headerobject
settings.​ui.​header.​visible_virtual_currency_balanceboolean

Должен ли этот элемент быть видимым в интерфейсе оплаты. true по умолчанию.

settings.​ui.​is_prevent_external_link_openboolean

Отключение перехода по внешним ссылкам, по умолчанию true. При нажатии на внешнюю ссылку отправляется событие external-link-open с помощью механизма postMessage. В параметре url передается адрес, по которому выполняется переход.

settings.​ui.​license_urlstring

Ссылка на лицензионное соглашение.

settings.​ui.​mobileobject
settings.​ui.​mobile.​footerobject
settings.​ui.​mobile.​footer.​is_visibleboolean

Скрывать или нет footer в мобильной версии платежного интерфейса.

settings.​ui.​mobile.​headerobject
settings.​ui.​mobile.​header.​close_buttonboolean

Показывать ли кнопку Закрыть в мобильной версии платежного интерфейса. Нажатие на кнопку закрывает платежный интерфейс и перенаправляет пользователя на адрес, указанный в параметре settings.return_url. false по умолчанию.

settings.​ui.​mobile.​modestring

Пользователь может совершить платеж только через сохраненные способы оплаты. Принимает значение saved_accounts.

Значение"saved_accounts"
settings.​ui.​modestring

Платежный интерфейс в режиме Личного кабинета. Принимает значение user_account. Хедер содержит только навигационное меню Личного кабинета; исключается возможность выбора предмета и оплата покупки; режим Личного кабинета доступен только в desktop-режиме.

settings.​ui.​sizestring

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

  • small: Наименьший размер платежного интерфейса. Используется в случаях, когда размеры окна строго ограничены (размер: 620 x 630)
  • medium: Рекомендуемый размер платежного интерфейса. Оптимален при открытии в lightbox (размер: 740 x 760)
  • large: желательно открывать в новом окне/вкладке (размер: 820 x 840)
Перечисление"small""medium""large"
Пример: "medium"
settings.​ui.​themestring

Внешний вид интерфейса оплаты. Может принимать значения default (по умолчанию) или default_dark.

Перечисление"default""default_dark"
settings.​ui.​user_accountobject

Объект с данными об аккаунте пользователя.

settings.​ui.​user_account.​historyobject

Страница История пользователя.

settings.​ui.​user_account.​history.​enableboolean

Должна ли вкладка отображаться в меню. false по умолчанию.

settings.​ui.​user_account.​history.​orderinteger

Место вкладки в меню.

settings.​ui.​user_account.​infoobject

Страница Мой аккаунт.

settings.​ui.​user_account.​info.​enableboolean

Должна ли вкладка отображаться в меню. false по умолчанию.

settings.​ui.​user_account.​info.​orderinteger

Место вкладки в меню.

settings.​ui.​user_account.​payment_accountsobject

Страница Сохраненные платежные аккаунты.

settings.​ui.​user_account.​payment_accounts.​enableboolean

Должна ли вкладка отображаться в меню. false по умолчанию.

settings.​ui.​user_account.​payment_accounts.​orderinteger

Место вкладки в меню.

settings.​ui.​user_account.​subscriptionsobject

Страница Управление подписками.

settings.​ui.​user_account.​subscriptions.​enableboolean

Должна ли вкладка отображаться в меню. false по умолчанию.

settings.​ui.​user_account.​subscriptions.​orderinteger

Место вкладки в меню.

settings.​ui.​versionstring

Тип устройства. Может принимать значения desktop (по умолчанию) или mobile.

Перечисление"desktop""mobile"
userobject

Объект с информацией о пользователе.

Пример: {"age":19,"country":{"allow_modify":true,"value":"US"},"email":{"value":"john.smith@mail.com"},"id":{"value":"user_2"},"name":{"value":"John Smith"}}
user.​ageinteger

Возраст пользователя.

Пример: 19
user.​attributesobject

Объект с данными об атрибутах пользователя, необходимых для фильтрации списка предметов. Параметры передаются в json хэше парами ключ-значение.

user.​countryobject
Пример: {"allow_modify":true,"value":"US"}
user.​country.​allow_modifyboolean

Может ли пользователь изменить страну на странице оплаты. Если в токене передан параметр country.value, значение по умолчанию — false.

Пример: true
user.​country.​valuestring

Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.

Пример: "US"
user.​emailobject

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

Пример: {"value":"john.smith@mail.com"}
user.​email.​valuestringобязательный

Email пользователя. Должен быть валидным в соответствии с протоколом RFC 822.

Пример: "john.smith@mail.com"
user.​idobjectобязательный
Пример: {"value":"user_2"}
user.​id.​valuestringобязательный

ID пользователя.

Пример: "user_2"
user.​is_legalboolean

Является ли пользователь юридическим лицом.

user.​legalobject

Объект с реквизитами юридического лица.

user.​legal.​addressstring

Полный юридический адрес.

user.​legal.​countrystring

Страна регистрации. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.

user.​legal.​namestring

Полное юридическое наименование.

user.​legal.​vat_idstring

Индивидуальный идентификатор налогоплательщика.

user.​nameobject
Пример: {"value":"John Smith"}
user.​name.​valuestring

Ник пользователя.

Пример: "John Smith"
user.​phoneobject
user.​phone.​valuestring

Номер телефона пользователя.

user.​public_idobject
user.​public_id.​valuestring

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

user.​steam_idobject
user.​steam_id.​valuestring

Steam ID пользователя.

user.​tracking_idobject
user.​tracking_id.​valuestring

Уникальный Tracking ID (используется для проведения рекламных кампаний).

user.​utmobject

Объект с данными о характеристиках трафика.

user.​utm.​utm_campaignstring

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

user.​utm.​utm_contentstring

Содержание кампании.

user.​utm.​utm_mediumstring

Канал трафика (контекстная реклама, медийная реклама, email-рассылка).

user.​utm.​utm_sourcestring

Источник трафика

user.​utm.​utm_termstring

Ключевое слово кампании. При использовании этого параметра в статистике будут собираться данные по тем ключевым словам, которые используются для таргетинга вашей рекламной кампании (а не по поисковым запросам). В Google Analytics содержимое метки utm_term попадает в единый отчет с поисковыми запросами.

curl -i -X POST \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/ru/api/subscriptions/merchants/{merchant_id}/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "purchase": {
      "checkout": {
        "amount": 10,
        "currency": "USD"
      },
      "subscription": {
        "gift": {
          "email": "recipient_email@email.com",
          "recipient": "test_recipient_v1"
        }
      }
    },
    "settings": {
      "currency": "USD",
      "language": "en",
      "project_id": 16184,
      "ui": {
        "components": {
          "virtual_currency": {
            "custom_amount": true
          }
        },
        "desktop": {
          "virtual_item_list": {
            "button_with_price": true,
            "layout": "list"
          }
        },
        "size": "medium"
      }
    },
    "user": {
      "age": 19,
      "country": {
        "allow_modify": true,
        "value": "US"
      },
      "email": {
        "value": "john.smith@mail.com"
      },
      "id": {
        "value": "user_2"
      },
      "name": {
        "value": "John Smith"
      }
    }
  }'

Ответы

Created.

Телоapplication/json
tokenstring
Ответ
application/json
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

Планы

Операции

Продукты

Операции

Subscription management

Операции

Платежи

Операции

Акции

Операции

Купоны

Операции

Subscription management

Операции