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

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

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

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

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

Предъявление карты лояльности с поддержкой TOTP

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

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

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

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

Info

Информация о методах, указанных в сценарии, приведена ниже, в разделе «Описание методов библиотеки Passcode Verify».

  1. Пользователь открывает карту лояльности сети ритейлера в Кошельке.
  2. Кошелёк запрашивает данные для отображения данных карты (содержит штрихкод TOTP).
  3. Кошелёк отображает данные карты лояльности.
  4. Кассир сканирует штрихкод (ШК) карты лояльности.
  5. Касса обрабатывает считанный ШК.
  6. Касса передаёт строковый параметр, соответствующий считанному ШК (fullBarcode), модулю Koshelek TOTP на кассе в качестве входного параметра для вызова метода barcodeVerify() библиотеки Passcode Verify.
  7. Модуль Koshelek TOTP на кассе анализирует полноту ШК и выделяет из полученного значения fullBarcode префикс, номер карты лояльности, парольную часть TOTP — все ожидаемые модулем параметры присутствуют в ШК.
  8. Модуль Koshelek TOTP на кассе проверяет:
    • действительность парольной части TOTP на основе префикса и номера карты лояльности;
    • доступность операций по карте лояльности (списание / начисление бонусов).
  9. Модуль Koshelek TOTP на кассе возвращает кассе ответ, содержащий параметры:
    • Код ответа (resultCode = CARDSESSION_NOT_AVAILABLE)
    • Успешный результат валидации (totpCodeValid = true)
    • Номер карты лояльности (cardNumber)
    • Полное значение ШК (fullBarcode)
  10. Касса обрабатывает успешный результат валидации.

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

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

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

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

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

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

Описание методов библиотеки Passcode Verify

Info

Названия методов и параметров могут незначительно отличаться в зависимости от формата библиотеки.

init()

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

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

Параметр Тип данных Обязательно Описание
algorythm String Да Используемый алгоритм шифрования. Возможные значения:
HMACSHA256
HMACSHA1
passLength Int Да Число символов одноразового пароля. Максимальное значение: 8.
prefix String Да Префикс штрихкода (по умолчанию всегда CM).
key String Да Секретный ключ партнера (HEX String), нужен для формирования пароля.
interval Int Да Интервал (в секундах), в рамках которого одноразовый пароль считается действительным.
cardSessionLength Int Да Количество символов параметра cardSession. Значение по умолчанию: 6
delimeter String Да Разделитель между составляющими штрихкода. Допустимое значение: пробел.

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

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

barcodeVerify()

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

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

Параметр Тип данных Обязательно Описание
fullBarcode String Да Значение штрихкода.

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

Параметр Тип данных Обязательно Описание
resultCode String Да Возможные значения в зависимости от сценария:
CARDSESSION_AVAILABLE (deprecated)
ANOTHER_INSTANCE
CARDSESSION_NOT_AVAILABLE
VALIDATION_FAILED
totpCodeValid Boolean См. описание →
  • Если в fullBarcode присутствует парольная часть TOTP и карта лояльности валидна, возвращается значение = true.
  • Если в fullBarcode присутствует парольная часть TOTP и карта лояльности невалидна, возвращается значение = false.
  • Если в fullBarcode не присутствует парольная часть TOTP, возвращается значение = false.
cardNumber String См. описание →
  • Возвращается всегда, кроме случаев, если префикс отсутствует или не равен префиксу из конфигурации (то есть, если источник предъявления штрихкода — не Кошелёк).
  • Если источник предъявления карты — не Кошелёк, возвращается значение = null.
cardSession String См. описание →
  • Если в fullBarcode присутствует cardSession возвращается его значение (deprecated).
  • Если в fullBarcode не присутствует cardSession возвращается значение = null.
fullBarcode String Да Значение штрихкода, полученное библиотекой от сканера кассы.

getToken() - (deprecated)

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

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

Параметр Тип данных Обязательно Описание
requestData String Да Строка, содержащая JSON тела ответа запроса POST /checkout.

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

Параметр Тип данных Обязательно Описание
token String Да Токен для передачи в качестве заголовка запроса POST /checkout.