Интеграция платежного решения
Чтобы отслеживать рефералов и совершать выплаты партнерам, необходимо выполнить интеграцию с Платежами Иксоллы. Требования:
- Платежный интерфейс подключен на оптимизированном сайте.
- Платежи Иксоллы являются единственным способом оплаты на сайте игры, в которую будет привлекаться трафик по программе Партнерской сети.
Получение токена
Для открытия платежного интерфейса необходимо получить токен. Токен — это строка, в которой содержится зашифрованная информация об игре и пользователе. Вам необходимо реализовать получение токена, чтобы идентифицировать пользователя для начисления покупки.
В серверной части вашего приложения реализуйте получение авторизационного токена. Для этого используйте HTTP POST-запрос с базовой HTTP-аутентифтикацией и передайте в теле запроса обязательные параметры.
Время жизни токена — 14 часов с момента последнего обращения к API Иксоллы. Реализуйте получение нового токена после истечения срока действия. Рекомендуется получать новый токен в фоновом режиме, без необходимости повторного входа пользователя в приложение.
Базовая HTTP-аутентификация
API Иксоллы использует базовую HTTP-аутентификацию. Все запросы к API должны содержать заголовок 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 должен храниться на вашем сервере и никогда — в бинарных файлах или на фронтенде.
Тело запроса
В теле запроса передайте обязательные параметры:
Параметр | Тип | Описание |
---|---|---|
user.id | string | Уникальный идентификатор пользователя в вашей системе. |
user.email | string | Email-адрес пользователя для отправки чеков. Если параметр не передан в запросе, на платежной форме появляется обязательное поле для ввода email-адреса. |
settings.project_id | integer | Идентификатор игры в Иксолле. Вы можете найти эту информацию в Личном кабинете в разделе вашего проекта. |
Для улучшения пользовательского опыта, вы также можете передать следующие параметры:
Параметр | Тип | Описание |
---|---|---|
user.name | string | Никнейм пользователя, который отображается в чеке. |
settings.currency | string | Предпочтительная валюта платежа. |
settings.language | string | Язык платежного интерфейса. |
Пример запроса для получения авторизационного токена пользователя
curl -i -X POST \
-u 2340:ZHgbSDVP6LtAJVWu \
https://api.xsolla.com/merchant/v2/merchants/<merchant_id>/token \
-H 'Content-Type: application/json' \
-d '{
"settings": {
"currency": "USD",
"language": "en",
"project_id": <project_id>
}
},
"user": {
"email": {
"value": "<user_email>"
},
"id": {
"value": "<user_id>"
},
"name": {
"value": "<user_name>"
}
}
}'
Пример авторизационного токена пользователя, который приходит в ответе
{
"token": "1230OWrp0KF6uqvmN8jWuzLyoXMzxTyK_lc_en"
}
Открытие платежного интерфейса
Тестирование платежей до подписания договора с Иксоллой доступно только в тестовом окружении. Если у вас возникли ошибки, изучите их описания.
Для открытия платежного интерфейса в тестовом окружении используйте ссылку https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN
, где ACCESS_TOKEN
— токен, полученный на предыдущем шаге.
Новое окно
Чтобы открыть платежный интерфейс в новом окне, используйте URL-адрес https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN
, где TOKEN
— это полученный токен.
https://secure.xsolla.com/paystation4/?token=TOKEN
.Вы также можете открывать платежный интерфейс другими способами:
- С помощью скрипта Pay Station Embed. Ограничение: могут возникнуть проблемы с открытием во внутриигровом браузере (WebView).
- В iframe. Ограничение: могут возникнуть проблемы с открытием во внутриигровом браузере (WebView) и в мобильной версии приложения.
Pay Station Embed
ПРИМЕР АСИНХРОННОЙ ЗАГРУЗКИ СКРИПТА
- html
<script>
var options = {
access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
sandbox: true //TODO please do not forget to remove this setting when going live
};
var s = document.createElement('script');
s.type = "text/javascript";
s.async = true;
s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
s.addEventListener('load', function (e) {
XPayStationWidget.init(options);
}, false);
var head = document.getElementsByTagName('head')[0];
head.appendChild(s);
</script>
<button data-xpaystation-widget-open>Buy Credits</button>
Pay Station Embed позволяет обрабатывать через механизм postMessage
события платежного интерфейса, которые вы можете отправлять в систему аналитики. Чтобы узнать, как настроить обработку событий в вашей системе аналитики, обратитесь к аккаунт-менеджеру проекта или напишите на адрес am@xsolla.com.
Команда Иксоллы создала виджет для упрощения интеграции платежного интерфейса на вашем сайте. Скрипт виджета доступен в нашем проекте на GitHub.
Список параметров для инициализации виджета:
Параметр | Тип | Описание |
---|---|---|
access_token | string | Токен, полученный по API. Обязательный. |
sandbox | boolean | Передайте true для тестирования. Будет использоваться URL sandbox-secure.xsolla.com вместо secure.xsolla.com . |
lightbox | object | Объект со списком настроек, доступных в случае открытия в lightbox (для полноэкранной версии). |
lightbox.width | string | Ширина lightbox. Значение по умолчанию null . Если установлено значение null , ширина lightbox соответствует ширине платежного интерфейса. |
lightbox.height | string | Высота lightbox. Значение по умолчанию 100% . Если установлено значение null , высота lightbox соответствует высоте платежного интерфейса. |
lightbox.zIndex | integer | Свойство, отвечающее за положение объекта, по умолчанию 1000 . |
lightbox.overlayOpacity | integer | Непрозрачность верхнего слоя (от 0 до 1), по умолчанию .6 . |
lightbox.overlayBackground | string | Фон для верхнего слоя, по умолчанию #000000 . |
lightbox.modal | boolean | Если установлено значение true , lightbox нельзя закрыть. По умолчанию false . |
lightbox.closeByClick | boolean | Если установлено значение true , lightbox закрывается при нажатии на верхний слой. По умолчанию true . |
lightbox.closeByKeyboard | boolean | Если установлено значение true , lightbox закрывается при нажатии ESC. По умолчанию true . |
lightbox.contentBackground | string | Фон фрейма, по умолчанию #ffffff . Обратите внимание, что настройка влияет только на фон фрейма lightbox и не меняет фон окна платежного интерфейса. |
lightbox.contentMargin | string | Отступ вокруг фрейма, по умолчанию 10px . |
lightbox.spinner | string | Тип прелоадера, может принимать значение xsolla или round , по умолчанию xsolla . |
lightbox.spinnerColor | string | Цвет прелоадера. |
childWindow | object | Настройки дочернего окна, в котором открывается платежный интерфейс. Работает для мобильной версии. |
childWindow.target | string | Свойство, определяющее, где должно быть открыто дочернее окно, может принимать значения _blank , _self , _parent , по умолчанию _blank . |
Скрипт позволяет вам отслеживать события, происходящие в платежном интерфейсе. В зависимости от типа события вы можете выполнять различные действия на вашей странице.
Список событий:
Параметр | Описание |
---|---|
init | Инициализация виджета. |
open | Открытие виджета. |
load | Событие после загрузки платежного интерфейса. |
close | Событие после закрытия платежного интерфейса. |
status | Событие, когда пользователь попадает на страницу статуса. |
status-invoice | Событие, когда пользователь попадает на страницу статуса, но платеж еще не завершен. |
status-delivering | Событие, когда пользователь попадает на страницу статуса, платеж завершен, мы прислали оповещение о платеже. |
status-done | Событие, когда пользователь попадает на страницу статуса, платеж успешно зачислен. |
status-troubled | Событие, когда пользователь попадает на страницу статуса, но платеж не прошел. |
Если вы хотите самостоятельно открывать платежный интерфейс, используйте ссылку https://secure.xsolla.com/paystation4/?token=TOKEN
.
Для тестирования используйте URL-адрес https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN
.
access_token
содержит приватную информацию о пользователе. Убедитесь, что вы получаете этот параметр только при server-server взаимодействии.Iframe
Чтобы открыть платежный интерфейс внутри iframe:
- Реализуйте механизм
postMessage
для получения событий от платежного интерфейса. - Откройте платежный интерфейс, используя ссылку
https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN
, гдеTOKEN
— это полученный токен.
Настройка вебхуков
Если вы хотите получать уведомления о событиях (например, о статусе оплаты товара), настройте вебхуки в Личном кабинете:
- Откройте ваш проект в Личном кабинете.
- Нажмите Настройки проекта в боковом меню и перейдите в раздел Вебхуки.
- Установите переключатель Вебхуки в положение Вкл.
- Укажите URL-адрес, на который вы хотите получать вебхуки.
- Секретный ключ проекта для подписи вебхуков генерируется по умолчанию. Если вы хотите изменить его, нажмите значок обновления.
- Нажмите Сохранить настройки.
Рекомендуется реализовать обработку основных типов вебхуков:
- Проверка существования пользователя
- Успешный платеж
- Получение состава корзины при покупке
- Возврат платежа
- Частичный возврат платежа
Чтобы подтвердить получение вебхука, ваш сервер должен вернуть:
- 204 HTTP-код без тела сообщения в случае успешного ответа.
- 400 HTTP-код с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись.
Тестирование процесса оплаты
Для тестирования процесса оплаты вы можете использовать тестовое окружение (sandbox-режим). Тестовое окружение — это автономная рабочая среда, в которой доступны все функции live-режима, кроме проведения реальных платежей и отмены платежей. Чтобы получить доступ к тестовому окружению, передайте параметр "mode":"sandbox"
при получении токена.
Используя тестовое окружение, вы можете тестировать процесс оплаты с помощью:
Тестирование оплаты банковской картой
- Откройте платежный интерфейс в тестовом окружении.
- Выберите группу способов оплаты Оплата банковской картой.
- Введите реквизиты карты. Остальные поля могут быть заполнены любыми данными. Вы также можете указать неверные реквизиты (номер карты или срок действия) для генерации ошибки.
- Нажмите Далее.
Кроме реквизитов карты вам потребуется указать индекс, если выполняется хотя бы одно из условий:
- Страна пользователя определена как США или Канада.
- Идентификатор карты (БИН) указывает на то, что карта выпущена в США.
Вы можете указать произвольное числовое значение в качестве индекса (например, 12345). Он используется для определения ставки налога на продажу и не влияет на прохождение тестового платежа.
Платежи банковской картой в тестовом окружении могут проводиться в следующих валютах: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.
Тестирование оплаты с помощью PayPal
Создание тестового аккаунта PayPal
Для тестирования процесса оплаты вам необходимо создать аккаунт для тестового окружения PayPal:
- Откройте сайт PayPal для разработчиков.
- Войдите в свой аккаунт или создайте новый.
- Перейдите на вкладку
Sandbox accounts . - На странице
Sandbox test accounts нажмитеCreate account . - Выберите тип аккаунта
Personal (Buyer Account) и необходимую страну. - Нажмите
Create .
Созданный аккаунт появится в списке тестовых аккаунтов.
Вы также можете использовать данные уже созданных тестовых аккаунтов:
sb-xmxij16980134@business.example.com | oi9_m_KW |
sb-p7pju16979920@business.example.com | 7%%p8ioS |
Совершение тестового платежа
- Откройте платежный интерфейс в тестовом окружении.
- Выберите способ оплаты PayPal.
- В поле
Mock Response Code введите0
или оставьте поле пустым. - В поле Индекс введите любые 5 цифр.

- Нажмите Оплатить. Вы будете перенаправлены на окно для входа в аккаунт PayPal.
- Введите данные вашего тестового аккаунта:
Email ID в качестве email-адреса иSystem Generated Password в качестве пароля. Чтобы найти эти данные:- Войдите в свой аккаунт на сайте PayPal для разработчиков.
- Перейдите на вкладку
Sandbox accounts . - На странице
Sandbox test accounts выберите тестовый аккаунт. - Нажмите ••• и в раскрывающемся списке выберите View/Edit account. Вы увидите необходимые данные в открывшемся модальном окне.
- Завершите тестовый платеж.
Запуск
После выполнения предыдущих шагов вы можете начать принимать реальные платежи:
- Убедитесь, что вы подписали договор с Иксоллой.
- Уберите параметр
"sandbox": true
из тела запроса при получении токена. - Откройте платежный интерфейс по ссылке
https://secure.xsolla.com/paystation4/?token=TOKEN
.
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.