Обработка платёжных уведомлений в Одноклассниках

Когда пользователь покупает виртуальные ценности в игре или мини-приложении за ОКи, площадка отправляет уведомления серверу приложения. В отличие от ВКонтакте, площадка Одноклассники отправляет два типа уведомлений:

•

POST-запрос для получения информации о виртуальном товаре. Это такой же запрос как и ВКонтакте типа get_item. Одноклассники отправляет это уведомление на адрес, указанный в настройке URL для платёжных уведомлений ВКонтакте.

Пример запроса:
app_id=1524456&item=sale_item_1&lang=ru_RU&notification_type=get_item_test&order_id=2044594&receiver_id=1&user_id=1&version=5.132&site=VK&sig=a71ec5b6c78940fa47a83796ee983ab6

В параметре site передаётся название площадки, на которой производится покупка. Учитывайте это значение при расчёте стоимости товара в голосах или ОКах.
•

GET-запрос для получения информации об оплате, отмене и возврате товара, а также для всех операций с подписками. Уведомление приходит на URL для платёжных уведомлений Одноклассников.

Параметры GET-запроса

Параметры уведомления в виде query-параметров, содержащих пары параметр=значение, разделённые символом &:

https://callback.url/
?transaction_id=transactionId
&sig=270c83248ac45232be85bbbe3be7613b
&uid=123456789012
&amount=10
&method=callbacks.payment
&transaction_time=2017-11-08+00:21:10
&product_code=productCode
&extra_attributes={“subscriptionEndDate”:”20-11-2018 13:07:04”,”action”:”reg_subscription”}
&application_key=CBAKMLELABABABABE
&call_id=1510089670220

Тип уведомления определяется параметром extra_attributes:

•
Если значение параметра пустое, то это уведомление о покупке товара.
•
Если в action передаётся значение reg_subscription, trial_subscription или unsubscribe, то это уведомление об оплате подписки, начале триальной подписки или запрос об отмене подписки соответственно.

Название	Тип	Описание
`uid` обязательный	`string`	Идентификатор пользователя.
`transaction_id` обязательный	`string`	Уникальный идентификатор транзакции. Для некоторых действий (начало триального периода игровой подписки, отказ от подписки) параметр может отсутствовать.
`transaction_time` обязательный	`date`	Время транзакции в формате yyyy-mm-dd HH:MM
`amount` обязательный	`integer`	Сумма покупки в ОКах.
`product_code` необязательный	`string`	Код продукта. Для подписки — `productId` в информации о подписке.
`extra_attributes` необязательный	`string`	JSON-кодированные пары ключей/значений, содержащие дополнительные параметры транзакции.
`trial_days` необязательный	`long`	Пробный период в днях купленной игровой подписки

Подробнее об общих параметрах запроса — в документации API Одноклассники.

Обработка уведомлений

•
Для сервера игры или мини-приложения уведомления — это входящие запросы. Сервер должен обработать уведомление, например предоставить пользователю купленный товар или преимущества подписки и вернуть результат об успешной обработке или ошибке.
•
Обратная связь вызывается 3 раза до получения успешного ответа HTTP. Каждая попытка имеет задержку 5 секунд. Если сервер не отвечает, транзакция будет отменена, а виртуальные деньги возвращены пользователю.
•
Разработчик обязан проверять соответствие товара и его цены, передаваемых в параметрах product_code и amount. В противном случае злоумышленник сможет совершать любые покупки в игре за минимальную стоимость.
•
Разработчик должен проверять значение подписи sig из запроса.
•
Сервер обязательно должен ответить на уведомление. Одноклассники переводит ОКи со счёта пользователя на счёт приложения только после получения ответа от сервера.

Формат ответа

•
Поддерживаются ответы в форматах XML и JSON.
•
Тип содержимого должен быть "application/xml" или "application/json".
•
В случае ошибки HTTP-заголовок "Invocation-error" должен содержать код ошибки.

В случае успешного выполнения надо вернуть true.

JSON

{
  true
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<callbacks_payment_response xmlns="http://api.forticom.com/1.0/">
    true
</callbacks_payment_response>

Формат ответа при ошибке

Структура данных

Если при обработке уведомления произошла ошибка, необходимо отправить ответ в следующем формате:

JSON

{
    "error_code": 1001,
    "error_msg": "CALLBACK_INVALID_PAYMENT : Payment is invalid and can not be processed",
    "error_data": null
}

Поле	Тип	Описание
`error_code`	`integer`	Код ошибки.
`error_msg`	`string`	Описание ошибки в текстовом виде.
`error_data`	`string`	Дополнительная информация об ошибке.

Подробнее о кодах ошибок — в документации API Одноклассники.

Проверка подписи параметров

Разработчик должен проверять значение подписи sig из запроса. Подробнее о подписи запроса — в документации API Одноклассники.

Работа со строковыми данными

Строковые данные в уведомлениях закодированы в URL-кодировке, принятой в PHP. Например, пробелы будут представлены как +, символы национальных алфавитов и специальные символы — в записи через %, например, %2F.

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

Поддержка многоязычных интерфейсов

Обработчик уведомления get_item возвращает информацию о покупаемом товаре или подписке.

В зависимости от языка пользователя (русский, английский и другие), эти обработчики могут возвращать различные данные для одного и того же товара или подписки.

Язык пользователя указан в параметре lang. Обработчики событий могут проверять значение этого параметра и возвращать название товара на языке пользователя. Это даёт возможность платёжным окнам выглядеть ожидаемо для клиентов в приложениях, поддерживающих многоязычные интерфейсы.

Кеширование информации о товарах и подписках

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

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

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

Мы рекомендуем использовать кеширование, насколько это возможно в вашем приложении. Это ускоряет обработку платёжных запросов и уменьшает нагрузку на сервер вашего приложения.

Данные для разных языков пользователя кешируются отдельно.