Сценарий 1. Оплата
Кошелёк Pay API
Документация перемещена
Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:
Поэтапное описание сценария оплаты
Сценарий описывает процесс оплаты товара или услуги из приложения «Кошелёк» посредством Кошелёк Pay. Описание сценария разбито на 2 этапа, при этом необходимо учитывать непрерывность выполнения сценария.
В сценарии оплаты через Кошелёк Pay сканирование карты лояльности выполняется строго 1 раз (одновременно для обработки карты в системе лояльности и для оплаты покупки).
1. Регистрация товаров, считывание карты лояльности и закрытие чека
Пояснение к диаграмме:
Номер шага | Описание |
---|---|
[01]-[03] | Пользователь выбирает карту лояльности ТСП в Кошельке. Кошелёк отображает данные карты лояльноcти: штрихкод, включающий в себя номер карты лояльности, код сессии предъявления карты и одноразовый пароль, сгенерированный по технологии «Кошелёк TOTP» — см. Модуль Кошелёк TOTP. |
[04] | Кассир сканирует штрихкод карты лояльности. Касса считывает номер карты лояльности и осуществляет проверку доступности оплаты сервисом Кошелёк Pay (в штрихкоде содержится |
[05]-[10] | Касса формирует запрос списка доступных провайдеров платежей (см. Запросы API v1.2.1) и получает от сервера Кошелька список провайдеров, а также значение флага |
[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] | На кассе отображается причина недоступности провайдеров (см. параметр |
Статусы платёжной транзакции
На диаграмме состояний приведены переходы между различными статусами транзакции в процессе выполнения сценария оплаты через Кошелёк Pay API.
Зелёным цветом отмечены успешные статусы.
Красным отмечены неуспешные статусы.
Жёлтым отмечены промежуточные статусы.
Обработка частных случаев оформления покупки
1. Покупка нештучного товара
В случае покупки нештучного товара (например, весового) необходимо указать:
в параметре
measure
— единицу измерения товара;в параметре
quantity
— количество товара (допускается только целое число) в указанной единице измерения.в параметре
price
— цена за единицу товара в перерасчёте на единицу измерения.
2. Количество одинаковых позиций товара превышает 1
Если покупатель приобретает позицию в количестве > 1, то необходимо передавать в Кошелёк информацию о точном количестве одинаковых позиций.
Только в таком случае будет успешно обработан сценарий частичного возврата товара, т.к. на стороне провайдера Долями в случае возврата проходит проверка на соответствие количества товара в отношении конкретного article
. В случае, если в оплате будет указано количество 1
, то частичный возврат оформить не получится.
3. Скидки, баллы, предоплата, смешанная оплата
Если часть суммы покупки оплачивается не Кошельком (используется предоплата / наличные / баллы или другой способ оплаты), то эту часть суммы необходимо указывать в поле discountAmount
.
Альтернативные сценарии оплаты
1. Пользователь решил добавить в чек (удалить из чека) продукт(ы) после отправки пречека серверу Кошелька
Действия ТСП:
Пользователю необходимо НЕ подтверждать оплату на экране подтверждения оплаты в Кошельке (в случае подтверждения оплата может пройти быстро и кассир может не успеть запросить отмену).
Необходимо выполнить отмену операции на кассе (см. Сценарий 2. Отмена оплаты).
Необходимо направить серверу Кошелька измененный пречек с тем же идентификатором
cardSession
, но новымrequestId
.
2. Пользователь решил отказаться от покупки или от части покупки после подтверждения оплаты в Кошельке
Действия ТСП:
Если ТСП ещё не пришел результат операции оплаты:
Необходимо выполнить отмену операции на кассе (см. Сценарий 2. Отмена оплаты). Если ТСП успевает отменить операцию до передачи оплаты в банк, то списание средств не произойдет и слип-чек по операции не будет выдан.
Если требуется изменение состава покупки, следует направить серверу Кошелька измененный пречек с тем же идентификатором
cardSession
(но новымrequestId
).
Если результат операции оплаты уже получен (даже если он получен после отправки операции отмены, т.е. сервер Кошелька уже передал запрос на оплату в банк до прихода запроса на отмену):
Если результат оплаты неудачный (оплата отклонена), для изменения состава покупки необходимо направить серверу Кошелька измененный пречек с тем же идентификатором
cardSession
(но новымrequestId
).Если оплата уже проведена и пользователь хочет отменить операцию, необходимо выполнить возврат средств (см. Сценарий 3. Возврат оплаты). Для проведения новой операции оплаты после завершения возврата потребуется повторное сканирование карты лояльности пользователя и получение нового
cardSession
.
3. Пользователь ошибочно отменил оплату в Кошельке
То есть: пользователь случайно (по ошибке) отменил оплату на экране подтверждения оплаты в Кошельке.
Действия ТСП:
Необходимо повторно направить серверу Кошелька пречек с тем же идентификатором
cardSession
(но новымrequestId
).
4. Банк по какой-либо причине отклонил оплату
По платежу пришел статус rejected
— платёж отклонён.
Действия ТСП:
Если платёж отклонён из-за недостаточности средств на счёте и пользователь исправил это, то необходимо повторно направить серверу Кошелька пречек с тем же идентификатором
cardSession
(но новымrequestId
).Если платёж отклонён по другим причинам (в том числе из-за технических проблем на стороне банка или СБП), то можно попробовать провести платеж ещё раз (см. случай с недостаточностью средств), или предложить пользователю использовать другой вариант оплаты. В случае повторного отклонения по техническим причинам — предложить пользователю использовать другой вариант оплаты.
5. На вызов запроса отправки пречека получена ошибка: «cardSession не существует/не прошел валидацию»
Действия ТСП:
Необходимо ещё раз просканировать штрихкод карты для того, чтобы ТСП получил новый
cardSession
пользователя.Необходимо направить серверу Кошелька изменённый пречек (запрос POST
/checkout
) с новыми идентификатором иcardSession
.
6. ТСП не получил ответ на запрос оплаты пречека ( POST /checkout
) и не может выполнить запрос POST /status
(т.к. не получил transactionId
в ответе на POST /checkout
)
/checkout
) и не может выполнить запрос POST /status
(т.к. не получил transactionId
в ответе на POST /checkout
)Допустимо отправить полностью идентичный повторный запрос на оплату пречека (запрос POST /checkout
) с теми же requestId
и cardSession
(методы API являются идемпотентными).
Last updated