Как подключить xsolla к сайту

Your browser is not supported. Please try a different browser

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

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

Интеграция

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

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

Как интегрировать продукты Партнерская сеть, Магазин, Авторизация и другие новые или дополнительные продукты Иксоллы?

Чтобы интегрировать продукты Иксоллы, напишите нам на integration@xsolla.com, и мы обязательно поможем.

Как добавить к способам оплаты paysafecard?

Чтобы добавить новый способ оплаты, напишите нам на integration@xsolla.com.

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

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

Почему PHP-библиотека не работает на нашем сайте?

Убедитесь, что вы установили все необходимые файлы и верно указали все относительные пути. Более подробные инструкции по установке есть в нашем GitHub-репозитории.

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

Что такое User ID? Как нам валидировать пользователей?

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

Какие данные надо возвращать после валидации? Например, что нужно вернуть, если валидация прошла успешна? И если нет?

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

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

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

Перед запуском необходимо настроить и протестировать модули. Подробную инструкцию вы найдете в руководствах по интеграции. Если возникла проблема с получением оповещений (webhooks), проверьте, правильно ли установлен webhook сервер. Если проблему решить не удалось, отправьте запрос на адрес integration@xsolla.com.

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

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

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

В чем разница между URL оповещений и URL возврата?

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

Где найти ID проекта/продавца/паблишера?

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

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

Как добавить в Личный кабинет других сотрудников компании?

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

Мы издаем игры для мобильных устройств. Что написать в поле Сайт в настройках проекта?

Укажите URL лендинга игры или вашей компании.

Настройки оповещений

Необходимо ли для оповещений использовать HTTPS?

Да — Иксолла API использует базовую HTTP-аутентификацию.

Почему ваше оповещение не пришло на URL для оповещений?

Убедитесь, что вы передаете все необходимые файлы, и что ваш вебхук-сервер поддерживает необходимые виды вебхук-запросов.

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

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

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

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

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

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

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

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

Да, в тестовом окружении вы можете использовать одну из тестовых карт.

Возможно ли протестировать платеж через PayPal в тестовом окружении, чтобы убедиться, что он корректно работает?

В данный момент тестирование платежа PayPal в тестовом окружении не реализовано.

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

Возврат платежа можно выполнить с помощью метода API или через Личный кабинет в разделе Поддержка > Поиск транзакций.

Что такое Номер заявки в Иксолле и Номер заявки на вкладке Тестирование?

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

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

Партнеры по Buycraft будут получать ответ INVALID_SIGNATURE, если в аккаунте Buycraft введены неверные ключ API, ID продавца, ID проекта или секретный ключ.

Платежи

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

Проверьте, существует ли указанный ID пользователя в вашем проекте, и отправьте код 200 для подтверждения платежа.

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

В данный момент такая проверка не реализована.

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

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

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

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

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

URL-адрес оповещений указывается в настройках Личного кабинета и определяется для всех транзакций.

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

Мы отправляем оповещение только в случае успешной покупки. Если вы получили уведомление о платеже, транзакция прошла успешно.

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

Настройки покрытия VAT выполняются на стороне Иксоллы. Если вы хотите удерживать VAT с пользователя, а не платить самостоятельно, как это настроено сейчас, обратитесь к аккаунт-менеджеру проекта для изменения настроек.

Что такое PID?

PID — идентификатор платежной системы в Иксолле.

Как я могу обновить баланс виртуальной валюты пользователя?

Вы можете использовать API метод Изменение баланса.

Внешний ID — это какой-то кастомный идентификатор нашей игры/платформы? Нужно ли создавать новый внешний ID для каждой транзакции?

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

Как установить purchase.description.value через PHP SDK?

Описание покупки используется в платежном интерфейсе и квитанциях. Вы можете установить значение в токене.

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

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

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

Какие способы выплат поддерживаются для проектов Buycraft?

Buycraft-проекты могут получать деньги через PayPal и банковский перевод.

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

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

Купоны

В чем отличие между отдельными и акционными купонами?

Отдельные купоны можно использовать, чтобы давать пользователям бесплатные предметы. Акционные купоны позволяют предоставлять пользователям скидки и бонусы при покупке.

Подписки

Что такое product_id в Подписках?

Вы можете использовать этот параметр, если у пользователя несколько платных подписок на разные продукты. Тогда product_id поможет отличать их друг от друга.

Ошибки

При открытии платежного интерфейса выдается следующая ошибка: 0004-0008. Что это значит?

PHP SDK выдает ошибку INVALID_CLIENT_IP. Что делать?

Для решения проблемы необходимо добавить обратный IP-адрес вашего прокси-сервера на webhook сервер.

Что означают ошибки 2205 и 2207 (user ID error)?

Требуется передать корректный ID пользователя. Убедитесь, что вы используете User ID из вашей базы данных.

Что означает ошибка 1000-0003?

Вам нужно включить соответствующий модуль для проекта. Если речь идет о модуле Чекаут, возможно, вы не указали параметр покупки.

Что означает ошибка 0002-0004?

Вам необходимо подписать соглашение с нами, чтобы начать получать выплаты. Свяжитесь с аккаунт-менеджером или напишите на onboarding@xsolla.com.

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

Мне кажется, я не могут получить строку токена из-за проблем с SSL. Обязательна ли SSL-проверка в вашем интерфейсе?

По умолчанию, мы включаем SSL-проверку сертификата и используем сертификаты, предоставленные операционной системой. Подробнее о решении проблем с SSL можно прочитать в документации SDK.

Источник

Your browser is not supported. Please try a different browser

Платежи

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

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

Интеграция

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

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

Как добавить к способам оплаты paysafecard?

Чтобы добавить новый способ оплаты, напишите нам на integration@xsolla.com.

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

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

Почему PHP-библиотека не работает на нашем сайте?

Убедитесь, что вы установили все необходимые файлы и верно указали все относительные пути. Более подробные инструкции по установке есть в нашем GitHub-репозитории.

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

Что такое User ID? Как нам валидировать пользователей?

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

Какие данные надо возвращать после валидации? Например, что нужно вернуть, если валидация прошла успешна? И если нет?

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

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

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

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

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

В чем разница между URL оповещений и URL возврата?

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

Где найти ID проекта/продавца/паблишера?

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

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

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

Где найти ID проекта/продавца и секретный/API-ключ для проектов Buycraft?

Что указать как Название игры в разделе Информация о соглашении в настройках Buycraft?

Укажите название вашего сервера.

Настройки оповещений

Необходимо ли для оповещений использовать HTTPS?

Да — Иксолла API использует базовую HTTP-аутентификацию.

Почему ваше оповещение не пришло на URL для оповещений?

Убедитесь, что вы передаете все необходимые файлы, и что ваш вебхук-сервер поддерживает необходимые виды вебхук-запросов.

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

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

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

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

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

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

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

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

Да, в тестовом окружении вы можете использовать одну из тестовых карт.

Возможно ли протестировать платеж через PayPal в тестовом окружении, чтобы убедиться, что он корректно работает?

В данный момент тестирование платежа PayPal в тестовом окружении не реализовано.

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

Возврат платежа можно выполнить с помощью метода API или через Личный кабинет в разделе Поддержка > Поиск транзакций.

Что такое Номер заявки в Иксолле и Номер заявки на вкладке Тестирование?

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

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

Партнеры по Buycraft будут получать ответ INVALID_SIGNATURE, если в аккаунте Buycraft введены неверные ключ API, ID продавца, ID проекта или секретный ключ.

Платежи

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

Проверьте, существует ли указанный ID пользователя в вашем проекте, и отправьте код 200 для подтверждения платежа.

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

В данный момент такая проверка не реализована.

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

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

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

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

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

URL-адрес оповещений указывается в настройках Личного кабинета и определяется для всех транзакций.

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

Мы отправляем оповещение только в случае успешной покупки. Если вы получили уведомление о платеже, транзакция прошла успешно.

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

Настройки покрытия VAT выполняются на стороне Иксоллы. Если вы хотите удерживать VAT с пользователя, а не платить самостоятельно, как это настроено сейчас, обратитесь к аккаунт-менеджеру проекта для изменения настроек.

Что такое PID?

PID — идентификатор платежной системы в Иксолле.

Как я могу обновить баланс виртуальной валюты пользователя?

Вы можете использовать API метод Изменение баланса.

Внешний ID — это какой-то кастомный идентификатор нашей игры/платформы? Нужно ли создавать новый внешний ID для каждой транзакции?

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

Как установить purchase.description.value через PHP SDK?

Описание покупки используется в платежном интерфейсе и квитанциях. Вы можете установить значение в токене.

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

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

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

Какие способы выплат поддерживаются для проектов Buycraft?

Buycraft-проекты могут получать деньги через PayPal и банковский перевод.

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

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

Ошибки

При открытии платежного интерфейса выдается следующая ошибка: 0004-0008. Что это значит?

PHP SDK выдает ошибку INVALID_CLIENT_IP. Что делать?

Для решения проблемы необходимо добавить обратный IP-адрес вашего прокси-сервера на webhook сервер.

Что означают ошибки 2205 и 2207 (user ID error)?

Требуется передать корректный ID пользователя. Убедитесь, что вы используете User ID из вашей базы данных.

Что означает ошибка 1000-0003?

Вам нужно включить соответствующий модуль для проекта. Если речь идет о модуле Чекаут, возможно, вы не указали параметр покупки.

Что означает ошибка 0002-0004?

Вам необходимо подписать соглашение с нами, чтобы начать получать выплаты. Свяжитесь с аккаунт-менеджером или напишите на onboarding@xsolla.com.

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

Мне кажется, я не могут получить строку токена из-за проблем с SSL. Обязательна ли SSL-проверка в вашем интерфейсе?

По умолчанию, мы включаем SSL-проверку сертификата и используем сертификаты, предоставленные операционной системой. Подробнее о решении проблем с SSL можно прочитать в документации SDK.

Источник

Your browser is not supported. Please try a different browser

С чего начать

Введение

API Иксоллы использует REST-архитектуру. В API мы используем HTTP коды ответов для обозначения ошибок и URL, аналогичных структуре каталогов. Ответы API (включая ошибки) возвращаются в виде JSON.

Мы используем встроенные особенности HTTP, такие как HTTP аутентификация и HTTP методы, которые понимаются всеми HTTP клиентами, также мы поддерживаем CORS (Cross-origin resource sharing) для обеспечения безопасной работы с API вашего клиентского приложения.

Запрос и ответ

Изменения API

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

Версионирование

Все разделы API Иксоллы поддерживают версионирование. Мы будем выпускать новую версию всякий раз, когда будут появляться несовместимые с текущей версией изменения. Версия обозначается идентификатором («v1″/»v2» и т. п.), который указывается в URL после префикса «/merchant».

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

Аутентификация

Команды управления ресурсами

Формат даты

Постраничная навигация

Типы ошибок

Иксолла использует стандартные HTTP коды для обозначения успешных или неуспешных запросов. В общем случае код в 2xx диапазоне обозначает успех, код диапазона 4хх означает ошибку в результате передачи некорректных параметров (например, обязательный параметр не передан, или авторизация не прошла и т. д.), код 5хх диапазона означает серверную ошибку.

Не все ошибки в точности соответствуют HTTP кодам. Например, если запрос был верным, но не смог завершиться успешно, мы вернем 422 ошибку.

В случае ошибочного ответа мы возвращаем JSON объект со следующими полями:

Оповещения

Введение

Используйте webhook-и для оповещения о событиях, которые происходят с транзакцией в Иксолле. Вы можете использовать оповещения для автоматизации бэк-офиса и функций, таких как отображение статуса.

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

Например, вы можете отменить платеж через API Иксоллы, либо платежная система может нас оповестить об оспариваемой операции.

Мы не гарантируем, что ваш обработчик получит все оповещения. Поскольку интернет-соединение не является на 100% надежным, оповещения могут теряться или задерживаться. Ваш обработчик оповещений также может возвращать код статуса HTTP 5xx при временных проблемах на вашем сервере. Например, если пользователь совершил успешную покупку виртуального предмета, но она не была добавлена в инвентарь, обработчик вернет код статуса HTTP 500.

Для решения этой проблемы сервис оповещений Иксоллы включает в себя механизм повторных оповещений. Повторные оповещения отправляются в течение 12 часов с момента первой попытки, пока ваш обработчик не подтвердит получение. Максимальное количество попыток — 12.

Подпись запроса

Подпись обеспечивает безопасность передачи данных. Генерация подписи состоит из двух шагов. Первый шаг — конкатенация JSON из тела запроса и секретного ключа проекта. Второй шаг — применение SHA-1 криптографической хэш-функции к получившейся на первом шаге строке.

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

Источник