Интеграция платежного решения

Чтобы отслеживать рефералов и совершать выплаты партнерам, необходимо выполнить интеграцию с Платежами Иксоллы. Требования:

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

Получение токена

Для открытия платежного интерфейса необходимо получить токен. Токен — это строка, в которой содержится зашифрованная информация об игре и пользователе. Вам необходимо реализовать получение токена, чтобы идентифицировать пользователя для начисления покупки.

В серверной части вашего приложения реализуйте получение авторизационного токена. Для этого используйте HTTP POST-запрос с базовой HTTP-аутентифтикацией и передайте в теле запроса обязательные параметры.

Справочник API

Посмотреть полный список параметров.

Время жизни токена — 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.

Тело запроса

В теле запроса передайте обязательные параметры:

Для улучшения пользовательского опыта, вы также можете передать следующие параметры:

Пример запроса для получения авторизационного токена пользователя

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"
}

Открытие платежного интерфейса

Новое окно

Чтобы открыть платежный интерфейс в новом окне, используйте URL-адрес https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, где TOKEN — это полученный токен.

Вы также можете открывать платежный интерфейс другими способами:

• С помощью скрипта Pay Station Embed. Ограничение: могут возникнуть проблемы с открытием во внутриигровом браузере (WebView).
• В iframe. Ограничение: могут возникнуть проблемы с открытием во внутриигровом браузере (WebView) и в мобильной версии приложения.

Pay Station Embed

ПРИМЕР АСИНХРОННОЙ ЗАГРУЗКИ СКРИПТА

<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.

Список параметров для инициализации виджета:

Скрипт позволяет вам отслеживать события, происходящие в платежном интерфейсе. В зависимости от типа события вы можете выполнять различные действия на вашей странице.

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

Если вы хотите самостоятельно открывать платежный интерфейс, используйте ссылку https://secure.xsolla.com/paystation4/?token=TOKEN.

Для тестирования используйте URL-адрес https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN.

Iframe

Чтобы открыть платежный интерфейс внутри iframe:

1. Реализуйте механизм postMessage для получения событий от платежного интерфейса.
2. Откройте платежный интерфейс, используя ссылку https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, где TOKEN — это полученный токен.

Настройка вебхуков

Если вы хотите получать уведомления о событиях (например, о статусе оплаты товара), настройте вебхуки в Личном кабинете:

1. Откройте ваш проект в Личном кабинете.
2. Нажмите Настройки проекта в боковом меню и перейдите в раздел Вебхуки.
3. Установите переключатель Вебхуки в положение Вкл.
4. Укажите URL-адрес, на который вы хотите получать вебхуки.
5. Секретный ключ проекта для подписи вебхуков генерируется по умолчанию. Если вы хотите изменить его, нажмите значок обновления.
6. Нажмите Сохранить настройки.

Рекомендуется реализовать обработку основных типов вебхуков:

• Проверка существования пользователя
• Успешный платеж
• Получение состава корзины при покупке
• Возврат платежа
• Частичный возврат платежа

Чтобы подтвердить получение вебхука, ваш сервер должен вернуть:

• 204 HTTP-код без тела сообщения в случае успешного ответа.
• 400 HTTP-код с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись.

Тестирование процесса оплаты

Для тестирования процесса оплаты вы можете использовать тестовое окружение (sandbox-режим). Тестовое окружение — это автономная рабочая среда, в которой доступны все функции live-режима, кроме проведения реальных платежей и отмены платежей. Чтобы получить доступ к тестовому окружению, передайте параметр "mode":"sandbox" при получении токена.

Используя тестовое окружение, вы можете тестировать процесс оплаты с помощью:

• банковской карты;
• PayPal.

Тестирование оплаты банковской картой

1. Откройте платежный интерфейс в тестовом окружении.
2. Выберите группу способов оплаты Оплата банковской картой.
3. Введите реквизиты карты. Остальные поля могут быть заполнены любыми данными. Вы также можете указать неверные реквизиты (номер карты или срок действия) для генерации ошибки.
4. Нажмите Далее.

Список тестовых карт

Посмотрите список тестовых банковских карт.

Тестирование оплаты с помощью PayPal

Создание тестового аккаунта PayPal

Для тестирования процесса оплаты вам необходимо создать аккаунт для тестового окружения PayPal:

1. Откройте сайт PayPal для разработчиков.
2. Войдите в свой аккаунт или создайте новый.
3. Перейдите на вкладку Sandbox accounts.
4. На странице Sandbox test accounts нажмите Create account.
5. Выберите тип аккаунта Personal (Buyer Account) и необходимую страну.
6. Нажмите Create.

Созданный аккаунт появится в списке тестовых аккаунтов.

Вы также можете использовать данные уже созданных тестовых аккаунтов:

Совершение тестового платежа

1. Откройте платежный интерфейс в тестовом окружении.
2. Выберите способ оплаты PayPal.
3. В поле Mock Response Code введите 0 или оставьте поле пустым.
4. В поле Индекс введите любые 5 цифр.

5. Нажмите Оплатить. Вы будете перенаправлены на окно для входа в аккаунт PayPal.
6. Введите данные вашего тестового аккаунта: Email ID в качестве email-адреса и System Generated Password в качестве пароля. Чтобы найти эти данные:
   1. Войдите в свой аккаунт на сайте PayPal для разработчиков.
   2. Перейдите на вкладку Sandbox accounts.
   3. На странице Sandbox test accounts выберите тестовый аккаунт.
   4. Нажмите ••• и в раскрывающемся списке выберите View/Edit account. Вы увидите необходимые данные в открывшемся модальном окне.
7. Завершите тестовый платеж.

Запуск

После выполнения предыдущих шагов вы можете начать принимать реальные платежи:

1. Убедитесь, что вы подписали договор с Иксоллой.
2. Уберите параметр "sandbox": true из тела запроса при получении токена.
3. Откройте платежный интерфейс по ссылке https://secure.xsolla.com/paystation4/?token=TOKEN.