Архитектура TOTP Service

Сервис Cardsmobile TOTP предназначен для аутентификации мобильных карт лояльности при их предъявлении на кассе из приложения «Кошелёк».

Для аутентификации карты в системе эмитента используется механизм Time-Based One Time Password (TOTP): при предъявлении карты Кошелёк формирует одноразовый временный пароль на основе номера карты. Временный пароль выводится на экран Кошелька вместе с номером карты в формате штрих-кода, который считывается кассовым ПО и валидируется в инфраструктуре партнера.

Библиотека "Passcode Verify"

Валидация одноразового пароля, сформированного Кошельком при предъявлении карты, выполняется компонентом Passcode Verify — библиотекой, поставляемой Cardsmobile партнеру в формате JAR или DLL / SO. Библиотека может быть встроена партнером непосредственно в кассовое ПО, или в backend-сервис серверного ПО.

Библиотека проверяет значение пароля, поступающего на вход, и возвращает результат проверки, после чего ПО партнера обрабатывает результат в соответствии с внутренней логикой (например: выполняет списание баллов по программе лояльности и выводит результат на экран кассового терминала).

Вызов библиотеки

Для валидации пароля TOTP необходимо вызвать библиотеку Passcode Verify и передать ей значения параметров barcode, key, prefix, interval, passLength. Все параметры являются обязательными, любые изменения констант предварительно согласовываются с Cardsmobile:

barcode
key
prefix
interval
passLength

Значение, считанное сканером с экрана Кошелька или введенное кассиром вручную при предъявлении карты. Полное значение штрих-кода содержит в себе статическую часть (префикс и номер карты лояльности) и закрывающую динамическую часть (одноразовый временный пароль TOTP).

Можно передать библиотеке полное считанное значение штрих-кода (barcode), или с разбиением на части, предварительно отделив номер карты и пароль TOTP (cardNumber, passCode).

Пример А (barcode)
Пример Б (cardNumber, passCode)
CM2775599991258853

Секретный ключ партнера (HEX-строка, 16 байт, константа). Значение предварительно передается безопасным способом представителю Cardsmobile.

Пример
70ac89d41ee665408409ffdb1b6596e0

Префикс штрих-кода (константа) — указывает на то, что карта предъявляется из Кошелька. Мы рекомендуем использовать короткий префикс CM (сокр. от "Cardsmobile").

Пример
CM

Время жизни пароля TOTP (в секундах). Константа, рекомендуемое значение: 300.

Пример
300

Длина пароля TOTP. Константа, рекомендуемое значение: 3 символа.

Пример
3

Обработав входные данные, библиотека Passcode Verify возвращает однозначный результат проверки подлинности пароля («да» / «нет»), который далее обрабатывается ПО партнера в соответствии с внутренней логикой.