Перейти к содержимому
Токен/
Создание токена

Pay Station API (2.0)

Введение

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

Pay Station позволяет вам монетизировать игру, предоставляя пользователям удобный интерфейс для оплаты покупок во внутриигровом магазине. Чтобы настроить открытие платежного интерфейса, следуйте инструкции.

В Pay Station API представлены следующие группы методов:

  • Токен — содержит метод для создания токена с любыми параметрами пользователя для дальнейшей обработки платежа через платежный интерфейс.
  • Токенизация — содержит методы для проведения безопасных платежей без открытия платежного интерфейса и непосредственного участия пользователя.
  • Отчеты — содержит методы для возвращения информации о транзакциях пользователя, а также создания отчетов и получения детализации выплат по валютам.
  • Возврат платежа — содержит методы для создания запросов на отмену платежа и на частичный возврат платежа.
  • Тестирование — содержит метод для тестирования процесса чарджбэка.

Подробные сведения о настройке платежного интерфейса приведены в руководстве по интеграции решения Payments.

Примечание

Вы также можете использовать раздел Xsolla Base API из коллекции Postman, чтобы протестировать методы, необходимые для интеграции.

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

Токен

Операции

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

Запрос

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

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

По умолчанию время жизни токена — 24 часа. Если вы хотите изменить это значение, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com. Новое значение будет действовать во всех проектах вашей компании, созданных в Личном кабинете.

Внимание

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

Чтобы открыть платежный интерфейс в новом окне, используйте ссылку: https://secure.xsolla.com/paystation4/?token={token}, где {token} — полученный токен.

Для тестирования используйте этот URL-адрес: https://sandbox-secure.xsolla.com/paystation4/?token={token}.

Внимание

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

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

ID продавца.

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

Объект с параметрами для настройки антифрод-фильтров. Список параметров приведен ниже на этой странице. Чтобы добавить кастомные параметры, свяжитесь с вашим персональным менеджером или напишите на csm@xsolla.com.

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_currencynumber(float)

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

custom_parameters.​notifications_enabledboolean

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

custom_parameters.​profile_completedboolean

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

custom_parameters.​profile_image_addedboolean

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

custom_parameters.​pvp_activityboolean

Участвует ли игрок в битвах PvP (Player(s) versus player(s); игрок против игрока).

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_valuenumber(float)

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

custom_parameters.​total_sumnumber(float)

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

custom_parameters.​tutorial_completedboolean

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

custom_parameters.​unlocked_achievementsinteger

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

custom_parameters.​user_levelinteger

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

custom_parameters.​win_rateinteger

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

purchaseobject(purchase)

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

purchase.​is_lootboxboolean(is_lootbox)

Является ли товар лутбоксом.

По умолчанию false
purchase.​subscriptionobject(subscription)

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

purchase.​subscription.​available_plansArray of strings

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

purchase.​subscription.​currencystring

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

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(settings)

Параметры для настройки процесса оплаты и платежного интерфейса для пользователя.

settings.​currencystring(currency)

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

settings.​external_idstring(external_id)

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

settings.​languagestring(language)

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

settings.​modestring(mode.settings)

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

settings.​payment_methodinteger(payment_method)

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

settings.​payment_widgetstring(payment_widget)

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

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

ID игры в Xsolla. Вы можете найти этот параметр в Личном кабинете.

settings.​redirect_policyobject(redirect_policy)

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

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.​show_redirect_countdownboolean

Отображать ли на странице со статусом платежа таймер обратного отсчета до перенаправления пользователя. Длительность отсчета определяется значением, переданным в параметре settings.redirect_policy.delay.

По умолчанию false
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(return_url)

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

settings.​uiobject(ui)

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

settings.​ui.​alternative_first_screenstring(alternative_first_screen)

Альтернативный вид экрана платежного интерфейса при его открытии. Например, может отображать приоритетные способы оплаты.

Когда передано значение apple-pay, при открытии платежного интерфейса пользователь видит приоритетную кнопку оплаты с помощью Apple Pay и ссылку для перехода к списку других способов оплаты. На устройства Android эта логика не распространяется.

Значение"apple-pay"
settings.​ui.​apple_pay_quick_payment_buttonboolean(ap_quick_payment_button)

Отображать ли кнопку для быстрой оплаты с помощью Apple Pay в верхней части платежного интерфейса, если этот способ оплаты поддерживается на устройстве пользователя. true по умолчанию. Если передано значение false, Apple Pay отображается в списке способов оплаты в соответствии с алгоритмом PayRank.

Примечание

На мобильных Android-устройствах, а также на любых других, где сервис Apple Pay недоступен, этот способ оплаты будет скрыт из списка вне зависимости от значения параметра.

settings.​ui.​componentsobject(components)

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

settings.​ui.​components.​subscriptionsobject

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

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

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

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

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

settings.​ui.​components.​virtual_currencyobject

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

settings.​ui.​components.​virtual_currency.​custom_amountboolean

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

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.​currency_formatstring(currency_format)

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

settings.​ui.​desktopobject(desktop.ui)

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

settings.​ui.​desktop.​headerobject(header.desktop)

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

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

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

settings.​ui.​desktop.​header.​close_button_iconstring(close_button_icon)

Значок кнопки Закрыть в платежном интерфейсе.

Перечисление ЗначениеОписание
arrow

Значок ← в левой части хедера платежного интерфейса.

cross

Значок × в правой части хедера платежного интерфейса.

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

Должен ли header отображаться на странице оплаты.

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

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

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

Если true, логотип будет отображаться в хедере. Чтобы загрузить изображение, откройте проект в Личном кабинете и перейдите в раздел Pay Station > Настройки.

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

Должно ли название игры отображаться в header.

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

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

settings.​ui.​desktop.​subscription_listobject(subscription_list.desktop)

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

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

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

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

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

settings.​ui.​gp_quick_payment_buttonboolean(gp_quick_payment_button)

Расположение способа оплаты с помощью Google Pay. Если передано значение true, кнопка для быстрой оплаты с помощью Google Pay отображается в верхней части платежного интерфейса вне зависимости от устройства и браузера пользователя. Если передано значение false, Google Pay отображается в списке способов оплаты в соответствии с алгоритмом PayRank. Если параметр не передан, Google Pay отображается в верхней части платежного интерфейса на любых устройствах и браузерах пользователя, кроме Safari — в Safari он отображается в списке способов оплаты.

settings.​ui.​headerobject(header.ui)
settings.​ui.​header.​visible_virtual_currency_balanceboolean

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

settings.​ui.​is_cart_open_by_defaultboolean(is_cart_open_by_default)

Отображение в платежном интерфейсе списка товаров корзины и финансовой информации. Если передано значение true, информация отображается в развернутом виде. Если передано значение false (по умолчанию) или параметр не передан, информация отображается в свернутом виде.

settings.​ui.​is_independent_windowsboolean(is_independent_windows)

Осуществляется ли переход из встроенного браузера лаунчера (WebView) во внешний браузер для совершения покупки. false по умолчанию.

settings.​ui.​is_language_selector_hiddenboolean(is_language_selector_hidden)

Скрыт ли на странице оплаты переключатель языков. Если передано значение false (по умолчанию), переключатель отображается.

settings.​ui.​is_payment_methods_list_modeboolean(is_payment_methods_list_mode)

Отображается ли список способов оплаты, доступных в стране игрока, при открытии платежного интерфейса. ​​Если передано значение false (по умолчанию), отображается способ оплаты, переданный в параметре settings.payment_method или способ, выбранный алгоритмом PayRank.

settings.​ui.​is_prevent_external_link_openboolean(is_prevent_external_link_open)

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

settings.​ui.​is_search_field_hiddenboolean(is_search_field_hidden)

Показывать ли в платежном интерфейсе строку поиска способов оплаты. Если передано значение true, строка поиска скрыта. false по умолчанию.

settings.​ui.​is_show_close_widget_warningboolean(is_show_close_widget_warning)

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

settings.​ui.​is_three_ds_independent_windowsboolean(is_three_ds_independent_windows)

Открывать ли проверку 3-D Secure в новом окне браузера. Если используется политика безопасности контента (Content Security Policy, CSP), передайте значение true.

По умолчанию false
settings.​ui.​layoutstring(layout)

Расположение основных элементов платежного интерфейса. Вы можете открыть платежный интерфейс внутри вашей игры и/или поменять местами колонки с информацией о заказе и способах оплаты. Подробная информация представлена в инструкции по кастомизации.

Перечисление"embed""column_reverse""embed_column_reverse"
settings.​ui.​mobileobject(mobile.ui)
settings.​ui.​mobile.​headerobject
settings.​ui.​mobile.​header.​close_buttonboolean

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

settings.​ui.​mobile.​header.​close_button_iconstring(close_button_icon)

Значок кнопки Закрыть в платежном интерфейсе.

Перечисление ЗначениеОписание
arrow

Значок ← в левой части хедера платежного интерфейса.

cross

Значок × в правой части хедера платежного интерфейса.

settings.​ui.​modestring(mode.ui)

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

Примечание

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

settings.​ui.​themestring(theme.ui)

Тема платежного интерфейса. Может принимать значения 63295a9a2e47fab76f7708e1 для светлой темы (по умолчанию) или 63295aab2e47fab76f7708e3 для темной темы. Вы также можете создать собственную тему и передать ID темы в этом параметре.

Перечисление"63295a9a2e47fab76f7708e1""63295aab2e47fab76f7708e3"
settings.​ui.​user_accountobject(user_account)

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

settings.​ui.​user_account.​payment_accountsobject

Раздел Сохраненные способы.

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

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

settings.​ui.​user_account.​payment_accounts.​orderinteger>= 1

Расположение раздела в раскрывающемся меню в платежном интерфейсе. Обязательный, если передается settings.ui.user_account.payment_accounts.enable.

userobject(user)

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

user.​ageinteger(age.user)

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

user.​attributesobject(attributes.user)

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

user.​countryobject(country.user)
user.​country.​allow_modifyboolean

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

user.​country.​valuestring

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

user.​emailobject(email.user)

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

user.​email.​allow_modifyboolean

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

user.​email.​valuestring<= 100 charactersобязательный

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

user.​idobject(id.user)обязательный
user.​id.​valuestringобязательный

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

user.​is_legalboolean(is_legal.user)

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

user.​legalobject(legal.user)

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

user.​legal.​addressstring

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

user.​legal.​countrystring

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

user.​legal.​namestring

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

user.​legal.​vat_idstring

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

user.​nameobject(name.user)
user.​name.​allow_modifyboolean

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

user.​name.​valuestring

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

user.​phoneobject or null(phone.user)
user.​phone.​valuestring

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

user.​public_idobject(public_id.user)
user.​public_id.​valuestring

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

user.​steam_idobject(steam_id.user)
user.​steam_id.​valuestring

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

user.​tracking_idobject(tracking_id.user)
user.​tracking_id.​valuestring= 32 characters

Уникальный ID пользователя — используется для проведения рекламных кампаний. Может содержать цифры и латинские буквы.

user.​utmobject(utm.user)

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

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://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "settings": {
      "currency": "USD",
      "language": "en",
      "project_id": 16184,
      "ui": {
        "size": "medium"
      }
    },
    "user": {
      "email": {
        "value": "email@example.com"
      },
      "id": {
        "value": "user_2"
      },
      "name": {
        "value": "John Smith"
      }
    }
  }'

Ответы

Created.

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

Токенизация

Операции

Отчеты

Операции

Возврат платежа

Операции

Тестирование

Операции