Использование

Описание процесса верификации карты лояльности на кассе при оплате через сервис Koshelek Pay.

Сценарий предъявления карты лояльности с участием модуля Koshelek TOTP

Диаграмма взаимодействия участников при предъявлении карты лояльности на кассе ТСП:

Предварительные условия

Для выполнения основного сценария необходимо выполнение следующих предварительных условий:

1. На стороне кассового сервера кассы развёрнут модуль Koshelek TOTP.
2. На стороне кассового сервера реализована поддержка предварительно согласованных с Кошельком значений параметров конфигурации модуля (см. Установка и конфигурирование).
3. На стороне кассового сервера выполнена инициализация библиотеки Passcode Verify (вызван метод init(), в котором переданы обязательные параметры конфигурации).
4. На стороне кассы реализована обработка ответов, которые возвращает модуль Koshelek TOTP в ответ на запрос метода barcodeVerify().
5. На сервере Кошелька осуществлена настройка сервисов для осуществления взаимодействия с ритейлером.

Основной сценарий

1. Пользователь открывает карту лояльности сети ритейлера в Кошельке.
2. Кошелёк запрашивает данные для отображения данных карты (содержит штрихкод TOTP).
3. Кошелёк отображает данные карты лояльности.
4. Кассир сканирует штрихкод (ШК) карты лояльности.
5. Касса обрабатывает считанный ШК.
6. Касса передаёт строковый параметр, соответствующий считанному ШК (fullBarcode), модулю Koshelek TOTP на кассовом сервере в качестве входного параметра для вызова метода barcodeVerify() библиотеки Passcode Verify.
7. Модуль Koshelek TOTP на кассовом сервере анализирует полноту ШК и выделяет из полученного значения fullBarcode префикс, номер карты лояльности, сессию предъявления карты (cardSession), парольную часть TOTP — все ожидаемые модулем параметры присутствуют в ШК.
8. Модуль Koshelek TOTP на кассовом сервере проверяет:
   • действительность парольной части TOTP на основе префикса и номера карты лояльности;
   • доступность операций по карте лояльности (списание / начисление бонусов);
   • возможность дальнейшей оплаты с помощью Koshelek Pay.
9. Модуль Koshelek TOTP на кассовом сервере возвращает кассе ответ, содержащий параметры:
   • Код ответа (resultCode = CARDSESSION_AVAILABLE)
   • Успешный результат валидации (totpCodeValid = true)
   • Номер карты лояльности (cardNumber)
   • Сессия карты (cardSession)
   • Полное значение ШК (fullBarcode)
10. Касса обрабатывает успешный результат валидации и временно сохраняет значение сессии предъявления карты cardSession.
11. Кассир предлагает пользователю оплату через Koshelek Pay.
12. Пользователь подтверждает оплату через Koshelek Pay.
13. Касса формирует запрос инициализации платежа для отправки методов POST /availability-info/task, POST /checkout, POST /refund и временно сохраняет его.
14. Касса передаёт JSON тела запроса в качестве строкового параметра requestData модулю Koshelek TOTP на кассовом сервере в качестве входного параметра для вызова метода getToken() библиотеки Passcode Verify.
15. Кассовый модуль Koshelek TOTP на сервере кассы получает строковый параметр requestData.
16. Модуль Koshelek TOTP на кассовом сервере осуществляет необходимые преобразования для получения токена (token) для последующих действий.
17. Модуль Koshelek TOTP на кассовом сервере возвращает кассе параметр token.
18. Касса отправляет запросы POST /availability-info/task, POST /checkout, POST /refund на сервер Кошелька. В качестве заголовка передается параметр token.
19. Сервер Кошелька получает и обрабатывает полученный заголовок и данные запроса.
20. Сервер Кошелька осуществляет валидацию полученных данных.
21. Сервер Кошелька возвращает кассе успешный ответ и формирует пречек для отправки в приложение в соответствии со сценарием оплаты с помощью Koshelek Pay.
22. Дальнейший сценарий на кассе осуществляется в соответствии со сценарием проведения транзакции на кассе с помощью Koshelek Pay (см. Обзор сценариев API).

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

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

Шаг 7 основного сценария: в ШК карты лояльности не содержится префикс или его значение отличается от значения, заявленного в конфигурации: источник предъявления карты не Кошелёк

1. Модуль Koshelek TOTP на кассовом сервере возвращает кассе ответ, содержащий:
   • Код ответа (resultCode = ANOTHER_INSTANCE).
   • Неуспешный результат валидации (totpCodeValid = false).
   • Номер карты лояльности отсутствует (cardNumber = null).
   • Сессия карты отсутствует (cardSession = null).
   • Полное значение ШК (fullBarcode).
2. Касса обрабатывает ответ модуля.
3. Сценарий на кассе осуществляется по схеме без списания / начисления бонусов, без использования функциональности оплаты через Koshelek Pay с учётом, что источник предъявления карты — не Кошелёк.

Шаг 7 основного сценария: карта лояльности действительна, но в ШК карты не содержится сессия предъявления карты cardSession: функциональность Koshelek Pay недоступна

1. Модуль Koshelek TOTP проверяет действительность парольной части TOTP: пароль действителен.
2. Модуль Koshelek TOTP возвращает кассе ответ, содержащий:
   • Код ответа (resultCode = CARDSESSION_NOT_AVAILABLE)
   • Успешный результат валидации (totpCodeValid = true)
   • Номер карты лояльности (cardNumber)
   • Указание на отсутствие сессии карты (cardSession = null)
   • Полное значение ШК (fullBarcode)
3. Касса обрабатывает ответ модуля.
4. Сценарий на кассе осуществляется по стандартной схеме списания / начисления бонусов, без использования функциональности оплаты через Koshelek Pay.

Шаг 7 основного сценария: карта лояльности недействительна: ошибка списания / начисления бонусов, отсутствие дальнейших действий с участием карты

1. Модуль Koshelek TOTP проверяет действительность парольной части TOTP: пароль недействителен.
2. Модуль Koshelek TOTP возвращает кассе ответ, содержащий:
   • Код ответа (resultCode = VALIDATION_FAILED)
   • Неуспешный результат валидации (totpCodeValid = false)
   • Номер карты лояльности (cardNumber)
   • Указание на отсутствие сессии карты (cardSession = null)
   • Полное значение ШК (fullBarcode)
3. Касса обрабатывает ответ модуля.
4. Касса выводит в интерфейс сообщение об ошибке.
5. Кассир сообщает о невозможности начислить / списать бонусы, а также совершить дальнейшие действия с картой.

Шаг 8 основного сценария: карта лояльности недействительна: ошибка списания / начисления бонусов, отсутствие дальнейших действий с участием карты

Сценарий полностью соответствует предыдущему.

Шаг 21 основного сценария: значение токена, полученное в заголовке запроса от кассы, недействительно: отсутствие дальнейших действий с участием карты

1. Сервер Кошелька проанализировал и установил, что полученный token в заголовке запроса POST /availability-info/task, POST /checkout, POST /refund недействителен.
2. Сервер Кошелька возвращает кассе ошибку.
3. Касса обрабатывает ошибку.
4. Кассир сообщает о невозможности совершить дальнейшие действия с картой.

Описание методов библиотеки Passcode Verify для оплаты через Koshelek Pay

init()

Инициализация библиотеки.

Входные параметры

Выходные параметры

Отсутствуют.

barcodeVerify()

Верификация штрихкода.

Входные параметры

Выходные параметры

getToken()

Получение токена.

Входные параметры

Выходные параметры