Перейти к содержанию

Сценарий 1. Оплата

Pay API

Поэтапное описание сценария оплаты

Сценарий оплаты товара или услуги ТСП из приложения «Кошелёк» посредством Koshelek Pay. Описание сценария разбито на 2 этапа, при этом необходимо учитывать непрерывность выполнения сценария.

Warning

В сценарии оплаты через Koshelek Pay сканирование карты лояльности выполняется строго 1 раз (одновременно для обработки карты в системе лояльности и для оплаты покупки).

1. Регистрация товаров, считывание карты лояльности и закрытие чека

Регистрация товаров, считывание карты лояльности и закрытие чека

Пояснение к диаграмме:

Номер шага Описание
[01]-[03] Пользователь выбирает карту лояльности ТСП в Кошельке. Кошелёк отображает данные карты лояльности: штрихкод, включающий в себя номер карты лояльности, код сессии предъявления карты и одноразовый пароль, сгенерированный по технологии «Кошелёк TOTP» (см. Модуль Koshelek TOTP).
[04] Кассир сканирует штрихкод карты лояльности. Касса считывает номер карты лояльности и осуществляет проверку доступности оплаты сервисом Koshelek Pay (в штрихкоде содержится cardSession), а также проводит валидацию парольной части (см. Модуль Кошелёк TOTP), идентифицирует покупателя и производит расчет суммы к оплате.
[05]-[10] Касса формирует запрос списка доступных провайдеров платежей (см. Pay API) и получает от сервера Кошелька список провайдеров, а также значение флага koshelekPayIsDefault, указывающего, выбран ли у пользователя сервис Koshelek Pay в качестве способа оплаты по умолчанию.
[11] Если оплата сервисом Koshelek Pay не подключена в Кошельке пользователя, происходит переход к альтернативным методам оплаты: наличные или карта. Сценарий завершён.
[12]-[14] (опциональные шаги)
Касса обращается к ЦОД ТСП для расчёта скидок и бонусов для разных способов оплаты (традиционных и для полученных провайдеров платежей).
ЦОД ТСП выполняет расчёт и возвращает кассовому терминалу для каждого провайдера маркетинговое сообщение для показа пользователю в Кошельке.
Кассовое ПО формирует итоговое значение суммы платежа и скидок в чеке для каждого способа оплаты — для способа оплаты через Кошелёк итоговая сумма и сумма скидок должна быть одинаковой для всех провайдеров платежей (отличаться могут маркетинговое сообщение и последующие бонусы от ТСП после оплаты через определенного провайдера платежей).

Алгоритм получения списка доступных провайдеров платежей:

Алгоритм получения списка доступных провайдеров платежей

2. Оплата

Оплата

Выполнение этого этапа определяется значением флага koshelekPayIsDefault.

koshelekPayIsDefault = true:

Номер шага Описание
[01]-[05] ТСП автоматически выполняет запрос формирования счёта к оплате (см. Pay API). Счёт в виде суммы к оплате передаётся на экран Кошелька пользователя.
[06] Пользователь инициирует оплату на экране Кошелька.
[07]-[11] Сервер Кошелька выполняет оплату и передаёт ТСП и пользователю информацию о статусе операции.
[12]-[14] ТСП отправляет серверу Кошелька чек операции (см. Pay API). Чек отображается на экране Кошелька. Сценарий завершён.

koshelekPayIsDefault = false и доступен хотя бы один провайдер платежей:

Номер шага Описание
[15]-[22] Кассир называет сумму покупки с учётом применения карты лояльности и предлагает пользователю оплату сервисом Koshelek Pay. Если пользователь согласен, то кассир инициирует запрос на формирование счёта к оплате (см. Pay API). Счёт в виде суммы к оплате передаётся на экран Кошелька.
[23] Пользователь инициирует оплату на экране Кошелька.
[24]-[28] Сервер Кошелька выполняет оплату и передаёт ТСП и пользователю информацию о статусе операции.
[29]-[31] ТСП отправляет серверу Кошелька чек операции (см. Pay API). Чек отображается на экране Кошелька. Сценарий завершён.

Недоступен ни один из провайдеров платежей:

Номер шага Описание
[32] На кассе отображается причина недоступности провайдеров (см. параметр message для каждого провайдера). Сценарий завершён.

Статусы платёжной транзакции

На диаграмме состояний приведены переходы между различными статусами транзакции в процессе оплаты через Pay API.

  • Зелёным цветом отмечены успешные статусы.
  • Красным отмечены неуспешные статусы.
  • Серым отмечены промежуточные статусы.

Статусы платёжной транзакции

Обработка частных случаев оформления покупки

1. Покупка нештучного товара

В случае покупки нештучного товара (например, весового) необходимо указать:

  • в параметре measure — единицу измерения товара;
  • в параметре quantity — количество товара (допускается только целое число) в указанной единице измерения;
  • в параметре price — цена за единицу товара в перерасчёте на единицу измерения.
Пример

В торговом зале указана стоимость 1 кг бананов: 100 руб.

Случай 1: на кассе оформляется покупка 1 кг бананов.

Тогда в запросе необходимо указать:

  • Единица измерения measure = GRAM или KILOGRAM
  • Количество товара quantity =
    • 1 (если measure = KILOGRAM)
    • 1000 (если measure = GRAM)
  • Цена за единицу товара price =
    • 10000 копеек (если measure = KILOGRAM)
    • 10 копеек (если measure = GRAM)

Случай 2: на кассе оформляется покупка 0,5 кг бананов.

Тогда в запросе необходимо указать:

  • Единица измерения measure = GRAM
  • Количество товара quantity = 500
  • Цена за единицу товара price = 10 копеек за GRAM

2. Количество одинаковых позиций превышает 1

Если покупатель приобретает позицию в количестве > 1, то необходимо передавать в Кошелёк информацию о точном количестве одинаковых позиций.

Только в таком случае будет успешно обработан сценарий частичного возврата товара, т.к. на стороне провайдера Долями в случае возврата проходит проверка на соответствие количества товара в отношении конкретного article. В случае, если в оплате будет указано количество = 1, частичный возврат оформить не получится.

Пример

На кассе оформляется покупка двух ручек с одинаковым article = 12345. В этом случае доступно 2 способа корректной передачи информации о товарах:

Способ 1: передача в одном item

  • name = ручка
  • quantity = 2
  • article = 12345

Способ 2: передача в двух item

Первый item:

  • name = ручка
  • quantity = 1
  • article = 12345

Второй item:

  • name = ручка
  • quantity = 1
  • article = 12345

3. Скидки, баллы, предоплата, смешанная оплата

Если часть суммы покупки оплачивается не Кошельком (используется предоплата / наличные / баллы или другой способ оплаты), то эту часть суммы необходимо указывать в поле discountAmount.

Пример

Случай 1: предоплата

Покупатель оформляет услугу «ремонт автомобиля» (её стоимость: 10 000 руб.) При этом запчасти необходимо покупать и доставлять в сервис заранее. По условиям, необходимо оплатить аванс (2 000 руб.)

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

  • discountAmount = 200000 копеек (экв. 2 000 руб.)
  • totalAmount = 800000 копеек (экв. 8 000 руб.)

Случай 2: частичная оплата баллами

Покупатель сформировал чек на 1000 руб., из которых 300 руб. будет оплачивать баллами, а остальные 700 руб. — Кошельком. Тогда в запросе необходимо указать:

  • discountAmount = 30000 копеек (экв. 300 руб.)
  • totalAmount = 70000 копеек (экв. 700 руб.)

Альтернативные сценарии оплаты

1. Пользователь решил добавить в чек (удалить из чека) продукт(ы) после отправки пречека серверу Кошелька

Действия ТСП:

  1. Пользователю необходимо НЕ подтверждать оплату на экране подтверждения оплаты в Кошельке (в случае подтверждения оплата может пройти быстро и кассир может не успеть запросить отмену).
  2. Необходимо выполнить отмену операции на кассе (см. Сценарий 2. Отмена оплаты).
  3. Необходимо направить серверу Кошелька измененный пречек с тем же идентификатором cardSession, но новым requestId.

2. Пользователь решил отказаться от покупки или от части покупки после подтверждения оплаты в Кошельке

Действия ТСП:

  • Если ТСП еще не пришёл результат операции оплаты:
    1. Необходимо выполнить отмену операции на кассе (см. Сценарий 2. Отмена оплаты). Если ТСП успевает отменить операцию до передачи оплаты в банк, то списание средств не произойдет и слип-чек по операции не будет выдан.
    2. Если требуется изменение состава покупки, следует направить серверу Кошелька измененный пречек с тем же идентификатором cardSession (но новым requestId).
  • Если результат операции оплаты уже получен (даже если он получен после отправки операции отмены, т.е. сервер Кошелька уже передал запрос на оплату в банк до прихода запроса на отмену):
    1. Если результат оплаты неудачный (оплата отклонена), для изменения состава покупки необходимо направить серверу Кошелька изменённый пречек с тем же идентификатором cardSession (но новым requestId).
    2. Если оплата уже проведена и пользователь хочет отменить операцию, необходимо выполнить возврат средств (см. Сценарий 3. Возврат оплаты). Для проведения новой операции оплаты после завершения возврата потребуется повторное сканирование карты лояльности пользователя и получение нового cardSession.

3. Пользователь ошибочно отменил оплату в Кошельке

То есть: пользователь случайно (по ошибке) отменил оплату на экране подтверждения оплаты в Кошельке.

Действия ТСП:

  1. Необходимо повторно направить серверу Кошелька пречек с тем же идентификатором cardSession (но новым requestId).

4. Банк по какой-либо причине отклонил оплату

По платежу пришел статус rejected — платёж отклонён.

Действия ТСП:

  • Если платёж отклонён из-за недостаточности средств на счёте и пользователь исправил это:
    1. Необходимо повторно направить серверу Кошелька пречек с тем же идентификатором cardSession (но новым requestId).
  • Если платёж отклонён по другим причинам (в том числе из-за технических проблем на стороне банка или СБП):
    1. Можно попробовать провести платёж ещё раз (см. случай с недостаточностью средств), или предложить пользователю использовать другой вариант оплаты. В случае повторного отклонения по техническим причинам — предложить пользователю использовать другой вариант оплаты.

5. На вызов запроса отправки пречека получена ошибка: «cardSession не существует / не прошёл валидацию»

Действия ТСП:

  1. Необходимо ещё раз просканировать штрихкод карты для того, чтобы ТСП получил новый cardSession пользователя.
  2. Необходимо направить серверу Кошелька изменённый пречек (запрос POST /checkout) с новыми идентификатором и cardSession.

6. ТСП не получил ответ на запрос оплаты пречека (POST /checkout) и не может выполнить запрос POST /status (т.к. не получил transactionId в ответе на POST /checkout)

Действия ТСП:

  1. Допустимо отправить полностью идентичный повторный запрос на оплату пречека (запрос POST /checkout) с теми же requestId и cardSession (методы API являются идемпотентными).