Настройка продажи игровых ключей
Продажа игровых ключей возможна по прямой ссылке, через интерфейс магазина или через виджет.
Товар | Способ продажи |
---|---|
Одна копия игры (игровой ключ). | Прямая ссылка, виджет или интерфейс магазина. При продаже через интерфейс магазина используйте метод быстрой покупки без создания корзины. |
Несколько копий игры (игровых ключей) или разные игры в составе корзины. | Интерфейс магазина. Используйте Site Builder или интегрируйте Shop Builder API. |
Вы можете продавать игровые ключи неавторизованным и авторизованным пользователям.
Использование авторизации позволяет:
- задавать ограничение на продажу игровых ключей для пользователя;
- использовать персонализацию каталога товаров и акционных предложений;
- использовать систему владения играми;
- сохранять данные пользователей в платежном интерфейсе Xsolla.
Вы можете авторизовывать пользователей с помощью продукта Login или вашей собственной системы авторизации. Подробная информация о настройке приведена в инструкции.
Доступ к игре появляется автоматически при покупке игрового ключа, однако игровые платформы могут устанавливать свои правила активации ключей.
Вы можете ограничить время отображения пакета игровых ключей в каталоге, например, на время сезонных распродаж. Для этого в объекте periods
передайте дату начала и окончания периода доступности в формате ISO 8601 в соответствующем методе API:
Чтобы ограничить количество игровых ключей, которое доступно пользователю для покупки, следуйте инструкции.
Продажа через прямую ссылку
Для открытия платежного интерфейса используется ссылка:
- curl
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 проекта из раздела Настройки проекта > Общие настройки > ID проекта в Личном кабинете.YOUR-ITEM-SKU
— артикул пакета игровых ключей. Для продажи игры на конкретной платформе необходимо получить артикул с помощью запроса Получение списка игр (как правило, этот артикул выглядит какunit_name_drm_sku
).
- Внешний вид платежного интерфейса: тема (темная — dark или светлая — default), размер и другие параметры. Укажите в URL ссылки параметр
ui_settings
и в качестве значения передайте JSON-объектsettings.ui
в кодировке Base64. Пример URL с настройками UI:
- curl
1https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}&ui_settings=ewoJCQkic2l6ZSI6ICJzbWFsbCIsCgkJCSJ0aGVtZSI6ICJkYXJrIgoJCX0=
- Токен для передачи информации о пользователе. Используется только при продаже игровых ключей для авторизованных пользователей. Формируется в зависимости от типа аутентификации. Пример URL с токеном:
- curl
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-адреса для тестирования:
- curl
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.

Пример кода виджета:
1<div id="xsolla-buy-button-widget"></div>
2 <script>
3 var options = {
4 project_id: "101010",
5 sku: "my_key",
6 user: {
7 auth: "9qs9VyCIQQXBlzJQcfETIKWZDvhi4Sz1"
8 },
9 drm: "steam",
10 item_type: "unit",
11 api_settings: {
12 sandbox: true,
13 },
14 widget_ui: {
15 target_element: "#xsolla-buy-button-widget",
16 theme: {
17 foreground: "green",
18 background: "light"
19 },
20 },
21
22 payment_widget_ui: {
23 lightbox: {
24 height: '700px',
25 spinner: 'round'
26 }
27 }
28 };
29 var s = document.createElement('script');
30 s.type = "text/javascript";
31 s.async = true;
32 s.src = "https://cdn.xsolla.net/embed/buy-button/3.1.8/widget.min.js";
33 s.addEventListener('load', function (e) {
34 var widgetInstance = XBuyButtonWidget.create(options);
35 }, false);
36 var head = document.getElementsByTagName('head')[0];
37 head.appendChild(s);
38 </script>
39 <style>
40 #xsolla-buy-button-widget {
41
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
48 .x-buy-button-widget-payment-button {
49 background-color: #ff005b;
50 color: black;
51 }
52 </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
.
Кастомизация кнопки
- Откройте проект в Личном кабинете.
- В боковом меню нажмите Store.
- В панели Игровые ключи нажмите Настроить.
- Выберите нужный вам игровой ключ и перейдите на вкладку Кастомизация виджета.
- В блоке Кастомизировать выберите цвет фона.
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. Пример миграции:
- javascript
1<div id="xsolla-buy-button-widget"></div>
2<div id="xsolla-buy-button-widget-2"></div>
3 <script>
4 var options = {
5 project_id: "191204",
6 sku: "789",
7 item_type: "unit",
8 api_settings: {
9 sandbox: false,
10 },
11 widget_ui: {
12 target_element: "#xsolla-buy-button-widget",
13 theme: {
14 foreground: "gold",
15 background: "",
16 },
17 },
18 payment_widget_ui: {
19 lightbox: {
20 height: "700px",
21 spinner: "round",
22 },
23 },
24 };
25 // options for second buy button - note the different SKU and target_element
26 var options2 = {
27 project_id: "191204",
28 sku: "123",
29 item_type: "unit",
30 api_settings: {
31 sandbox: false,
32 },
33 widget_ui: {
34 target_element: "#xsolla-buy-button-widget-2",
35 theme: {
36 foreground: "gold",
37 background: "",
38 },
39 },
40 payment_widget_ui: {
41 lightbox: {
42 height: "700px",
43 spinner: "round",
44 },
45 },
46 };
47 var s = document.createElement("script");
48 s.type = "text/javascript";
49 s.async = true;
50 s.src = "https://cdn.xsolla.net/embed/buy-button/3.1.4/widget.min.js";
51
52// one event listener per widget instance. repeat for more buttons, passing in different SKUs
53 s.addEventListener(
54 "load",
55 function (e) {
56 var widgetInstance = XBuyButtonWidget.create(options);
57 },
58 false
59 );
60 s.addEventListener(
61 "load",
62 function (e) {
63 var widgetInstance2 = XBuyButtonWidget.create(options2);
64 },
65 false
66 );
67 var head = document.getElementsByTagName("head")[0];
68 head.appendChild(s);
69 </script>
- Строки 1 и 2 содержат
div
для каждой кнопки. У каждого div есть свой уникальный ID. - Объект с именем
options2
содержит параметры для второй кнопки (начиная со строки 26). У вас будет набор таких объектовoptions
, аналогично приведенным выше, для каждой кнопки Купить. Обратите внимание на разныеsku
(строка 28) иtarget_element
(строка 34, указывающая наdiv
в строке 2).
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.