Прием платежей в SmartApp Code

Если смартап создан в SmartApp Code, вы можете подключить платежи в несколько этапов:

  1. Формирование корзины.
  2. Удаление позиции из корзины.
  3. Проведение платежа.
  4. Регистрация платежа.
  5. Получение статуса платежа.
Для смартапов, созданных в SmartApp Code, доступно подключение только одностадийных платежей.

Перед подключением

Получение токена

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

  • Тип токена: Bearer
  • Имя заголовка: Authorization

Подробнее о получении токена читайте в разделе Проект SmartPay. Токен необходимо добавить в файл конфигурации chatbot.yaml.

injector:
    pay_api_key: '***********'
Мы рекомендуем исключить данный вариант использования токена, если у вас есть возможность использовать для запросов собственный бэкенд. Указание токена в файлах проекта несет риск его компрометации.

Подключение библиотек

Для вызова функций предварительно подключите в файле chatbot.yaml следующие библиотеки:

scriptsPreLoad:
    global:
        - /jslib/moment.min.js

        - /jslib/underscore.js

        - /jsapi/common.js

        - /jsapi/http.js

    local:
        - /jsapi/mail.js

        - /jsapi/reactions.js

        - /jsapi/payment.js

Подключение платежей

Формирование корзины

Первым шагом необходимо сформировать корзину, то есть список товаров на оплату. Для формирования корзины из одной товарной позиции используйте встроенную функцию $payment.addItem и передайте следующий набор параметров:

Параметр Обязательный Описание
name Да Наименование или описание товарной позиции
item_price Да Цена единицы товарной позиции. Указывается без разделителя, в копейках
item_amount Да Общая цена всех единиц товарной позиции. Указывается без разделителя, в копейках
currency Да Код валюты в формате ISO 4217.

Пример: RUB
quantity Да Блок, содержащий информацию о количестве и мере измерения единиц данной товарной позиции
    value Да Количество товаров в позиции.
Для разделителя используйте "."
    measure Да Единицы измерения товаров, указанных в поле value
item_code Да Номер (идентификатор) товарной позиции в системе магазина. Параметр должен быть уникальным в рамках запроса


tax_type
Да Значение ставки НДС:

0: без НДС
1: НДС по ставке 0%
2: НДС по ставке 10%
3: НДС по ставке 18%
4: НДС по ставке 10/110
5: НДС по ставке 18/118
6: НДС по ставке 20%
7: НДС по ставке 20/120

Значение "НДС по ставке 0%" отличается от варианта "без НДС" только формированием чека в зависимости от системы налогооблажения. По сумме налога разницы нет
tax_sum Нет Сумма налога, посчитанная продавцом. Указывается без разделителя, в копейках
discount_type Нет Тип скидки на товарную позицию.

Пример: percent
discount_value Нет Значение скидки на товарную позицию
interest_type Нет Тип агентской комиссии за продажу товара (применимо только для агентской схемы).

Пример: agentPercent
interest_value Нет Значение агентской комиссии за продажу товара (применимо только для агентской схемы)
invoice_params Нет Дополнительные параметры, уточняющие товарную позицию
    key Да, если передан блок Название передаваемого параметра
    value Да, если передан блок Значение передаваемого параметра

Пример вызова функции:

script:
   $payment.addItem({
      "name": "100 кристаллов для использования при нырянии",
      "item_price": 11836,
      "item_amount": 11836,
      "currency": "RUB",
      "item_code": "com.MashaAndTheBear.HairSalon.crystal100",
      "quantity": {
            "value": 1.05,
            "measure": "кг."
      },
      "invoice_params": {
             "key": "packageName",
             "value": "com.MashaAndTheBear.HairSalon"
      }
      "discount_type": "percent",
      "discount_value": 5.25,
      "interest_type": "agentPercent",
      "interest_value": 15.105,
      "tax_type": 6,
      "tax_sum": 2367,
  })

Очистка корзины

Для очистки корзины используйте встроенную функцию $payment.clearItems. Пример вызова функции:

script: $payment.clearItems();

Регистрация платежа

После того, как все товары для покупки были загружены в корзину, необходимо зарегистрировать оплату — получить invoice_id. Для этого используйте встроенную функцию $payment.createPayment, которая отправляет запрос POST /invoices.

Параметр Обязательный Описание
purchaser
Нет Блок информации о покупателе
    email Да, если не передан phone Email покупателя.

При передаче нескольких значений используется разделитель ","
    phone Да, если не передан email Телефон покупателя
    contact Нет Способ связи с покупателем
delivery_info Нет Блок информации о параметрах доставки
    address Да, если передается блок Блок с информацией об адресе покупателя
        country Да, если передается блок Страна покупателя
        city Да, если передается блок Город покупателя
        address Да, если передается блок Адрес покупателя (улица, дом, квартира и т. д.)
    delivery_type Да, если передается блок Тип доставки
    description Нет Дополнительное описание для доставки
order Да Блок с информацией по заказу
    order_id Да Идентификатор заказа для сервиса платежей.

Должен быть уникален в рамках выделенного для приложения service_id. Если передать неуникальный параметр, новый invoice_id не будет создан
    order_number Нет Номер заказа для отображения покупателю и отслеживания статуса заказа. Должен быть понятным и простым для восприятия
    service_id Да Идентификатор сервиса, полученный при выдаче токена для авторизации запроса
    amount Да Сумма заказа. Указывается без разделителя в копейках.

Сумма должна совпадать с суммой всех позиций, добавленных с помощью $payment.addItem
    currency Да Код валюты в формате ISO-4217

Пример: RUB
    description Да Описание платежа для отображения плательщику
    purpose Да Наименование вашего юридического лица
    language Да Язык, на котором передаются все текстовые поля в запросе.

Пример: ru-RU
    expiration_date Нет Дата истечения срока оплаты. По умолчанию на оплату отводится 20 минут от момента регистрации платежа.

Пример: 2020-04-29T08:17:03+03
    autocompletion_date Нет Дата и время автоматического завершения платежа. Передается только для двухстадийного платежа.

Пример: 2020-04-29T08:17:03+03
    tax_system Да Система налогообложения:

0 – общая
1 – упрощенная, доход
2 – упрощенная, доход минус расход
3 – единый налог на вмененный доход
4 – единый сельскохозяйственный налог
5 – патентная система налогообложения

При успешном выполнении запроса вы получите invoice_id — уникальный номер зарегистрированного заказа. Сохраните этот номер в сценарии, как показано в примере ниже:

script: var response = $payment.createPayment({
    purchaser: {
        email: 'qq@dd.eof',
        phone: 9123456789,
        contact: 'email',
    },
    delivery_info: {
        address: {
            country: 'RU',
            city: 'Москва',
            address: 'ул. Вавилова, 19, офис 1',
        },
        delivery_type: 'courier',
        description: 'Перезвонить за 1,5 часа',
    },
    order: {
        order_id: 'd290f1ee-6c54-4b01-90e6-d701748f0851',
        order_number: 145,
        service_id: '9',
        amount: 11836,
        currency: 'RUB',
        purpose: 'Покупка в игре "Маша и Медведь, салон красоты Чародейка".',
        description: 'Покупка внутриигрового контента в игре Маша и Медведь, салон красоты Чародейка.',
        language: 'ru-RU',
        expiration_date: '2020-07-31T07:32:56.288Z',
        autocompletion_date: '2020-07-31T07:32:56.288Z',
        tax_system: 0,
    },
});
$session.invoice_id = response.invoice_id; // Сохраняем invoice_id

Проведение платежа

Полученный invoice_id необходимо передать ассистенту с помощью функции $reactions.pay. Функция принимает на вход invoice_id и передает его ассистенту в сообщении POLICY_RUN_APP.

script:
   $reactions.pay($session.invoice_id)

По завершении оплаты возвращается событие PAY_DIALOG_FINISHED, и сценарий запускает проверку статуса оплаты.

state: PayStatus
        event!: PAY_DIALOG_FINISHED
        script:
            $reactions.answer($request.data.eventData[0].response_code)

События eventData содержат информацию о коде ответа response_code и номере счета invoice_id.

Получение статуса

Для получения статуса платежа используется встроенная функция $payment.checkPayment, которая вызывает метод GET ​/invoices​/{invoice_id}. Входным параметром для функции $payment.checkPayment является invoice_id.

Сохраните ответ с результатом статуса оплаты в отдельную переменную:

script: var response = $payment.checkPayment($session.invoice_id);
$session.invoice_status = response.invoice_status;
$reactions.answer($session.invoice_status);

В приведенном примере переменная response содержит весь ответ на запрос GET ​/invoices​/{invoice_id} со статусом платежа invoice_status и ошибкой error.


Параметры ответа

Параметр Описание
Code Код ответа
Error Блок с описанием ошибки или ответа
    user_message Описание кода ошибки или ответа
    error_description Техническое описание кода ошибки или ответа
    error_code Код ответа
invoice_id Идентификатор счета, по которому был направлен запрос
invoice_date Дата и время создания счета
invoice_statusТекущий статус счета. Возможные значения смотрите в разделе Статусы платежа
invoice Блок с информацией по заказу. Передается только при коде ответа 200
payment_info Блок с информацией о платеже
    payment_id Идентификатор проведенной оплаты
    card_id Токен карты, с которой была проведена оплата. Параметр возвращается, если использовалась сохраненная карта
    name Имя владельца карты, с которой была проведена оплата. Параметр возвращается, если использовалась сохраненная карта
    masked_pan Маскированный номер карты, с которой была проведена оплата
    expiry_date Срок действия карты, с которой была проведена оплата
    cardholder Имя владельца карты, с которой была проведена оплата
    payment_system Платежная система, в которой зарегистрирована карта
    payment_system_image. Ссылка на логотип платежной системы
    image Ссылка на логотип карты в интерфейсе платежного устройства
    paysys Название платежного сервиса, через который был проведен платеж
    paysys_image Ссылка на логотип платежного сервиса
    bank_info Блок информации о банке плательщика
        bank_name Название банка, выпустившего карту
        bank_country_code Код страны банка, выпустившего карту
        bank_country_name Название страны банка, выпустившего карту
        bank_image Ссылка на логотип банка, выпустившего карту

Просмотр товаров в счете

Функция $payment.getItems() возвращает список товаров, добавленных в счет.

script:
   $reactions.answer(JSON.stringify($payment.getItems()));

Просмотр купленных товаров

Функция $payment.getUserItems вызывает метод GET /items и возвращает информацию по всем товарам, которые пользователь купил внутри смартапа. Информация возвращается в виде списка.

Пользователь идентифицируется автоматически на основе значения поля $request.rawRequest.uuid.sub.

В качестве аргументов функция принимает pay_api_key и объект с настройками ответа: постраничной выгрузкой и сортировкой.

Пример вызова функции:

script:
      var response = $payment.getUserItems($pay_api_key, {
          page: '1',
          size: '2',
          sort: 'ASC',
          sortField: 'item_code'
      });
      $response.message = response.message;
      $response.success = response.success;
      $reactions.answer(JSON.stringify(response));
 
      // Вызов функции без параметров.
      // В этом случае токен pay_api_key надо добавить в раздел injector
      // конфигурационного файла chatbot.yaml
      var response = $payment.getUserItems()
      $reactions.answer(JSON.stringify(response));

Подробное описание ответа и параметров запроса смотрите в разделе SmartStore.

Просмотр купленного товара

Функция $payment.getUserItem вызывает метод GET /items/{code} и возвращает информацию о конкретном товаре, который пользователь купил внутри смартапа.

Пользователь идентифицируется автоматически на основе значения поля $request.rawRequest.uuid.sub.

В качестве аргументов функция принимает pay_api_key и код товара.

Пример вызова функции:

script:
      var response = $payment.getUserItem("com.MashaAndTheBear.HairSalon.crystal100", $pay_api_key);
      $session.quantitiesItem= response.quantities.quantity_value // Сохраняем количество купленных товаров по коду
      $reactions.answer(JSON.stringify(response));
 
      // Вызов функции без параметров.
      // В этом случае токен pay_api_key надо добавить в раздел injector
      // конфигурационного файла chatbot.yaml
      var response = $payment.getUserItem()

Подробное описание ответа и параметров запроса смотрите в разделе SmartStore.

Коды ответа

Код ответа Описание
200 Запрос обработан успешно
400 Один из параметров в запросе передан в некорректном формате, либо формат запроса некорректный
401 Использован недействительный или неверный API Key (токен)
403
Внутренняя ошибка работы сервиса. Обратитесь в поддержку для устранения неполадки

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней