ym88659208ym87991671
Прием платежей в Code | Документация для разработчиков

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

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

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

  1. Формирование корзины.
  2. Создание счета.
  3. Проведение платежа.
  4. Получение статуса.
  5. Просмотр товаров в счете.
  6. Просмотр купленных товаров.
  7. Просмотр купленного товара.

Для смартапов, созданных в 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Да, если не передан phoneEmail покупателя.

При передаче нескольких значений используется разделитель ","
    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
Внутренняя ошибка работы сервиса. Обратитесь в поддержку для устранения неполадки
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.