Формирование платежного токена на стороне клиента

Формирование платежного токена на стороне сервера

Тестирование

Настройка каталога

Кастомизация

Промоакции

Управление платежным интерфейсом

Anti-fraud

Быстрый старт

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

Чтобы интегрировать решение Payments:

Создайте проект в Личном кабинете. Один проект соответствует одной игре. Если у вас несколько игр, создайте проект для каждой из них.
Добавьте ваши товары для продажи в каталог на стороне Xsolla.
Протестируйте создание заказа, который будет оплачивать пользователь.
Протестируйте совершение тестовой покупки и настройте оповещения.
Подпишите лицензионный договор с Xsolla в Личном кабинете, чтобы начать принимать реальные платежи.

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

Создание каталога

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

Создание виртуальных предметов

Получение списка предметов

Для получения списка предметов, вызовите метод API Получение списка виртуальных предметов:

В заголовке запроса передайте Xsolla Login JWT (Bearer-токен), который используется по умолчанию для авторизации пользователей. Для проверки вызова метода вы можете использовать тестовый токен: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI.
В path-параметре project_id передайте ID проекта, который вы можете найти в Личном кабинете:

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

Создание заказа

Заказ — это товары, которые пользователь выбрал для покупки в магазине. После того как заказ оплачен, пользователь получает товары. Чтобы совершить платеж, пользователь должен быть авторизован в игре.

Выберите способ интеграции, подходящий для вашей игры, чтобы посмотреть инструкцию для настройки.

Характеристики	На стороне сервера	На стороне клиента
Наличие сервера	Вам необходимо иметь собственный сервер для получения токена, а также контролировать нагрузку на него.	Вам не нужен свой сервер.
Определение страны пользователя	Вам необходимо передать в платежном токене либо страну, либо IP-адрес. Это влияет на выбор способов оплаты, доступных для пользователя.	Xsolla определяет страну пользователя по IP-адресу.
Определение валюты для оплаты	Если вы не передали валюту в токене, она будет определяться согласно стране. Если вы передали валюту в токене, пользователь оплачивает заказ в этой валюте.	Валюта определяется согласно стране.

Вызовите метод API Create payment token for purchase и передайте в нем информацию о пользователе и о товаре. Используя этот метод API, вы сможете продавать как один, так и несколько товаров.

Чтобы использовать тестовое окружение (sandbox-режим), передайте параметр “sandbox”: true в теле запроса на получение токена.

Значение параметра user_id:

При тестировании вы можете передать в параметре любые символы.
Для приема реальных платежей передайте в параметре ID пользователя из вашей системы. Этот ID будет передаваться в вебхуке Проверка пользователей.

Пример запроса:

Copy

Full screen

Small screen

curl -i -X POST \
  -u 224575:MYAPIKEY \
  https://store.xsolla.com/api/v2/project/224575/admin/payment/token \
  -H 'Content-Type: application/json' \
  -d '{
    "user": {
      "id": {
        "value": "myUserID"
      }
    },
    "purchase": {
      "items": [
        {
          "sku": "mySKU",
          "quantity": 1
        }
      ]
    },
    "sandbox": true
  }'

Интегрируйте продукт Xsolla Login:

Используя настроенный способ авторизации Xsolla, создайте и сохраните авторизационный токен пользователя, чтобы получить платежный токен. Платежный токен используется для открытия платежного интерфейса и совершения оплаты.

Для тестирования оплаты создайте заказ, используя метод API Create order with specified item:

Если вы тестируете на сайте документации API, нажмите Try it для открытия интерфейса создания запроса.
В блоке Security в поле Bearer Token введите токен, полученный при прохождении аутентификации.
В блоке Body передайте информацию о заказе, например количество товара. Чтобы получить доступ к тестовому окружению, передайте "sandbox": true.
В блоке Parameters введите:
- project_id — ID проекта, который вы можете найти в Личном кабинете.
- item_sku — артикул товара.

В ответе вы получите данные, которые вам понадобятся для дальнейшей работы:

token — платежный токен.

Пример запроса:

Copy

Full screen

Small screen

curl -i -X POST \
  'https://store.xsolla.com/api/v2/project/{project_id}/payment/item/{item_sku}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "quantity": 5,
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

Для работы с Xsolla API вы можете использовать готовые методы SDK для игровых движков и платформ:

Совершение тестовой покупки

При совершении тестовой покупки с реальных счетов не списываются деньги. Для тестирования вы можете использовать данные тестовых карт.

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

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

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

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

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

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

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

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

Информация о почтовом индексе

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

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

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

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

Если вы настраиваете интеграцию на стороне сервера, вам необходимо валидировать создаваемые заказы, отправляя соответствующие коды в ответ на вебхуки. Если вы настраиваете интеграцию на стороне клиента, вебхуки позволят вам получать уведомления о настроенных событиях (например, о статусе оплаты заказа).

Чтобы включить получение вебхуков:

Откройте проект в Личном кабинете.
Нажмите Настройки проекта в боковом меню и перейдите на вкладку Вебхуки.
В поле Сервер для вебхуков укажите URL-адрес вашего сервера для получения вебхуков в формате https://example.com. Вы также можете ввести URL-адрес из инструмента для тестирования вебхуков.
Секретный ключ проекта для подписи вебхуков генерируется по умолчанию. Если вы хотите изменить его, нажмите значок обновления.
Нажмите Получать вебхуки.

PHP SDK

Используйте готовые классы для обработки вебхуков.

Для тестирования вебхуков вы можете выбрать любой специализированный сайт, например webhook.site, или платформу, например ngrok.

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

Проверка существования пользователя — для оповещения о подтверждении регистрации пользователя в игре.
Успешный платеж — для оповещения о совершении платежа.

Подробная информация о настройке и тестировании вебхуков приведена в документации.

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

Обработчик вебхуков — это программный код, который позволяет принимать поступающие вебхуки на указанный URL-адрес, генерировать подпись и отправлять ответ на вебхук на сервер Xsolla.

Информация о генерации подписи и отправке ответов на вебхук

Генерация подписи

При получении вебхука необходимо обеспечить безопасность передачи данных. Для этого из данных вебхука необходимо сгенерировать подпись и проверить, что она совпадает с подписью, отправленной в заголовке HTTP-запроса. Чтобы сгенерировать подпись:

Осуществите конкатенацию JSON из тела запроса и секретного ключа проекта.
Примените SHA-1 криптографическую хэш-функцию к получившейся на первом шаге строке.

Отправка ответов на вебхук

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

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

Ваш обработчик вебхуков также может возвращать код 5xx при временных проблемах на вашем сервере. Если на вебхуки Успешная оплата заказа и Отмена заказа не был получен ответ или получен ответ с кодом 5xx, осуществляется повторная отправка вебхуков по следующему расписанию:

2 попытки с интервалом 5 минут;
7 попыток с интервалом 15 минут;
10 попыток с интервалом 60 минут.

Максимально осуществляется 20 попыток отправки вебхуков в течение 12 часов с момента первой попытки. Если на вебхук Успешный платеж не был получен ответ или получен ответ с кодом 5xx, также осуществляется повторная отправка вебхуков через увеличивающийся временной интервал. Максимально осуществляется 12 попыток в течение 12 часов. Если на вебхук Проверка существования пользователя не был получен ответ или получен ответ с кодом 400 или 5xx, повторная отправка вебхука Проверка существования пользователя не осуществляется. Пользователь увидит ошибку, вебхуки Успешный платеж и Успешная оплата заказа отправлены не будут.

Запуск

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

Подписание лицензионного договора

Подписание лицензионного договора позволит вам принимать реальные платежи, используя любые способы оплаты, поддерживаемые Xsolla. Чтобы подписать лицензионный договор:

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

Ваша заявка будет рассмотрена в течение 3 рабочих дней. Если в процессе проверки возникнут вопросы, Xsolla свяжется с указанным в заявке контактным лицом. После прохождения проверки на стороне Xsolla статус вашего договора изменится на Подписан.

Переключение на боевое окружение

После проведения первого реального платежа в силу вступает строгая политика платежей в тестовом окружении. Проведение платежа в тестовом окружении будет доступно только для пользователей, которые указаны в Личном кабинете в разделе Настройки компании > Пользователи.

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

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

Данное руководство включает в себя минимальный набор настроек для быстрого запуска. Если у вас возникли вопросы по подключению, пожалуйста, свяжитесь с нами через Xsolla Chat в правом нижнем углу страницы или напишите персональному менеджеру проекта на csm@xsolla.com.

Спасибо за обратную связь!

Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.

Оценить страницу

В другой раз

Спасибо за обратную связь!

Последнее обновление: 18 марта 2024

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

Содержание

Сценарий интеграции
Создание каталога
Создание виртуальных предметов
Получение списка предметов
Создание заказа
Совершение тестовой покупки
Открытие платежного интерфейса в тестовом окружении
Совершение тестового платежа
Настройка вебхуков
Настройка обработчика вебхуков
Запуск
Подписание лицензионного договора
Переключение на боевое окружение

Your browser is not supported. Please try a different browser

Payments

Быстрый старт

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

Создание каталога

Создание виртуальных предметов

Получение списка предметов

Создание заказа

Совершение тестовой покупки

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

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

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

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

Генерация подписи

Отправка ответов на вебхук

Запуск

Подписание лицензионного договора

Переключение на боевое окружение

Была ли статья полезна?

Оценить страницу

Спасибо за обратную связь!