Быстрый старт

Платёжный API — это API для работы с платёжной системой в играх и мини-приложениях. Он нужен, чтобы продавать в приложении виртуальные товары или услуги.

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

В этом руководстве мы расскажем, как подключить платёжную систему в вашем приложении ВКонтакте.

Платежи ВКонтакте

Для платежей за товары и услуги используйте VK Pay.

Подойдёт для платежей в чат-ботах, сообществах ВКонтакте, сервисах VK Mini Apps и на сторонних сайтах. Оплата происходит с баланса VK Pay или привязанных к нему банковских карт.

Для платежей в играх и мини-приложениях используйте голоса.

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

Пользователь оплачивает покупки в игре или мини-приложении внутренней валютой ВКонтакте (голосами) следующим образом:

1.
Пользователь выбирает виртуальный товар в приложении.
2.
С его личного баланса списывается число голосов, равное стоимости покупки.
3.
Счёт приложения пополняется на стоимость покупки.

Подготовка серверной части

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

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

Откройте страницу редактирования вашего приложения и перейдите на вкладку Платежи. Здесь нужно указать адрес обратного вызова (URL на вашем сервере, где размещён скрипт обработки уведомлений). Чтобы проводить оплату в тестовом режиме, в поле Тестировщики платежей выберите пользователей, которые будут тестировать платёжную систему.

Пока приложение не прошло модерацию, в нём доступны только тестовые платежи.

Вызов диалогового окна

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

Чтобы показать диалоговое окно, используйте метод showOrderBox или showSubscriptionBox из Client API.

Типовой JS-код для открытия окна:

JavaScript

function order() {
    const params = {
        type: 'item',
        item: 'item_25new'
    };

   VK.callMethod('showOrderBox', params);
}

После успешной оплаты товара приложению будет отправлено событие onOrderSuccess с идентификатором заказа.

Внимание! Это событие нельзя использовать для принятия решения о предоставлении пользователю виртуального товара. Проверяйте специальное уведомление order_status_change, которое отправляется на ваш сервер.

Диалоговое окно платежа

Этот диалог показывается пользователю после выбора виртуального товара на странице приложения.

Параметры `showOrderBox`

Чтобы показать диалоговое окно платежа, используйте метод showOrderBox из Client API. Он принимает следующие параметры:

`type`

string

Тип заказа. Возможные значения: votes — окно для ввода голосов на счёт приложения; offers — окно со списком специальных предложений (офферов), которые могут быть использованы пользователем для получения голосов; item — покупка товара.

`votes`

integer

Количество голосов для ввода на счёт приложения (для type = votes).

`offer_id`

integer

Идентификатор рекламной акции (для type = offers).

`currency`

integer, [0,1]

1 — стоимость специальных предложений будет отображена в валюте приложения (для type = offers).

`item`

string

Наименование товара, которое будет отправлено в уведомлении get_item (для type = item). Строка длиной до 64 символов. Например, item_25new.

События

После завершения оплаты в зависимости от результата в обработчик отправляется одно из трёх событий:

Название	Параметры	Описание
`onOrderCancel`	—	Пользователь отменил покупку.
`onOrderSuccess`	`orderId` (`integer`)	Покупка закончилась успешно.
`orderId` — идентификатор заказа. Подробную информацию об обработке платежных уведомлений вы можете найти на этой странице.
`onOrderFail`	`errorCode` (`integer`)	Покупка закончилась неуспешно.
`errorCode` — код ошибки. Подробную информацию об ошибках платежных уведомлений вы можете найти на этой странице.

Пример кода на JavaScript

JavaScript

<script type="text/javascript">

// Функция order() отображает окно для покупки товара с наименованием "item_25new". 
// Названия платёжных событий пишутся в контейнер с id="callbacks".

  function order() {
    var params = {
      type: 'item',
      item: 'item_25new'
    };
    VK.callMethod('showOrderBox', params);
  }

  var callbacksResults = document.getElementById('callbacks');

  VK.addCallback('onOrderSuccess', function(order_id) {
    callbacksResults.innerHTML += '<br />onOrderSuccess '+order_id;
  });
  VK.addCallback('onOrderFail', function() {
    callbacksResults.innerHTML += '<br />onOrderFail';
  });
  VK.addCallback('onOrderCancel', function() {
    callbacksResults.innerHTML += '<br />onOrderCancel';
  });
</script>

Диалоговое окно подписки

Параметры `showSubscriptionBox`

Чтобы показать диалоговое окно подписки, нужно вызвать метод showSubscriptionBox из Client API. Вторым аргументом передайте action — действие, которое необходимо совершить. Возможные значения:

•
create — приобрести подписку;
•
resume — возобновить подписку;
•
cancel — отменить подписку.

Метод showSubscriptionBox принимает следующие параметры:

`item`

string

Наименование подписки, которое будет отправлено в уведомлении get_subscription. Строка длиной до 64 символов. Например: subscription_25new (для action = create).

`subscription_id`

integer

Идентификатор подписки (для action = resume, cancel).

События

После завершения оплаты в зависимости от результата в обработчик отправляется одно из трёх событий:

Название	Параметры	Описание
`onSubscriptionCancel`	—	Пользователь отменил покупку.
`onSubscriptionSuccess`	`subscription_id` (`integer`)	Покупка закончилась успешно.
`subscription_id` — идентификатор подписки. Подробную информацию об обработке платежных уведомлений вы можете найти на этой странице.
`onSubscriptionFail`	`errorCode` (`integer`)	Покупка закончилась неуспешно.
`errorCode` — код ошибки. Подробную информацию об ошибках платежных уведомлений вы можете найти на этой странице.

Обратите внимание — в тестовом режиме подписка 5 раз автоматически продлевается раз в 10 минут (для period = month) и раз в 2 минуты для других значений period. После этого подписка автоматически отменяется.

Пример кода на JavaScript

JavaScript

<script type="text/javascript">
  function order() {
    VK.callMethod('showSubscriptionBox', 'create', {item: 'subscription1'});
  }

  var callbacksResults = document.getElementById('callbacks');

  VK.addCallback('onSubscriptionSuccess', function(subscription_id) {
    callbacksResults.innerHTML += '<br />onSubscriptionSuccess '+subscription_id;
  });
  VK.addCallback('onSubscriptionFail', function() {
    callbacksResults.innerHTML += '<br />onSubscriptionFail';
  });
  VK.addCallback('onSubscriptionCancel', function() {
    callbacksResults.innerHTML += '<br />onSubscriptionCancel';
  });
</script>

Функция order позволяет отобразить пользователю окно для покупки товара с наименованием 'subscription_25new'. Названия произошедших платёжных событий пишутся в контейнер с id="callbacks".

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

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

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

Для осуществления платежей в тестовом режиме необходимо добавить всех пользователей, совершающих тестовые платежи, в специальный список в настройках приложения (поле Тестировщики платежей).

В тестовом режиме к параметру notification_type добавляется суффикс '_test'. Таким образом, уведомления будут называться 'get_item_test', 'order_status_change_test', 'get_subscription_test', 'subscription_status_change ' соответственно (см. Платёжные уведомления).

При этом идентификаторы заказов в тестовом режиме – параметры order_id у уведомлений – могут пересекаться с идентификаторами заказов в рабочем режиме.

Обратите внимание — в тестовом режиме подписка 5 раз автоматически продлевается раз в 10 минут (для period = month) и раз в 2 минуты для других значений period. После этого подписка автоматически отменяется. Уведомления приходят только при изменении статуса подписки, в случае продления уведомления не приходят. Подробнее см. Изменение статуса подписки.

Модерация приложения

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

Чтобы приложение успешно прошло модерацию, убедитесь, что оно соответствует Правилам.

Методы `orders`

Метод API orders.get позволяет получить список заказов с их текущими статусами. Чтобы отменить заказ, используйте метод orders.changeState, передав идентификатор заказа и новый статус заказа refund. Голоса вернутся на баланс пользователя. На балансе приложения должно быть достаточно голосов для возврата. Весь список методов секции orders можно посмотреть здесь.

Быстрый старт

Платежи ВКонтакте

Подготовка серверной части

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

Вызов диалогового окна

Диалоговое окно платежа

Параметры showOrderBox

type

votes

offer_id

currency

item

События

Пример кода на JavaScript

Диалоговое окно подписки

Параметры showSubscriptionBox

item

subscription_id

События

Пример кода на JavaScript

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

Модерация приложения

Методы orders

Параметры `showOrderBox`

`type`

`votes`

`offer_id`

`currency`

`item`

Параметры `showSubscriptionBox`

`item`

`subscription_id`

Методы `orders`