Частые вопросы

Интеграция

Как открыть платежный интерфейс внутри iframe?

Рекомендуется открывать платежный интерфейс в lightbox с помощью скрипта Pay Station Embed. Использование этого способа позволит вам:

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

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

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

Возможная проблема: Если при открытии платежного интерфейса в iframe не отображается кнопка копирования кода для подтверждения оплаты, который запрашивают некоторые платежные системы, передайте в iframe атрибут allow=“clipboard-read; clipboard-write; payment”.

Пример:

<iframe
  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
  width="800"
  height="700"
  allow="clipboard-read; clipboard-write; payment"
></iframe>

Какие IP-адреса необходимо добавить в список разрешений для настройки вебхуков?

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

• 185.30.20.0/24;
• 185.30.21.0/24;
• 185.30.23.0/24.

Если у вас подключен продукт Login, дополнительно добавьте обработку со следующих IP-адресов:

• 35.236.32.131;
• 34.94.154.26;
• 34.94.14.95;
• 34.102.48.30;
• 34.94.115.185;
• 34.94.173.132;
• 35.236.35.100;
• 35.236.117.164;
• 34.94.0.85;
• 35.235.99.248;
• 34.94.25.33.

У вас есть SDK под Node.JS/C#/Ruby/Java/ASP и т. п.?

Сейчас доступны SDK под PHP и Android, но вы можете создать собственный SDK под любой язык/платформу, где можно отправлять HTTPS-запросы.

Проверка существования пользователя

Что такое User ID?

User ID — это параметр, который позволяет идентифицировать пользователя в игре. Вы можете хранить ID пользователей в базе данных. При получении некорректных ID пользователей генерируйте исключения. Примеры пользовательской валидации вы можете найти в GitHub-репозитории.

Какие данные надо возвращать после валидации?

При успешной валидации вы должны вернуть HTTP-код 200. В случае ошибки — код 400 (INVALID_USER).

Настройки проекта

Нужно ли создавать отдельные проекты для каждой среды (QA, staging, production)?

Для тестирования рекомендуется использовать отдельные проекты, чтобы изменения не затрагивали среду production.

В чем разница между секретным ключом, ключом проекта и ключом API?

Секретный ключ и ключ проекта — это одно и то же. Он используется для формирования цифровой подписи, необходимой для проведения платежей. JSON-тело запроса конкатенируется с этим ключом, а затем результат хешируется при помощи SHA-1.

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

В чем разница между URL-адресом вебхука и URL-адресом возврата?

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

Где я могу найти ID проекта?

Откройте проект в Личном кабинете и перейдите в раздел Настройки проекта > Общие настройки.

Где я могу найти ID продавца?

Откройте Личный кабинет и перейдите в раздел Настройки компании > Компания.

Где мне найти ключ API?

Ключ API отображается в Личном кабинете только при создании и должен храниться на вашей стороне. Создать ключ можно в разделах:

• Настройки компании > Ключи API;
• Настройки проекта > Ключи API.

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

Необходимо ли для вебхуков использовать HTTPS?

Да.

Почему оповещение от Xsolla не пришло на URL-адрес вебхука?

Убедитесь, что ваш вебхук-сервер поддерживает необходимые виды HTTP-запросов (POST, GET).

Почему вебхуки не приходят на мое мобильное приложение?

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

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

Могу ли я изменить оформление платежного интерфейса?

Вы можете изменить стандартную тему на темную, передав в токене параметр settings.ui.theme = default_dark. Темная тема позволяет установить фоновое изображение или изменить цвет фона (как, например, в демо). Чтобы изменить другие настройки, обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com.

Могу ли я изменить оформление писем, отправляемых пользователю?

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

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

Могу ли я использовать тестовую карту для проверки платежа?

Да, но только в тестовом окружении вашего приложения и демоверсии платежного интерфейса с включенным тестовым окружением (sandbox-режимом). Вы можете найти тестовые карты разных брендов и стран выпуска в общем списке.

Могу ли я протестировать платеж через PayPal в тестовом окружении?

Как я могу протестировать возврат платежа?

С помощью API-метода Возврат платежа. Изучите подробную информацию в инструкции.

Что такое ID заявки в Xsolla и Invoice ID на вкладке тестирования вебхуков в Личном кабинете?

ID заявки в Xsolla — ID транзакции на стороне Xsolla. При тестировании вы можете указать любое числовое значение.

Invoice ID — это необязательный ID транзакции на стороне вашей игры. При тестировании вы можете указать любую комбинацию букв и цифр.

Платежи

Как я могу проверить валидность запроса на оплату, полученного в вебхуке?

Могу ли я сразу перенаправить пользователя на определенный способ оплаты?

Могу ли я сразу перенаправить пользователя на страницу успешной/ошибочной транзакции сразу после обработки платежа в зависимости от результата?

В моем биллинге номеру заказа присваивается order_id. Можно ли использовать order_id вместо user_id при получении токена?

Нет, для корректной работы требуется user_id.

Вы можете передать order_id дополнительно в параметре external_id. Для этого:

1. Откройте Личный кабинет.
2. Перейдите в раздел Pay Station > Настройки.
3. В блоке Дополнительные настройки установите переключатель External ID транзакции в положение Вкл.

Можно ли переопределять URL-адрес вебхука для каждой транзакции?

Буду ли я получать данные о неуспешных транзакциях?

Какая платежная опция позволяет добавлять VAT к общей сумме платежа?

Что такое PID?

Что такое External ID?

External ID — это ID транзакции в игре, который присваивается заказу в вашей системе. На стороне Xsolla External ID связан с ID транзакции, поэтому наличие External ID позволяет Xsolla предотвращать повторную оплату одной и той же транзакции. External ID должен быть уникальным для каждого платежа пользователя.

Чтобы включить External ID в проекте:

1. Откройте проект в Личном кабинете и перейдите в раздел Pay Station > Настройки.
2. Установите переключатель External ID транзакции в положение Вкл.

Нужно ли создавать новый External ID для каждой транзакции?

Какое значение установить для команды setExternalPaymentId?

Что такое прямые аккаунты?

Прямые аккаунты позволяют отображать в платежном интерфейсе платежные системы, с которыми у вас заключен прямой договор. Игроки по-прежнему оплачивают покупки выбранными ими способом, а вы получаете выплаты напрямую от платежных систем. Чтобы подключить прямые аккаунты, откройте свой проект в Личном кабинете и перейдите в раздел Pay Station > Прямые аккаунты.

Xsolla выступает поставщиком услуг и взимает сниженный процент revenue share: 1.25% от суммы транзакции + $0.10. Вы будете иметь полноценный доступ ко всем решениям Xsolla, но при этом обязуетесь самостоятельно:

• контролировать уплату налогов;
• заключать отдельный договор с каждой платежной системой;
• производить взаиморасчеты с платежными системами;
• контролировать уплату комиссий платежных систем, возвраты платежей, возврат средств, комиссии с выплат и расходы на оперирование.

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

Как мне перенести в Xsolla данные пользователей (сохраненные платежные аккаунты, подписки и т. д.)?

Обратитесь к персональному менеджеру проекта или напишите на csm@xsolla.com. Используйте PGP-шифрование, чтобы обеспечить конфиденциальность данных.

Параметры PGP-ключа Xsolla:

• ID ключа: FBA38225
• Тип ключа: RSA
• Длина ключа: 4096
• Уникальный отпечаток: 4D63 4B67 B265 5464 D39D 7228 67B0 672A FBA3 8225
• ID пользователя: admins@xsolla.com

-----BEGIN PGP PUBLIC KEY BLOCK-----
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
=7AyM
-----END PGP PUBLIC KEY BLOCK-----

Как определяется страна пользователя?

Когда вы используете клиентский метод API для формирования платежного токена, Xsolla определяет страну пользователя по IP-адресу запроса.

Когда вы используете серверный метод API для формирования платежного токена, страна определяется путем последовательной проверки:

• значения параметра user.country.value из тела запроса;
• IP-адреса из заголовка X-User-Ip.

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

Ошибки

Что делать при возникновении ошибки 0004-0008?

• Для открытия платежного интерфейса в тестовом окружении используйте ссылку: https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, где ACCESS_TOKEN — это полученный токен.
• Для совершения реальных платежей используйте ссылку: https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, где ACCESS_TOKEN — это полученный токен.

Что делать при возникновении ошибок 2205 и 2207 (user ID error)?

• Передайте корректный ID пользователя — user_id из вашей базы данных.
• Рекомендации относительно использования вебхуков:
  • Если вы не хотите использовать вебхуки, проверьте, чтобы они были выключены в проекте. Для этого перейдите в Личный кабинет в раздел Настройки проекта > Вебхуки и установите переключатель в положение Выкл.
  • Если вы хотите использовать вебхуки, реализуйте успешную обработку вебхука Проверка существования пользователя.

Что делать при возникновении ошибки 1000-0003?

Что делать при возникновении ошибки 0002-0004?

Что делать при возникновении ошибки 3032?

Почему в вебхук-запросе нет заголовка Authorization?

Контактная информация

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

• Нажмите значок чата в правом нижнем углу и напишите команде интеграторов в любом мессенджере. Вы сможете получить ответ и решить проблему в режиме живого общения.
• Напишите на integration@xsolla.com.
• Свяжитесь с персональному менеджеру проекта или напишите на csm@xsolla.com.
• Свяжитесь со специалистом по интеграции в Basecamp.

Руководство по интеграции службы поддержки клиентов (PDF)

Узнайте о вариантах интеграции с нашей службой поддержки клиентов.