Партнерская сеть / Интеграция платежного решения
 На главную

Партнерская сеть

  • Руководство по интеграции

  • Возможности

  • Инструкции

  • Расширения

  • Справочники

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

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

    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.

    Внимание

    Подробная информация о работе с ключами API приведена в справочнике API.

    Основные рекомендации:

    • Сохраните созданный ключ API на вашей стороне. Вы можете посмотреть ключ API в Личном кабинете только один раз при его создании.
    • Никому не сообщайте ваш ключ API, так как он дает доступ к управлению аккаунтом и проектами в Личном кабинете.
    • Ключ API должен храниться на вашем сервере и никогда — в бинарных файлах или на фронтенде.

    Тело запроса

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

    ПараметрТипОписание
    user.id
    stringУникальный идентификатор пользователя в вашей системе.
    user.email
    stringEmail-адрес пользователя для отправки чеков. Если параметр не передан в запросе, на платежной форме появляется обязательное поле для ввода email-адреса.
    settings.project_id
    integerИдентификатор игры в Иксолле. Вы можете найти эту информацию в Личном кабинете в разделе вашего проекта.

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

    ПараметрТипОписание
    user.name
    stringНикнейм пользователя, который отображается в чеке.
    settings.currency
    stringПредпочтительная валюта платежа.
    settings.language
    stringЯзык платежного интерфейса.

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

    Copy
    Full screen
    Small screen

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

      Пример авторизационного токена пользователя, который приходит в ответе

      Copy
      Full screen
      Small screen

        {
            "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 — это полученный токен.

        Примечание
        Эта ссылка для открытия платежного интерфейса в тестовом окружении (sandbox-режиме). После запуска проекта используйте URL-адрес https://secure.xsolla.com/paystation4/?token=TOKEN.

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

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

        Pay Station Embed

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

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

        Copy
        Full screen
        Small screen

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

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

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

        Внимание
        Параметр access_token содержит приватную информацию о пользователе. Убедитесь, что вы получаете этот параметр только при server-server взаимодействии.

        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-код с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись.

        Примечание
        Полный список и механизм работы вебхуков с примерами обработки подробно описаны в справочнике API.

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

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

        Примечание
        Тестирование платежей до подписания договора с Иксоллой доступно только в тестовом окружении.

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

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

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

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

        • Страна пользователя определена как США или Канада.
        • Идентификатор карты (БИН) указывает на то, что карта выпущена в США.

        Вы можете указать произвольное числовое значение в качестве индекса (например, 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:

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

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

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

        Email IDSystem Generated Password
        sb-xmxij16980134@business.example.comoi9_m_KW
        sb-p7pju16979920@business.example.com7%%p8ioS

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

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

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

        Внимание
        Изучите все доступные сценарии тестирования разовой оплаты и сохраненных аккаунтов PayPal.

        Запуск

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

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

        Внимание
        После проведения первого реального платежа в силу вступает строгая политика платежей в тестовом окружении. Проведение платежа в тестовом окружении будет доступно только для пользователей, которые указаны в Личном кабинете в разделе Настройки компании > Пользователи.
        Прогресс интеграции
        Спасибо за обратную связь!
        Последнее обновление: 5 июля 2021

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

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