Настройка продажи игровых ключей
Продажа игровых ключей возможна по прямой ссылке, через интерфейс магазина или через виджет.
Товар | Способ продажи |
---|---|
Одна копия игры (игровой ключ). | Прямая ссылка, виджет или интерфейс магазина. При продаже через интерфейс магазина используйте метод быстрой покупки без создания корзины. |
Несколько копий игры (игровых ключей) или разные игры в составе корзины. | Интерфейс магазина. Используйте Site Builder или интегрируйте Shop Builder API. |
Вы можете продавать игровые ключи неавторизованным и авторизованным пользователям.
Использование авторизации позволяет:
- задавать ограничение на продажу игровых ключей для пользователя;
- использовать персонализацию каталога товаров и акционных предложений;
- использовать систему владения играми;
- сохранять данные пользователей в платежном интерфейсе Xsolla.
Вы можете авторизовывать пользователей с помощью продукта Login или вашей собственной системы авторизации. Подробная информация о настройке приведена в инструкции.
Доступ к игре появляется автоматически при покупке игрового ключа, однако игровые платформы могут устанавливать свои правила активации ключей.
Вы можете ограничить время отображения пакета игровых ключей в каталоге, например, на время сезонных распродаж. Для этого в объекте periods
передайте дату начала и окончания периода доступности в формате ISO 8601 в соответствующем методе API:
Чтобы ограничить количество игровых ключей, которое доступно пользователю для покупки, следуйте инструкции.
Продажа через прямую ссылку
Для открытия платежного интерфейса используется ссылка:
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:
1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}&ui_settings=ewoJCQkic2l6ZSI6ICJzbWFsbCIsCgkJCSJ0aGVtZSI6ICJkYXJrIgoJCX0=
- Токен для передачи информации о пользователе. Используется только при продаже игровых ключей для авторизованных пользователей. Формируется в зависимости от типа аутентификации. Пример URL с токеном:
1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&xsolla_login_token={ACCESS_TOKEN}
- Параметр
mode=sandbox
для тестирования оплаты. Вы можете использовать тестовые банковские карты для проведения платежей.
- Пример URL-адреса для тестирования:
1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}&mode=sandbox
Продажа через интерфейс магазина
Вы можете продавать игровые ключи через интерфейс магазина. Для создания магазина вы можете:
- использовать Site Builder;
- создать свою версию магазина и интегрировать Shop Builder API.
Для продажи пакетов игровых ключей, используя Shop Builder API:
- Для отображения каталога используйте метод Получение списка игр.
Реализуйте покупку игровых ключей:
- Для быстрой покупки одного ключа используйте метод Создание заказа с указанным товаром. В ответе на данный метод вы получите токен, который необходимо использовать для открытия платежного интерфейса.
- Для покупки нескольких игровых ключей используйте методы работы с корзиной:
- Обновление товара из текущей корзины для добавления игрового ключа в корзину.
- Получение корзины текущего пользователя для получения списка игровых ключей в корзине.
- Создание заказа с указанным товаром для оплаты игровых ключей в корзине. В ответе на данный метод вы получите токен, который необходимо использовать для открытия платежного интерфейса.
items.unit_items.sku
из запроса на получение списка игр.Продажа через виджет
Вы можете добавить виджет для продажи игровых ключей на свою страницу и кастомизировать его. Чтобы скопировать код виджета перейдите в раздел Кастомизация виджета после создания пакета ключей в Личном кабинете.
Если игра продается на одной платформе, в виджете будет указана цена игры на этой платформе.
Пример: Купить сейчас за $10.
Если игра продается на нескольких платформах, в виджете будет указана наименьшая из цен среди платформ.
Пример: Купить от $10.
В окне оформления заказа пользователь сможет увидеть цены на всех платформах и сделать выбор.
Вы также можете отобразить в виджете цену на конкретной платформе, указав название платформы в параметре drm.

Пример кода виджета:
- html
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 | integer | ID проекта, в который загружены игровые ключи или бандлы с игровыми ключами, внутриигровые товары или бандлы с товарами. |
item_type | string | Тип предмета. Может принимать значения virtual_good , virtual_currency , game_key , unit . Тип unit используется, когда есть несколько платформ распространения игры. |
sku | string | Уникальный ID предмета. |
drm | string | Артикул платформы распространения игры, например, steam . Позволяет отобразить цену на конкретной платформе. |
api_settings | object | Настройки для выбора окружения и хоста:
|
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 | Шаблон. Возможные значения:
|
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
.
Кастомизация кнопки
- В проекте в Личном кабинете перейдите в раздел Каталог товаров > Игровые ключи.
- Выберите нужный вам игровой ключ и перейдите на вкладку Кастомизация виджета.
- В блоке Кастомизировать выберите цвет фона.
theme
свойство background
с пустым значением.- Код при добавлении на страницу наследует стили. Чтобы их переопределить, добавьте стили, приведенные ниже.
style
под тегом script
, который вы получили на вкладке Кастомизация виджета для приоритета стилей виджета.- css
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. Пример миграции:
- html
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).
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.