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

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

ТоварСпособ продажи
Одна копия игры (игровой ключ).Прямая ссылка, виджет или интерфейс магазина. При продаже через интерфейс магазина используйте метод быстрой покупки без создания корзины.
Несколько копий игры (игровых ключей) или разные игры в составе корзины.Интерфейс магазина. Используйте Site Builder или интегрируйте Shop Builder API.

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

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

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

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

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

Вы можете ограничить время отображения пакета игровых ключей в каталоге, например, на время сезонных распродаж. Для этого в объекте periods передайте дату начала и окончания периода доступности в формате ISO 8601 в соответствующем методе API:

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

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

Copy
Full screen
Small screen
    1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}
    
    Примечание

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

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

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

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

    • Внешний вид платежного интерфейса: тема (темная — dark или светлая — default), размер и другие параметры. Укажите в URL ссылки параметр ui_settings и в качестве значения передайте JSON-объект settings.ui в кодировке Base64. Пример URL с настройками UI:
    Copy
    Full screen
    Small screen
      1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}&ui_settings=ewoJCQkic2l6ZSI6ICJzbWFsbCIsCgkJCSJ0aGVtZSI6ICJkYXJrIgoJCX0=
      
      • Токен для передачи информации о пользователе. Используется только при продаже игровых ключей для авторизованных пользователей. Формируется в зависимости от типа аутентификации. Пример URL с токеном:
      Copy
      Full screen
      Small screen
        1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&xsolla_login_token={ACCESS_TOKEN}
        
        Примечание
        При проведении платежа сервер Xsolla отправляет запрос на URL-адрес вебхука, чтобы удостовериться, что пользователь существует в игре. Чтобы избежать ошибок при тестировании оплаты, в проекте в Личном кабинете перейдите в раздел Настройки проекта > Вебхуки и установите переключатель в положение Выкл. Если вы хотите использовать вебхуки, реализуйте успешную обработку вебхука Проверка существования пользователя.
        1. Пример URL-адреса для тестирования:
        Copy
        Full screen
        Small screen
          1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}&mode=sandbox
          

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

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

          Для продажи пакетов игровых ключей, используя Shop Builder API:

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

          Чтобы методы работали корректно, выберите подходящий способ аутентификации пользователей.
          Примечание
          При продаже игры через Shop Builder API необходимо реализовать на клиенте выбор конкретной платформы. В качестве артикула необходимо передавать значение параметра items.unit_items.sku из запроса на получение списка игр.

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

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

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

          Пример: Купить сейчас за $10.

          Если игра продается на нескольких платформах, в виджете будет указана наименьшая из цен среди платформ.

          Пример: Купить от $10.

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

          Вы также можете отобразить в виджете цену на конкретной платформе, указав название платформы в параметре drm.

          Пример кода виджета:

          Copy
          Full screen
          Small screen
           1<div id="xsolla-buy-button-widget"></div>
           2
           3<script>
           4  var options = {
           5    project_id: "101010",
           6    sku: "my_key",
           7    user: {
           8      auth: "9qs9VyCIQQXBlzJQcfETIKWZDvhi4Sz1"
           9    },
          10    drm: "steam",
          11    item_type: "unit",
          12    api_settings: {
          13      sandbox: true
          14    },
          15    widget_ui: {
          16      target_element: "#xsolla-buy-button-widget",
          17      theme: {
          18        foreground: "green",
          19        background: "light"
          20      }
          21    },
          22    payment_widget_ui: {
          23      lightbox: {
          24        height: "700px",
          25        spinner: "round"
          26      }
          27    }
          28  };
          29
          30  var s = document.createElement("script");
          31  s.type = "text/javascript";
          32  s.async = true;
          33  s.src = "https://cdn.xsolla.net/embed/buy-button/3.1.8/widget.min.js";
          34  s.addEventListener("load", function () {
          35    var widgetInstance = XBuyButtonWidget.create(options);
          36  });
          37  document.getElementsByTagName("head")[0].appendChild(s);
          38</script>
          39
          40<style>
          41  #xsolla-buy-button-widget {
          42    /* place code for button positioning here */
          43    margin: 10px;
          44  }
          45
          46  /* Styles the button itself */
          47  .x-buy-button-widget.x-buy-button-widget__tiny .x-buy-button-widget-payment-button {
          48    background-color: #ff005b;
          49    color: black;
          50  }
          51</style>
          
          Примечание
          Параметры виджета

          ПараметрТипОписание
          project_id
          integerID проекта, в который загружены игровые ключи или бандлы с игровыми ключами, внутриигровые товары или бандлы с товарами.
          item_type
          stringТип предмета. Может принимать значения virtual_good, virtual_currency, game_key, unit. Тип unit используется, когда есть несколько платформ распространения игры.
          sku
          stringУникальный ID предмета.
          drm
          stringАртикул платформы распространения игры, например, steam. Позволяет отобразить цену на конкретной платформе.
          api_settings
          objectНастройки для выбора окружения и хоста:
          • host — хост для выполнения запросов. Значение по умолчанию — store.xsolla.com.
          • api_host — хост для выполнения запросов API. Значение по умолчанию — store.xsolla.com/api.
          • sandbox — установите значение true, чтобы протестировать процесс оплаты. Для обработки платежей будет использоваться sandbox-secure.xsolla.com вместо secure.xsolla.com (см. Тестирование процесса оплаты).
          user
          objectОбъект с информацией о пользователе.
          user.auth
          stringАвторизационный токен пользователя: JSON Web Token или Pay Station access token.
          user.locale
          stringЛокаль пользователя. Определяет язык текста кнопки покупки и платежного интерфейса. Используется двубуквенный код языка по ISO_639-1.
          widget_ui.theme
          objectЦветовая тема виджета, определяющая его внешний вид. Может принимать значения {foreground:[‘blue’,‘red’,‘green’,‘gold’], background:[’light’,‘dark’]}.
          widget_ui.template
          stringШаблон. Возможные значения:
          • standard (по умолчанию) — изображение, название игры и стилизованная кнопка;
          • simple — только кнопка без применения стилей.
          widget_ui.target_element
          stringЭлемент страницы, на котором должен отображаться виджет (должен использоваться селектор jQuery, например, #widget-example). Обязательный.

          Параметры, определяющие внешний вид интерфейса оплаты

          ПараметрТипОписание
          payment_ui
          objectПараметры внешнего вида платежного интерфейса.
          payment_widget_ui
          objectОбъект с параметрами, которые определяют внешний вид платежного интерфейса.
          payment_widget_ui.lightbox
          objectОбъект с опциями модального окна, в котором открывается платежный интерфейс.
          payment_widget_ui.lightbox.width
          stringШирина lightbox. Значение по умолчанию null. Если установлено значение null, ширина lightbox соответствует ширине платежного интерфейса.
          payment_widget_ui.lightbox.height
          stringВысота lightbox. Значение по умолчанию 100%. Если установлено значение null, высота lightbox соответствует высоте платежного интерфейса.
          payment_widget_ui.lightbox.zIndex
          integerСвойство, отвечающее за положение объекта, по умолчанию 1000.
          payment_widget_ui.lightbox.overlayOpacity
          integerНепрозрачность подложки виджета (0 — полностью прозрачная, 1 — полностью непрозрачная). Значение по умолчанию — 60% (.6).
          payment_widget_ui.lightbox.overlayBackground
          stringФон для верхнего слоя, по умолчанию #000000.
          payment_widget_ui.lightbox.contentBackground
          stringФон фрейма, по умолчанию #ffffff. Обратите внимание, что настройка влияет только на фон фрейма lightbox и не меняет фон окна платежного интерфейса.
          payment_widget_ui.lightbox.spinner
          stringТип прелоадера, может принимать значение xsolla или round, по умолчанию xsolla.
          payment_widget_ui.lightbox.spinnerColor
          stringЦвет прелоадера.
          payment_widget_ui.childWindow
          objectНастройки дочернего окна, в котором открывается платежный интерфейс. Работает для мобильной версии.
          payment_widget_ui.childWindow.target
          stringСвойство, определяющее, где должно быть открыто дочернее окно. Может принимать значения _blank, _self, _parent. Значение по умолчанию — _blank.

          Методы виджета

          • var widgetInstance = XBuyButtonWidget.create(options) — создает экземпляр виджета и отображает его на странице.
          • widgetInstance.on(event, handler) — привязывает функцию обработчика событий к виджету.
            • event (string) — тип события.
            • handler (function) — функция, которая будет выполняться при срабатывании события.
          • widgetInstance.off(event, handler) — удаляет обработчик событий.
            • event (string) — тип события.
            • handler (function) — функция обработчика, ранее привязанная к событию.

          Список событий:

          ПараметрОписание
          initИнициализация виджета.
          openОткрытие виджета.
          loadСобытие после загрузки платежного интерфейса.
          closeСобытие после закрытия платежного интерфейса.
          statusСобытие, когда пользователь попадает на страницу статуса.
          status-invoiceСобытие, когда пользователь попадает на страницу статуса, но платеж еще не завершен.
          status-deliveringСобытие, когда пользователь попадает на страницу статуса, платеж завершен, мы прислали оповещение о платеже.
          status-doneСобытие, когда пользователь попадает на страницу статуса, платеж успешно зачислен.
          status-troubledСобытие, когда пользователь попадает на страницу статуса, но платеж не прошел.

          Вы можете получить доступ к списку событий, используя объект XBuyButtonWidget.eventTypes.

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

          1. В проекте в Личном кабинете перейдите в раздел Каталог товаров > Игровые ключи.
          2. Выберите нужный вам игровой ключ и перейдите на вкладку Кастомизация виджета.
          Примечание
          Если игровых ключей нет, создайте их.
          1. В блоке Кастомизировать выберите цвет фона.
          Примечание
          Также вы можете задать объекту theme свойство background с пустым значением.
          1. Код при добавлении на страницу наследует стили. Чтобы их переопределить, добавьте стили, приведенные ниже.
          Внимание
          Рекомендуется добавить стили в тег style под тегом script, который вы получили на вкладке Кастомизация виджета для приоритета стилей виджета.
          Copy
          Full screen
          Small screen
           1/* This should be used for button positioning but note this technically repositions the entire widget */
           2#xsolla-buy-button-widget {
           3  /* place code for button positioning here */
           4}
           5
           6/* Styles the button itself */
           7.x-buy-button-widget.x-buy-button-widget__tiny
           8  .x-buy-button-widget-payment-button {
           9  background-color: #ff005b;
          10  color: black;
          11}
          12
          13/* Button on hover */
          14.x-buy-button-widget.x-buy-button-widget__tiny
          15  .x-buy-button-widget-payment-button:hover {
          16  background-color: #ff005b;
          17}
          18
          19/* The following are style overrides to leave you with just the button */
          20
          21/* space immediately surrounding button */
          22.x-buy-button-widget-button-block.x-buy-button-widget-button-block__light {
          23  background-color: white;
          24}
          25
          26/* space above button (including game title area) */
          27.x-buy-button-widget.x-buy-button-widget__tiny
          28  .x-buy-button-widget-game-logo {
          29  height: 200px;
          30  background-image: none !important;
          31  background-color: white;
          32}
          33
          34 /* Game title (located right above button) */
          35.x-buy-button-widget-game-name.x-buy-button-widget-game-name__light {
          36  display: none !important;
          37}
          
          Внимание
          • Важно вставить скопированный код виджета, поскольку приведенные выше имена ID или классов и сам фрагмент кода используются вместе с ним (шаг 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
           1<div id="xsolla-buy-button-widget"></div>
           2<div id="xsolla-buy-button-widget-2"></div>
           3
           4<script>
           5  var options = {
           6    project_id: "191204",
           7    sku: "789",
           8    item_type: "unit",
           9    api_settings: {
          10      sandbox: false
          11    },
          12    widget_ui: {
          13      target_element: "#xsolla-buy-button-widget",
          14      theme: {
          15        foreground: "gold",
          16        background: ""
          17      }
          18    },
          19    payment_widget_ui: {
          20      lightbox: {
          21        height: "700px",
          22        spinner: "round"
          23      }
          24    }
          25  };
          26
          27  // options for second buy button - note the different SKU and target_element
          28  var options2 = {
          29    project_id: "191204",
          30    sku: "123",
          31    item_type: "unit",
          32    api_settings: {
          33      sandbox: false
          34    },
          35    widget_ui: {
          36      target_element: "#xsolla-buy-button-widget-2",
          37      theme: {
          38        foreground: "gold",
          39        background: ""
          40      }
          41    },
          42    payment_widget_ui: {
          43      lightbox: {
          44        height: "700px",
          45        spinner: "round"
          46      }
          47    }
          48  };
          49
          50  var s = document.createElement("script");
          51  s.type = "text/javascript";
          52  s.async = true;
          53  s.src = "https://cdn.xsolla.net/embed/buy-button/3.1.4/widget.min.js";
          54
          55  // one event listener per widget instance. repeat for more buttons, passing in different SKUs
          56  s.addEventListener("load", function () {
          57    var widgetInstance = XBuyButtonWidget.create(options);
          58  });
          59  s.addEventListener("load", function () {
          60    var widgetInstance2 = XBuyButtonWidget.create(options2);
          61  });
          62
          63  document.getElementsByTagName("head")[0].appendChild(s);
          64</script>
          
          Внимание
          • Строки 1 и 2 содержат div для каждой кнопки. У каждого div есть свой уникальный ID.
          • Объект с именем options2 содержит параметры для второй кнопки (начиная со строки 26). У вас будет набор таких объектов options, аналогично приведенным выше, для каждой кнопки Купить. Обратите внимание на разные sku (строка 28) и target_element (строка 34, указывающая на div в строке 2).
          Была ли статья полезна?
          Спасибо!
          Что может сделать страницу еще лучше? Сообщение
          Жаль, что так произошло
          Расскажите, почему статья не была полезна. Сообщение
          Спасибо за обратную связь!
          Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
          Последнее обновление: 19 сентября 2025

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

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