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

Обновлено 15 декабря 2023

SmartPay

Code

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

Формирование корзины.
Создание счета.
Проведение платежа.
Получение статуса.
Просмотр товаров в счете.
Просмотр купленных товаров.
Просмотр купленного товара.

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

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

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

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

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

О том как получить токен читайте в разделе Проект SmartPay. Передавайте токен в запросах одним из двух способов.

Безопасный способ передачи токена

Сохраните токен в переменную $pay_api_key.

В этом случае при вызове функций оплаты createPayment(), checkPayment() и других, вы можете авторизовать запросы с помощью переменной $pay_api_key, переданной в аргументе функции, например:

$payment.createPayment(order, "$pay_api_key");
$payment.checkPayment($session.invoice_id, "$pay_api_key")

Переменную нужно указывать в кавычках "$pay_api_key".

Небезопасный способ передачи токена

Укажите токен в файле chatbot.yaml, в разделе injector.

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

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

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

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

Параметр	Обязательный	Описание
poisition_id	Да	Номер товарной позиции в корзине
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	Да, если передан блок	Значение передаваемого параметра

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

{
    "poisition_id": 1,
    "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
}

Создание счета

После того, как все товары для покупки были загружены в корзину, необходимо зарегистрировать оплату — получить 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	Да	Сумма заказа. Указывается без разделителя в копейках
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 – патентная система налогообложения
order_bundle	Да	Блок содержимого корзины. Описание параметров см. Формирование корзины

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

script: var response = $payment.createPayment({
    order: {
        order_id: 'd290f1ee-6c54-4b01-90e6-d701748f0869',
        order_number: 145,
        service_id: '27',
        amount: 0,
        currency: 'RUB',
        purpose: 'Покупка в игре',
        description: 'Покупка внутриигрового контента в игре Маша и Медведь, салон красоты Чародейка',
        language: 'ru-RU',
        tax_system: 0,
        order_bundle: [
            {
                position_id: 1,
                name: '100 кристаллов для использования при нырянии',
                quantity: {
                    value: 1.05,
                    measure: 'кг.',
                },
                item_price: 0,
                item_amount: 0,
                currency: 'RUB',
                item_code: 'com.MashaAndTheBear.HairSalon.crystal100',
            },
        ],
    },
    "$pay_api_key"
});
$session.invoice_id = response.invoice_id; // Сохраняем invoice_id

События eventData содержат информацию о коде ответа response_code и номере счета 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	Внутренняя ошибка работы сервиса. Обратитесь в поддержку для устранения неполадки

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

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

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

Безопасный способ передачи токена﻿

Небезопасный способ передачи токена﻿

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

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

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

Создание счета﻿

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

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

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

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

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

Коды ответа﻿