Настройка продажи игровых ключей

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

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

Для неавторизованных пользователей

Без авторизации пользователи могут покупать игры на следующих условиях:

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

ТоварСпособ продажи
Одна копия игры (игровой ключ).Используйте прямую ссылку или виджет.
Несколько копий игры (игровых ключей) или разные игры в составе корзины.Передайте уникальный идентификатор пользователя и email-адрес. Email-адрес и другая дополнительная информация (имя пользователя и код страны в формате ISO 3166-1 alpha-2) передаются в заголовке в кодировке Base64 для параметра x-user при вызове API-метода для получения токена оплаты.
Один товар.Используйте методы быстрой покупки.
Продажа товаров в составе корзины.Передайте уникальный идентификатор пользователя в заголовке в виде числа или строки при вызове API-методов подраздела Catalog из группы методов Game keys (параметр x-unauthorized-id). Генерация идентификатора происходит на клиенте, например при помощи библиотеки для генерации идентификатора.

Для авторизованных пользователей

Чтобы управлять доступом пользователей к вашему приложению и возможностями продуктов Иксолла, необходимо настроить авторизацию. Вы можете это сделать с помощью продукта Авторизация или вашей собственной системы авторизации.

Если вы уже реализовали собственную систему авторизации и хотите использовать только платежный интерфейс Иксоллы, сгенерируйте Pay Station access token и настройте обработку вебхуков на вашем сервере.

Вы можете использовать продукт Авторизация для вашего внутриигрового магазина, если у вас отсутствует своя серверная часть или вы хотите использовать готовое решение, чтобы:

  • хранить каталог товаров;
  • управлять каталогом товаров;
  • управлять ценами и региональными ценами;
  • авторизовывать пользователей;
  • обрабатывать транзакции.

Аутентификация через продукт Авторизация

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

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

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

Аутентификация через Pay Station access token

Примечание
Обычно используется для интеграции методов API продуктов In-Game Store и Buy Button.

Сценарий взаимодействия вашего клиента и сервера Иксоллы:

  1. Ваш клиент отправляет на ваш сервер запрос на аутентификацию.
  2. Ваш сервер запрашивает токен авторизации, передавая в запросе заголовок с параметрами project_id/merchant_id и api_key на сервер Иксоллы.
  3. Сервер Иксоллы в ответе возвращает Pay Station access token.
  4. Ваш сервер передает полученный Pay Station access token вашему клиенту.
  5. Возвращенный Pay Station access token используется как авторизационный токен для аутентификации в API продуктов In-Game Store и Buy Button и построения интерфейса магазина с помощью клиентских методов.

Получение Pay Station access token

В серверной части вашего приложения реализуйте метод для получения Pay Station access token с использованием HTTP POST запроса.

API Иксоллы использует базовую HTTP-аутентификацию. Запрос должен содержать заголовок Authorization: Basic <your_authorization_basic_key>, где <your_authorization_basic_key> — пара ID продавца:ключ API, закодированная по стандарту Base64. Значения параметров вы можете найти в Личном кабинете:

  • ID продавца указан:
    • В разделе Настройки проекта > Вебхуки.
    • Разделе Настройки компании > Компания.
    • Aдресной строке браузера на любой странице Личного кабинета. URL-адрес имеет вид https://publisher.xsolla.com/​ID продавца/раздел Личного кабинета.

  • Ключ API отображается в Личном кабинете только при создании и должен храниться на вашей стороне. Создать ключ можно в разделах:
    • Настройки компании > Ключи API;
    • Настройки проекта > Ключи API.

Внимание

Подробная информация о работе с ключами API приведена в справочнике API.

Основные рекомендации:

  • Сохраните созданный ключ API на вашей стороне. Вы можете посмотреть ключ API в Личном кабинете только один раз при его создании.
  • Никому не сообщайте ваш ключ API, так как он дает доступ к управлению аккаунтом и проектами в Личном кабинете.
  • Ключ API должен храниться на вашем сервере и никогда — в бинарных файлах или на фронтенде.

HTTP-запрос:

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

В теле запроса на получение токена передайте следующие параметры:

ПараметрТипОписание
settings
objectОбъект, содержащий настройки проекта.
settings.project_id
integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта. Обязательный.
user
objectОбъект с информацией о пользователе.
user.id
objectОбъект с данными об ID пользователя в вашей системе авторизации.
user.id.value
stringID пользователя. Обязательный.
user.email
objectОбъект с данными о email-адресе пользователя.
user.email.value
stringEmail пользователя. Должен быть валидным в соответствии с протоколом RFC 822. Обязательный.
user.name
objectОбъект с информацией о нике пользователя. Обязательный.
user.name.value
stringНикнейм пользователя.
user.steam_id
objectОбъект с данными о Steam ID пользователя.
user.steam_id.value
stringSteam ID пользователя. Обязательный, если приложение публикуется на Steam.
user.playfab_id
objectОбъект с данными о PlayFab ID пользователя.
user.playfab_id.value
stringPlayFab ID пользователя. Обязательный, если приложение использует сервисы PlayFab для начисления товаров.

Примеры запросов и ответов приведены в справочнике API.

Внимание
В запросе используйте только параметры из списка выше. Другие параметры API метода (custom_parameters, purchase и т. д.) передавать не следует, они не предназначены для получения авторизационного токена.

Время жизни Pay Station access token при работе с внутриигровым магазином и инвентарем — 1 час с момента последнего обращения к API Иксоллы. Чтобы изменить время жизни Pay Station access token, обратитесь к аккаунт-менеджеру проекта.

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

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

Для открытия платежного интерфейса используется ссылка:

Copy
Full screen
Small screen

https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOU_PROJECT_ID}&sku={YOUR-ITEM-SKU}

Примечание

Покупка игровых ключей по прямой ссылке за реальную валюту возможна после подписания лицензионного договора с Иксоллой. Для этого в Личном кабинете перейдите в раздел Финансы > Лицензионные договоры, заполните договор и дождитесь подтверждения согласования. Согласование может занять до 3 рабочих дней.

Для тестирования оплаты используйте тестовое окружение, добавив в ссылку параметр mode=sandbox.

Добавьте в ссылку следующие данные:

  • YOUR-ITEM-TYPE — тип товара:
    • game — игра; game_key — игра на конкретной платформе.
    • bundle — бандл.
  • YOUR-PROJECT-ID — идентификатор вашего проекта из раздела Настройки проекта > Общие настройки > ID проекта в Личном кабинете.
  • YOUR-ITEM-SKU — артикул пакета игровых ключей. Для продажи игры на конкретной платформе необходимо получить артикул с помощью запроса Get games list (как правило, этот артикул выглядит как unit_name_drm_sku).

  • Внешний вид платежного интерфейса: тема (темная — dark или светлая — default), размер и другие параметры. Укажите в URL ссылки параметр ui_settings и в качестве значения передайте JSON-объект settings.ui в кодировке Base64. Пример URL с настройками UI:

Copy
Full screen
Small screen

https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOU_PROJECT_ID}&sku={YOUR-ITEM-SKU}&ui_settings=ewoJCQkic2l6ZSI6ICJzbWFsbCIsCgkJCSJ0aGVtZSI6ICJkYXJrIgoJCX0=

  • Токен для передачи информации о пользователе. Используется только при продаже игровых ключей для авторизованных пользователей. Формируется в зависимости от типа аутентификации. Пример URL с токеном:

Copy
Full screen
Small screen

https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&xsolla_login_token={ACCESS_TOKEN}

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

  1. Пример URL-адреса для тестирования:

Copy
Full screen
Small screen

https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOU_PROJECT_ID}&sku={YOUR-ITEM-SKU}&mode=sandbox

Продажа через интерфейс магазина

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

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

Для продажи пакетов игровых ключей интегрируйте In-Game Store & Buy Button API:

  1. Для отображения каталога используйте метод Get games list.
  2. Реализуйте покупку игровых ключей:

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

Примечание
При продаже игры через In-Game Store & Buy Button API необходимо реализовать на клиенте выбор конкретной платформы. В качестве артикула необходимо передавать значение параметра items.unit_items.sku из запроса на получение списка игр.

Продажа через виджет

Существует несколько способов разработать свои кнопки и интегрировать их с API Иксоллы:

Кастомизация кнопки

  1. Откройте ваш проект в Личном кабинете.
  2. Нажмите Магазин в боковом меню.
  3. В панели Игровые ключи нажмите Настроить.
  4. Выберите нужный вам игровой ключ и перейдите на вкладку Кастомизация виджета.

Примечание
Если игровых ключей нет, создайте их.

  1. В блоке Кастомизировать выберите цвет фона Белый.

Примечание
Также вы можете задать объекту theme свойство background с пустым значением.

  1. Код при добавлении на страницу наследует стили. Чтобы их переопределить, добавьте стили, приведенные ниже.

Внимание
Рекомендуется добавить стили в тег style под тегом script, который вы получили на вкладке Кастомизация виджета для приоритета стилей виджета.
Copy
Full screen
Small screen

/* This should be used for button positioning but note this technically repositions the entire widget */
#xsolla-buy-button-widget {
  /* place code for button positioning here */
}

/* Styles the button itself */
.x-buy-button-widget.x-buy-button-widget__tiny
  .x-buy-button-widget-payment-button {
  background-color: #ff005b;
  color: black;
}

/* Button on hover */
.x-buy-button-widget.x-buy-button-widget__tiny
  .x-buy-button-widget-payment-button:hover {
  background-color: #ff005b;
}

/* The following are style overrides to leave you with just the button */

/* space immediately surrounding button */
.x-buy-button-widget-button-block.x-buy-button-widget-button-block__light {
  background-color: white;
}

/* space above button (including game title area) */
.x-buy-button-widget.x-buy-button-widget__tiny
  .x-buy-button-widget-game-logo {
  height: 200px;
  background-image: none !important;
  background-color: white;
}

 /* Game title (located right above button) */
.x-buy-button-widget-game-name.x-buy-button-widget-game-name__light {
  display: none !important;
}

Внимание
  • Важно вставить скопированный код виджета, поскольку приведенные выше имена идентификаторов или классов и сам фрагмент кода используются вместе с ним (шаг 5).
  • Вы также можете скопировать приведенный выше код, но, возможно, его придется адаптировать под ваши потребности. Комментарии к коду (строки 1, 3, 5, 11, 16, 18, 22, 29) помогут определить зависимости для каждого CSS-правила и для будущих стилей. Например, если вы хотите, чтобы у вас осталась только кнопка (а не весь виджет), вам нужно заменить фоновый цвет вашей страницы в местах, где цвет задан как white — в строках 20 и 27.

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

Используйте Xsolla Pay2Play Widget Simple Integration 4 buttons, чтобы получить примеры кода для создания нескольких кнопок.

Структура этого кода аналогична коду виджета Buy Button. Пример миграции:

Copy
Full screen
Small screen

<div id="xsolla-buy-button-widget"></div>
<div id="xsolla-buy-button-widget-2"></div>
    <script>
      var options = {
        project_id: "191204",
        sku: "789",
        item_type: "unit",
        api_settings: {
          sandbox: false,
        },
        widget_ui: {
          target_element: "#xsolla-buy-button-widget",
          theme: {
            foreground: "gold",
            background: "",
          },
        },
        payment_widget_ui: {
          lightbox: {
            height: "700px",
            spinner: "round",
          },
        },
      };
      // options for second buy button - note the different SKU and target_element
      var options2 = {
        project_id: "191204",
        sku: "123",
        item_type: "unit",
        api_settings: {
          sandbox: false,
        },
        widget_ui: {
          target_element: "#xsolla-buy-button-widget-2",
          theme: {
            foreground: "gold",
            background: "",
          },
        },
        payment_widget_ui: {
          lightbox: {
            height: "700px",
            spinner: "round",
          },
        },
      };
      var s = document.createElement("script");
      s.type = "text/javascript";
      s.async = true;
      s.src = "https://cdn.xsolla.net/embed/buy-button/3.1.4/widget.min.js";

// one event listener per widget instance. repeat for more buttons, passing in different SKUs
      s.addEventListener(
        "load",
        function (e) {
          var widgetInstance = XBuyButtonWidget.create(options);
        },
        false
      );
      s.addEventListener(
        "load",
        function (e) {
          var widgetInstance2 = XBuyButtonWidget.create(options2);
        },
        false
      );
      var head = document.getElementsByTagName("head")[0];
      head.appendChild(s);
    </script>

Внимание
  • Строки 1 и 2 содержат div для каждой кнопки. У каждого div есть свой уникальный идентификатор.
  • Объект с именем options2 содержит параметры для второй кнопки (начиная со строки 26). У вас будет набор таких объектов options, аналогично приведенным выше, для каждой кнопки Купить. Обратите внимание на разные sku (строка 28) и target_element (строка 34, указывающая на div в строке 2).
Была ли статья полезна?
Спасибо!
Что может сделать страницу еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
Оценить страницу
Оценить страницу
Что может сделать страницу еще лучше?

В другой раз

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

Продолжить чтение

Следующие шаги

Настройка вебхуков
Последнее обновление: 31 января 2023

Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

Сообщите о проблеме
Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
Укажите email-адрес, чтобы мы могли связаться с вами
Спасибо за обратную связь!