Russian
Обзор сценариев API
Кошелёк Pay API

Требования к ТСП для реализации сценариев

Для реализации сценариев оплаты при помощи Кошелёк Pay API, к торгово-сервисному предприятию предъявляются следующие технические требования.

1. Прием штрихкодов с поддержкой TOTP

Для верификации штрихкодов, поддерживающих Кошелёк Pay, ТСП необходимо обеспечить прием и распознавание штрихкодов карт лояльности, содержащих не только номер карты, но и верифицирующую информацию: одноразовый код сессии cardSession и одноразовый пароль TOTP (см. Модуль Кошелёк TOTP).
Также возможен вариант реализации, при котором ТСП самостоятельно генерирует одноразовые QR-коды, а приложение «Кошелёк» распознает код и передает его ТСП вместе с cardSession. Одноразовый код cardSession генерируется сервером Кошелька по запросу от приложения «Кошелёк».
Пример штрихкода TOTP, формируемого приложением «Кошелёк» для оплаты с помощью Кошелёк Pay:
Структура штрихкода TOTP
Если ТСП использует одномерные штрихкоды (например, формата code128), то максимальное значение любого штрихкода будет складываться их следующих данных:
  • prefix — префикс, не более 2-х символов (допустимы буквы латинского алфавита и цифры).
  • cardNumber — номер карты, не более 13 цифр при использовании префикса, или 16 цифр без использования префикса.
  • cardSession — код сессии предъявления карты, генерируется сервером, по умолчанию содержит 6 символов.
  • delimeter — разделитель, отделяет парольную часть TOTP.
  • TOTP password — парольная часть TOTP, 3 цифры (на основе конфигурации TOTP-профиля партнера).
Если длина (номера карты + префикса) превышает указанные лимиты, ТСП необходимо использовать двумерные штрихкоды, т.к. одномерный штрихкод большей длины не сможет быть корректно отображен на экранах смартфонов для его считывания сканером.
Допустимые форматы штрихкодов: code128, PDF417, DataMatrix, QR code.

2. Интеграция программного модуля Кошелёк TOTP

Для работы с TOTP-штрихкодами Кошелёк Pay партнеру необходимо интегрировать в свою инфраструктуру программный модуль "Кошелёк TOTP" — в соответствии с руководством на странице Модуль Кошелёк TOTP.

3. Минимальная задержка при обработке сценариев

После указания покупателем способа оплаты через Кошелёк Pay и выбора соответствующего способа кассиром в кассовом ПО, система ТСП должна незамедлительно передать в Кошелёк Pay API данные, необходимые для оплаты. Время задержки между нажатием кнопки на кассе и передачей данных на сервер Кошелька не должно превышать 0,5 секунды.

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

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

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

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

1.2. Оплата

(для просмотра в полном разрешении откройте изображение в новой вкладке)
Выполнение этого этапа определяется значением флага koshelekPayIsDefault.
koshelekPayIsDefault = true:
Номер шага
Описание
[01]-[05]
ТСП автоматически выполняет запрос формирования счета к оплате (см. Запросы API). Счет в виде суммы к оплате передается на экран Кошелька пользователя.
[06]
Пользователь инициирует оплату на экране Кошелька.
[07]-[11]
Сервер Кошелька выполняет оплату и передает ТСП и пользователю информацию о статусе операции.
[12]-[14]
ТСП отправляет серверу Кошелька чек операции (см. Запросы API). Чек отображается на экране Кошелька.
Сценарий завершен.
koshelekPayIsDefault = false и доступен хотя бы один провайдер платежей:
Номер шага
Описание
[15]-[22]
Кассир озвучивает сумму покупки с учетом применения карты лояльности и предлагает пользователю оплату сервисом Кошелёк Pay. Если пользователь согласен, то кассир инициирует запрос на формирование счета к оплате (см. Запросы API). Счет в виде суммы к оплате передается на экран Кошелька пользователя.
[23]
Пользователь инициирует оплату на экране Кошелька.
[24]-[28]
Сервер Кошелька выполняет оплату и передает ТСП и пользователю информацию о статусе операции.
[29]-[31]
ТСП отправляет серверу Кошелька чек операции (см. Запросы API). Чек отображается на экране Кошелька.
Сценарий завершен.
Недоступен ни один из провайдеров платежей:
Номер шага
Описание
[32]
На кассе отображается причина недоступности провайдеров (см. параметр message для каждого провайдера). Сценарий завершен.

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

На диаграмме состояний приведены переходы между различными статусами транзакции в процессе выполнения сценария оплаты через Кошелёк Pay API. Зеленым цветом отмечены успешные, красным — неуспешные статусы, остальные статусы считаются промежуточными.
(для просмотра в полном разрешении откройте изображение в новой вкладке)

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

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

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

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

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

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

(то есть: пользователь случайно/по ошибке отменил оплату на экране подтверждения оплаты в Кошельке).
Действия ТСП:
  1. 1.
    Необходимо повторно направить серверу Кошелька пречек с тем же идентификатором cardSession (но новым requestId).

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

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

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

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

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

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

Сценарий 2. «Отмена оплаты»

Сценарий описывает отмену непосредственно текущей операции оплаты на кассе, (пока не получен слип-чек об оплате). Для случая, когда оплата уже прошла и необходимо ее отменить (с возвратом средств покупателю) — см. Сценарий 3. «Возврат оплаты по чеку».
(для просмотра в полном разрешении откройте изображение в новой вкладке)
Примеры текстовых сообщений к передаваемому статусу транзакции в случае отклонения отмены по refTransactionId:
Статус транзакции
Сообщение о причине отклонения транзакции отмены
Canceled
Отмена отклонена, т.к. транзакция оплаты с transactionId = <transactionId> уже была отменена ранее.
Accepted
Отмена отклонена, т.к. транзакция оплаты с transactionId = <transactionId> уже была одобрена банком. Для отмены уже выполененной оплаты выполните операцию возврата.
Все Refund-статусы
Отмена отклонена, т.к. транзакция оплаты с transactionId = <transactionId> уже была одобрена банком.
Примечание. Обработка данного статуса была предусмотрена, однако такая ситуация не должна возникнуть, т.к. для оплаченных транзакций на кассе не должно быть кнопки отмены, а если транзакция находится в любом из Refund-статусов, значит, по ней выполняется/выполнялся возврат и факт оплаты точно известен.
Транзакция не найдена
Отмена отклонена, т.к. транзакция оплаты с transactionId = <transactionId> не найдена.
Точные формулировки приведены для примера и пояснения причин возможных отклонений операции отмены и могут быть изменены.

Сценарий 3. «Возврат оплаты по чеку»

Сценарий возврата описывает действия, которые необходимо выполнить, чтобы вернуть покупателю оплаченную сумму. Сценарий может быть выполнен только при наличии уже завершенной операции оплаты.
(для просмотра в полном разрешении откройте изображение в новой вкладке)

Статусы транзакции отмены

На диаграмме состояний приведены переходы между различными статусами транзакции в процессе выполнения сценариев отмены или возврата платежа через Кошелёк Pay API. Зеленым цветом отмечены успешные, красным — неуспешные статусы, остальные статусы считаются промежуточными.
Last modified 18d ago