Продажа виртуальных товаров ВКонтакте

При продаже виртуальных товаров ВКонтакте отсылает уведомления серверу приложения для получения информации о продаваемом товаре и для подтверждения покупки. Уведомления — это POST-запросы, которые отправляются на адрес обратного вызова, указанный в настройках вашего приложения. Структура запросов-уведомлений рассмотрена в разделе Обработка платёжных уведомлений.

Как реализовать продажу виртуальных товаров

Шаг 1. Подготовьте серверную часть приложения

  1. 1.

    На сервере приложения определите URL, на который будут приходить запросы, связанные с покупками. Это может быть адрес https://{ваш-сервер}/purchase или любой другой.

  2. 2.

    В код сервера добавьте обработчик POST-запросов, которые будут приходить на этот URL. Для работы с платежами за товары надо реализовать обработку следующих уведомлений:

    Уведомления
    Описание
    get_item
    ВКонтакте отсылает это уведомление, чтобы получить информацию о товаре для отображения в окне покупки: название, стоимость, изображение.
    order_status_change
    Это уведомление используется при покупке и возврате товара.

    Подробности создания обработчиков — в разделе Обработка платёжных уведомлений.

Шаг 2. Укажите адрес обратного вызова в настройках приложения

  1. 1.

    Перейдите в настройки приложения. Для этого в списке приложений найдите ваше мини-приложение или игру и нажмите Настройки.

  2. 2.

    Выберите раздел Платежи в меню слева.

    • •

      В поле URL для платёжных уведомлений ВКонтакте укажите URL, на который площадка будет отсылать уведомления. Вы определили его на шаге 1.

    • •

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

    • •

      Чтобы проводить оплату в тестовом режиме, в поле Тестировщики платежей укажите пользователей, которые будут тестировать платежи. Предварительно этих пользователей надо добавить в администраторы приложения и дать им права на тестирование.

      Добавление администраторов в этот список обязательно для тестирования. Без этого тестирование платежей недоступно даже администраторам с полным доступом. Подробнее о настройках для тестирования — в разделе Тестирование платежей.

Шаг 3. Вызовите событие VK Bridge для показа окна покупки

Для продажи игрового товара вызовите событие VKWebAppShowOrderBox в клиентской части игры. Например так:

JavaScript
bridge.send('VKWebAppShowOrderBox', { type: 'item', // Всегда должно быть 'item' item: 'sale_item_id_1', // Идентификатор товара }) .then( (data) => {console.log('Покупка состоялась.', data) }) .catch( (e) => {console.log('Ошибка!', e) });

Обратите внимание, что если вы не используете какой-либо сборщик, например webpack, a включаете .js-файл библиотеки VK Bridge в HTML-код своих страниц, то в JavaScript-коде надо использовать имя объекта vkBridge, а не bridge.

Проверить результаты можно не только c помощью then и catch, но и через события. Подробнее — в разделе Обработка результатов.

Порядок обработки ответов на уведомление зависит от платформы:

  • •

    В десктопной версии сайта ВКонтакте ваше приложение получает событие VKWebAppShowOrderBoxResult только после того, как платформа ВКонтакте обработала ответ на уведомление. Если сервер приложения сообщает об ошибке в ответе на платёжное уведомление, ВКонтакте отправляет событие VKWebAppShowOrderBoxFailed.

  • •

    На Android и в мобильной версии сайта ваше приложение всегда получает событие VKWebAppShowOrderBoxResult после того, как пользователь подтвердит оплату голосами. ВКонтакте ожидает ответ на уведомление, но не отправляет событие VKWebAppShowOrderBoxFailed, даже если приложение вернёт код ошибки.

Обмен данными

Обмен данными происходит в два этапа:

  1. 1.

    Чтобы показать окно покупки товара, ваше приложение должно вызвать событие VKWebAppShowOrderBox библиотеки VK Bridge.

    Получение данных о товареПолучение данных о товаре

    • •

      Библиотека отправляет запрос площадке ВКонтакте о необходимости показать диалоговое окно.

    • •

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

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

    • •

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

    • •

      Площадка проверяет, достаточно ли у пользователя голосов на счёте.

      Если голосов достаточно, платформа покажет диалоговое окно для подтверждения платежа.

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

  2. 2.

    После того как пользователь нажмёт Оплатить в окне покупки, происходит следующее:

    Обмен данными после подтверждения оплатыОбмен данными после подтверждения оплаты

    • •

      ВКонтакте отправляет серверу приложения уведомление orders_status_change. Оно сообщает, что пользователь оплатил товар.

    • •

      Сервер приложения предоставляет пользователю покупаемый товар и возвращает ВКонтакте ответ об успешной обработке заказа.

    • •

      ВКонтакте переводит голоса со счёта пользователя на счёт приложения, а также сообщает клиентской части приложения об успешной покупке.

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

Возврат товаров

Процедура возврата товара инициируется Поддержкой ВКонтакте. Пользователь и приложение не могут сделать это сами.

При возврате товара ВКонтакте отправит серверу приложения уведомление order_status_change.

Тестовый режим

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

Работа со списком заказов

Вся информация о заказах и платежах сохраняется на серверах ВКонтакте. Для работы со списком заказов вы можете использовать API-операции группы Orders.

Материалы по теме