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

Кошелёк Pay API

Документация перемещена

Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:

https://developers.koshelek.app

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

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

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

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

(для просмотра в полном разрешении откройте изображение в новой вкладке)

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

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

2. Оплата

(для просмотра в полном разрешении откройте изображение в новой вкладке)

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

koshelekPayIsDefault = true:

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

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

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

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

Номер шага	Описание
[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 — платёж отклонён.

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

• Если платёж отклонён из-за недостаточности средств на счёте и пользователь исправил это, то необходимо повторно направить серверу Кошелька пречек с тем же идентификатором cardSession (но новым requestId).

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

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

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

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

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

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

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