Отслеживание статуса заказа
Отслеживание статуса заказа требуется, чтобы убедиться, что оплата прошла успешно, и начислить товары пользователю.
Выберите способ отслеживания статуса заказа:
Выберите наиболее подходящий для вашего проекта способ обращения к данным Xsolla:
Если у вас нет своего сервера или вы используете логику обработки покупок на стороне клиента, вы можете использовать следующие способы:
Получение статуса заказа на стороне клиента с помощью веб-сокет-соединения
Решение предусматривает использование веб-сокетов для получения статусов заказа без получения подробной информации о самом заказе. Этот способ является предпочтительным: между клиентом (например, вашим сайтом или мобильным приложением) и сервером Xsolla устанавливается только одно подключение, поэтому нет дополнительной нагрузки ни на клиент, ни на сервер.
Выполните следующие действия:
- Для того чтобы веб-сокет-сервер Xsolla и ваш клиент могли идентифицировать сообщения со статусом заказа, создайте соединение:
- javascript
const client = new Centrifuge(
connectionURL,
{
data: {
user_external_id: user_external_id,
auth: auth,
project_id: project_id
}
}
)
connectionURL - wss://ws-store.xsolla.com/connection/websocket
auth - user JWT token
- Чтобы получать новые сообщения о статусах заказов, подпишитесь на события с помощью функции
client.on
:
- javascript
client.on('publication', (ctx) => {
//handle the status
});
- Установите соединение:
- javascript
client.connect()
- Чтобы получать историю изменений статусов заказов, подключите метод API history method.
- javascript
client.on('subscribed', function (ctx) {
client.history(ctx.channel, { limit: -1, since: { offset: 0 }, reverse: false }).then(function (resp) {
resp.publications.forEach((ctx) => {
/handle the status
});
}, function (err) {
//handle the status
});
});
Пример тела сообщения:
- javascript
{
order_id: 59614241,
status: 'new'
}
Возможны следующие статусы заказа:
New
— заказ создан и еще не оплачен.Paid
— заказ оплачен.Done
— заказ полностью доставлен (в том числе отправлены все чеки, выполнены доставки на стороне Xsolla, внешних платформ и т.д.).Canceled
— заказ отменен, оплата возвращена пользователю.
Рекомендуемое ожидание ответа через веб-сокет — 5 минут. После этого (или если с веб-сокетом есть какие-либо проблемы), рекомендуется использовать простые запросы.
Простые запросы (short-polling)
Чтобы получить детальную информацию о товарах в заказе после перехода в нужный статус, используйте API-метод Get order.
Метод XsollaCatalog.Purchase
инкапсулирует в себе несколько методов отслеживания статуса заказа. Механизм отслеживания подробно описан в документации SDK для Unity.
Дополнительно вы можете реализовать обработку статуса и содержимого заказа, которые передаются в функцию обратного вызова onSuccess
метода покупки.
C помощью SDK вы можете отслеживать статус заказа следующими способами:
Подписка на изменение статуса заказа
Чтобы подписаться на изменения статуса заказа, используйте метод SDK getOrderStatus
из библиотеки Store. Передайте в метод следующие параметры:
listener
— объект слушателя типаOrderStatusListener
;orderId
— ID заказа, полученный в результате покупки через корзину, покупки в один клик или покупки за виртуальную валюту.
Пример вызова метода XStore.getOrderStatus:
- kotlin
XStore.getOrderStatus(object : OrderStatusListener() {
override fun onStatusUpdate(status: OrderResponse.Status) {
if(status == OrderResponse.Status.DONE) {
Log.d("MainActivity", "Success")
}
}
override fun onFailure() {
Log.d("MainActivity", "Failure")
}
}, orderId)
Мы рекомендуем вызывать метод XStore.getOrderStatus
вместе с открытием платежного интерфейса.
Этот метод инкапсулирует в себя несколько методов отслеживания статуса заказа. Отслеживание выполняется по следующему алгоритму:
- Устанавливается веб-сокет-соединение.
- Если соединение установлено и статус заказа изменен на
done
илиcancel
, отслеживание прекращается. Если не удалось установить веб-сокет-соединение либо в ответе приходят некорректные данные, статус заказа отслеживается с помощью short-polling. - Отслеживание статуса заказа продолжается с помощью short-polling. Раз в 3 секунды отправляется простой HTTP-запрос статуса заказа. Отслеживание прекращается, когда статус заказа изменится на
done
илиcancel
.
Запрос статуса заказа
Для запроса текущего статуса платежной транзакции вызовите метод getOrder
из библиотеки Store, передав в него следующие параметры:
orderId
— ID заказа, который был получен при покупке товара.callback
— обработчик, вызываемый после успешного получения информации о заказе. При создании обработчика используйте интерфейсGetStatusCallback
и реализуйте методыonSuccess
иonError
.callback
— обработчик, вызываемый после успешного получения информации о заказе. При создании обработчика используйте интерфейсGetStatusCallback
и реализуйте методыonSuccess
иonError
.
Данные о статусе заказа передаются в метод onSuccess
в объекте с типом InvoicesDataResponse
. Этот объект содержит массив объектов InvoiceData
. Каждый объект InvoiceData
соответствует определенному этапу в обработке заказа и содержит статус этого этапа.
Например, если пользователь сначала ввел некорректные данные при оформлении заказа, в списке InvoiceData
появится объект со статусом InvoicesDataResponse.CANCELED
. Если затем пользователь исправит данные и успешно оплатит заказ, в массиве появится новый объект InvoiceData
уже со статусом InvoicesDataResponse.Status.DONE
.
Отслеживание статуса прекращается, если получен финальный статус платежа (InvoicesDataResponse.Status.DONE
или InvoicesDataResponse.Status.ERROR
).
Пример:
- kotlin
XPayments.getStatus(<token>, <isSandbox>, object : GetStatusCallback {
override fun onSuccess(data: InvoicesDataResponse?) {
Log.d(TAG, "onSuccess is fired. Result data = $data")
}
override fun onError(throwable: Throwable?, errorMessage: String?) {
Log.d(TAG, "onError is fired. ErrorMessage = $errorMessage")
}
})
Для запроса статуса и содержимого заказа вызовите метод SDK CheckPendingOrder
, передав в него следующие параметры:
AccessToken
— платежный токен, который был получен при покупке товара.OrderId
— ID заказа, который был получен при покупке товара.SuccessCallback
— обработчик, вызываемый после успешной проверки заказа. В ответе будет получен статус заказа.ErrorCallback
— обработчик, вызываемый в случае ошибки при выполнении запроса.bIsUserInvolvedToPayment
— участвует ли пользователь в процессе оплаты. Передайте значениеtrue
для покупки за реальную валюту, ffalse
— для бесплатной покупки товара и покупки за виртуальную валюту.
Механизм отслеживания подробно описан в документации SDK для Unreal Engine.
Для запроса статуса и содержимого заказа вызовите метод SDK CheckOrder
, передав в него следующие параметры:
AccessToken
— платежный токен, который был получен при покупке товара.OrderId
— ID заказа, который был получен при покупке товара.SuccessCallback
— обработчик, вызываемый после успешной проверки заказа. В ответе будет получен статус заказа.ErrorCallback
— обработчик, вызываемый в случае ошибки при выполнении запроса.
Для отслеживания статусов создаваемых заказов и их валидации вам потребуется настроить обработку вебхуков на серверной части вашего приложения.
Для полноценной работы внутриигрового магазина необходимо реализовать обработку основных вебхуков:
Вебхук | Тип оповещения | Описание |
---|---|---|
Проверка существования пользователя | user_validation | Отправляется на разных этапах оплаты, чтобы удостовериться, что пользователь зарегистрирован в игре. |
Успешный платеж | payment | Отправляется, когда заказ оплачен, и содержит информацию о данных платежа и детали транзакции. |
Успешная оплата заказа | order_paid | Отправляется, когда был получен ответ об успешной обработке вебхука Успешный платеж. Содержит информацию о купленных товарах и ID транзакции. Используйте данные вебхука для начисления товаров пользователю. |
Возврат платежа | refund | Отправляется, когда заказ был отменен, и содержит информацию о данных отмененного платежа и детали транзакции. |
Отмена заказа | order_canceled | Отправляется, когда был получен ответ об успешной обработке вебхука Возврат платежа. Содержит информацию о купленных товарах и ID отмененной транзакции. Используйте данные вебхука для списания купленных товаров у пользователя. |
Полный список вебхуков и общая информация о работе с ними приведены в документации по вебхукам.
Настройка отправки вебхуков
Чтобы настроить вебхуки на стороне Xsolla:
- Откройте проект в Личном кабинете.
- Нажмите Настройки проекта в боковом меню и перейдите в раздел Вебхуки.
- В поле URL вебхука укажите URL-адрес, на который Xsolla будет отправлять вебхуки.
- Нажмите Получать вебхуки.
![](https://cdn.xsolla.net/developers/v-20240906-v01/images/sdk/android/baas-integrations/webhooks-settings.png)
Реализация обработчика вебхуков
Обработчик вебхуков — это программный код, который позволяет принимать поступающие вебхуки на указанный 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
, повторная отправка вебхука Проверка существования пользователя не осуществляется.
Пользователь увидит ошибку, вебхуки Успешный платеж и Успешная оплата заказа отправлены не будут.
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.