Серверная интеграция

Этот тип интеграции подходит для партнеров, которые уже разработали игровую логику для авторизации, внутриигрового магазина и инвентаря игроков на своих серверах и хотят использовать платежный интерфейс Иксоллы. Необходимо получить Pay Station access token и настроить обработку вебхуков.

При серверной интеграции реализуется следующая логика обработки платежа:

  1. Клиент отправляет на сервер приложения запрос для открытия платежного интерфейса.
  2. Сервер приложения отправляет на сервер Иксоллы сведения о валюте и размере платежа.
  3. Сервер Иксоллы возвращает токен со сведениями о покупке и параметрах платежного интерфейса.
  4. Сервер приложения отправляет полученный токен на клиент.
  5. Клиент открывает платежный интерфейс в браузере с помощью SDK.
  6. После оплаты покупки на сервер приложения приходит вебхук со статусом платежа.

Сервер Discord
Общайтесь с командой Иксоллы и разработчиками, использующими продукты Иксоллы.

Сценарий интеграции

Для интеграции библиотеки Payments:

  1. Загрузите и установите Android Studio.
  2. Создайте новый проект.
  3. Настройте внутриигровой магазин и каталог товаров на вашем сервере.
  4. Настройте проект в Личном кабинете.
  5. Установите библиотеку.
  6. Настройте Return URL.
  7. Получите токен.
  8. Откройте платежный интерфейс.
  9. Настройте вебхуки.

После завершения интеграции протестируйте процесс оплаты.

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

Настройка проекта в Личном кабинете

  1. Зарегистрируйтесь в Личном кабинете.
  2. Настройте проект:
    1. Чтобы заполнить данные об игре автоматически, укажите Ссылку на вашу игру на любой платформе. В результате в настройки проекта добавятся изображение игры, ее название и описание.
    2. Чтобы заполнить данные об игре вручную, перейдите по ссылке У меня нет ссылки, настроить вручную и укажите:
      • языки проекта (английский установлен по умолчанию);
      • название проекта на всех добавленных языках;
      • сайт игры (опционально).
    3. Нажмите Создать проект.

В процессе интеграции вам понадобятся следующие параметры:

  • ID продавца, который можно найти в разделе Настройки проекта > Оповещения.

  • Ключ API, который можно найти в разделе Настройки компании > Ключ API.

  • ID проекта, который можно найти в разделе Настройки проекта > ID проекта.

  • Секретный ключ проекта, который можно найти в разделе Настройки проекта > Оповещения.

Установка библиотеки

Библиотека доступна в Maven Central.

Для установки библиотеки:

  1. Запустите Android Studio.
  2. Откройте файл build.gradle вашего приложения.
  3. Добавьте следующую строку в раздел зависимостей, где <version_number> — необходимая версия библиотеки Payments:

Последняя версия:

Copy
Full screen
Small screen
implementation 'com.xsolla.android:payments:<version_number>'

Настройка Return URL

Note
Return URL — URL-адрес страницы или путь в приложении, на который пользователь будет перенаправлен после совершения платежа.

Добавьте следующие строки в файл с исходным кодом вашего проекта, чтобы указать Return URL, настроенный в Личном кабинете.

Copy
Full screen
Small screen
<string name="xsolla_payments_redirect_scheme">app</string>
<string name="xsolla_payments_redirect_host">yourgame</string>

Здесь вы должны указать Return URL, разделенный на части. Пример приведен для app://yourgame.

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

Для получения токена используйте метод API Create payment token by server. Ваш сервер должен отправлять на сервер Иксоллы запрос со следующими данными:

  • идентификатор пользователя, совершившего покупку;
  • сумма платежа;
  • валюта платежа;
  • сведения о покупке (опционально);
  • параметры платежного интерфейса (опционально).

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

  • в виде списка предметов через параметр item;
  • в виде описания покупки через параметр description.

Параметры платежного интерфейса (например, язык локализации, свойства интерфейса, тема) передаются в объекте settings. Для включения/отключения sandbox-режима требуется изменить значение параметра sandbox в запросе на получение токена и изменить настройки SDK. Для изменения остальных настроек платежного интерфейса требуется изменить параметры запроса на получение токена.

Note
Вы можете передавать дополнительные сведения с помощью параметра custom_parameters. Эти сведения будут также передаваться в настроенных вебхуках.

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

Создание объекта Intent для платежного интерфейса

Чтобы открыть платежный интерфейс, передайте полученный на предыдущем шаге токен в метод SDK XPayments.createIntentBuilder.

Copy
Full screen
Small screen
val intent = XPayments.createIntentBuilder(getContext())
            .accessToken(AccessToken(token))
            .isSandbox(BuildConfig.IS_SANDBOX)
            .build()

Запуск Activity с использованием созданного Intent

Copy
Full screen
Small screen
startActivityForResult(intent, RC_PAYSTATION)

Извлечение результатов Activity

Copy
Full screen
Small screen
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
       super.onActivityResult(requestCode, resultCode, data)
       if (requestCode == RC_PAYSTATION) {
           val result = XPayments.Result.fromResultIntent(data)
       }
   }

В приведенном примере кода в переменную result передаются следующие данные:

  • Статус процесса оплаты — может принимать значения completed или canceled.
  • Идентификатор заявки на оплату — присваивается при успешной обработке платежа в платежном интерфейсе.

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

Copy
Full screen
Small screen
val (status, invoiceId) = XPayments.Result.fromResultIntent(data)

Notice
Не используйте данные о платеже, полученные с помощью методов SDK, для начисления товаров пользователю. Это небезопасный способ.

Чтобы начислять товары пользователю, получите данные о платеже на вашем сервере с помощью вебхуков. Данные, полученные с помощью методов SDK, используйте на стороне клиента, чтобы отображать статус покупки, пока сервер приложения не получит вебхук.

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

  1. Перейдите к вашему проекту в Личном кабинете.
  2. Перейдите в Настройки проекта > Оповещения, укажите URL оповещения и сгенерируйте секретный ключ проекта для подписи вебхуков.

  1. Сохраните настройки.
  2. Реализуйте обработку следующих типов вебхуков:

  1. Перейдите на вкладку Чекаут и нажмите Подключить.

  1. Протестируйте вебхуки.

Note
Чтобы подтвердить получение вебхука, ваш сервер должен вернуть:
  • 204 HTTP код без тела сообщения в случае успешного ответа;
  • 400 HTTP код с описанием проблемы, если указанный пользователь не был найден или если передана недействительная подпись.
Механизм работы вебхуков с примерами обработки подробно описан в справочнике API.

  1. Нажмите Платежи в боковом меню и перейдите в раздел Настройки.
  2. Установите переключатель Чекаут в положение Вкл.

  1. Нажмите Сохранить.

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

После успешной настройки библиотеки вы можете проверить процесс оплаты. По умолчанию все платежи проводятся в sandbox-режиме. Вы можете использовать тестовую банковскую карту для имитации успешного процесса оплаты.

Для тестирования оплаты на реальных платежах:

  • Убедитесь, что вы заключили договор с Иксоллой.
  • Установите .isSandbox(false) при сборке объекта Intent Paystation.
  • В запросе на получение токена для параметра sandbox укажите значение false.

Была ли статья полезна?
Спасибо!
Что может сделать страницу еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
Оценить страницу
Оценить страницу
Что может сделать страницу еще лучше?

В другой раз

Спасибо за обратную связь!
Последнее обновление: 18 января 2022

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

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