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

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

Документация перемещена

Информация на этой странице не обновляется и может быть устаревшей. Наиболее полная и актуальная версия документации для разработчиков доступна по новому адресу:

https://developers.koshelek.app

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

Диаграмма последовательности

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

(для просмотра в полном разрешении откройте изображение в новой вкладке)

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

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

1. На стороне кассового сервера кассы развёрнут модуль Кошелёк TOTP.

2. На стороне кассового сервера реализована поддержка предварительно согласованных с Кошельком значений параметров конфигурации модуля (см. Установка и конфигурирование).

3. На стороне кассового сервера выполнена инициализация библиотеки Passcode Verify (вызван метод init, в котором переданы обязательные параметры конфигурации).

4. На стороне кассы реализована обработка ответов, которые возвращает модуль Кошелёк TOTP в ответ на запрос метода barcodeVerify.

5. На сервере Кошелька осуществлена настройка сервисов для осуществления взаимодействия с ритейлером.

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

Информация о методах, указанных в сценарии, приведена ниже, в разделе "Описание методов библиотеки Passcode Verify для оплаты через Кошелёк Pay".

1. Пользователь открывает карту лояльности сети ритейлера в Кошельке.

2. Кошелёк запрашивает данные для отображения данных карты (содержит штрихкод TOTP).

3. Кошелёк отображает данные карты лояльности.

4. Кассир сканирует штрихкод (ШК) карты лояльности.

5. Касса обрабатывает считанный ШК.

6. Касса передаёт строковый параметр, соответствующий считанному ШК (fullBarcode), модулю Кошелёк TOTP на кассовом сервере в качестве входного параметра для вызова метода barcodeVerify библиотеки Passcode Verify.

7. Модуль Кошелёк TOTP на кассовом сервере анализирует полноту ШК и выделяет из полученного параметра fullBarcode префикс, номер карты лояльности, сессию предъявления карты (cardSession), парольную часть TOTP — все ожидаемые модулем параметры присутствуют в ШК.

8. Модуль Кошелёк TOTP на кассовом сервере проверяет: • действительность парольной части TOTP на основе префикса и номера карты лояльности; • доступность операций по карте лояльности (списание/начисление бонусов); • возможность дальнейшей оплаты с помощью Кошелёк Pay.

9. Модуль Кошелёк TOTP на кассовом сервере возвращает кассе ответ, содержащий параметры: • Код ответа (resultCode = CARDSESSION_AVAILABLE) • Успешный результат валидации (totpCodeValid = true) • Номер карты лояльности (cardNumber) • Сессия карты (cardSession) • Полное значение ШК (fullBarcode)

10. Касса обрабатывает успешный результат валидации и временно сохраняет сессию предъявления карты cardSession.

11. Кассир предлагает пользователю оплату через Кошелёк Pay.

12. Пользователь подтверждает оплату через Кошелёк Pay.

13. Касса формирует запрос инициализации платежа для отправки методов POST /availability-info, /checkout, /refund и временно сохраняет его.

14. Касса передает JSON тела запроса в качестве строкового параметра requestData модулю Кошелёк TOTP на кассовом сервере в качестве входного параметра для вызова метода getToken библиотеки Passcode Verify.

15. Кассовый модуль Кошелёк TOTP на сервере кассы получает строковый параметр requestData.

16. Модуль Кошелёк TOTP на кассовом сервере осуществляет необходимые преобразования для получения токена (token) для последующих действий.

17. Модуль Кошелёк TOTP на кассовом сервере возвращает кассе параметр token.

18. Касса отправляет запрос POST /availability-info, /checkout, /refund на сервер Кошелька. В качестве заголовка передается параметр token.

19. Сервер Кошелька получает и обрабатывает полученный заголовок и данные запроса.

20. Сервер Кошелька осуществляет валидацию полученных данных.

21. Сервер Кошелька возвращает кассе успешный ответ и формирует пречек для отправки в приложение в соответствии со сценарием оплаты с помощью Кошелёк Pay.

22. Дальнейший сценарий на кассе осуществляется в соответствии со сценарием проведения транзакции на кассе с помощью Кошелёк Pay (см. Обзор сценариев API).

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

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

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

1. Модуль Кошелёк TOTP на кассовом сервере возвращает кассе ответ, содержащий:

   • Код ответа (resultCode = ANOTHER_INSTANCE).

   • Неуспешный результат валидации (totpCodeValid = false).

   • Номер карты лояльности отсутствует (cardNumber = null).

   • Сессия карты отсутствует (cardSession = null).

   • Полное значение ШК (fullBarcode).

2. Касса обрабатывает ответ модуля.

3. Сценарий на кассе осуществляется по схеме без списания/начисления бонусов, без использования функциональности оплаты через Кошелёк Pay с учетом, что источник предъявления карты — не Кошелёк.

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

1. Модуль Кошелёк TOTP проверяет действительность парольной части TOTP: пароль действителен.

2. Модуль Кошелёк TOTP возвращает кассе ответ, содержащий:

   • Код ответа (resultCode = CARDSESSION_NOT_AVAILABLE)

   • Успешный результат валидации (totpCodeValid = true) • Номер карты лояльности (cardNumber) • Указание на отсутствие сессии карты (cardSession = null) • Полное значение ШК (fullBarcode)

3. Касса обрабатывает ответ модуля.

4. Сценарий на кассе осуществляется по стандартной схеме списания/начисления бонусов, без использования функциональности оплаты через Кошелёк Pay.

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

1. Модуль Кошелёк TOTP проверяет действительность парольной части TOTP: пароль недействителен.

2. Модуль Кошелёк TOTP возвращает кассе ответ, содержащий:

   • Код ответа (resultCode = VALIDATION_FAILED). • Неуспешный результат валидации (totpCodeValid = false). • Номер карты лояльности (cardNumber). • Указание на отсутствие сессии карты (cardSession = null). • Полное значение ШК (fullBarcode).

3. Касса обрабатывает ответ модуля.

4. Касса выводит в интерфейс сообщение об ошибке.

5. Кассир сообщает о невозможности начислить/списать бонусы, а также совершить дальнейшие действия с картой.

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

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

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

1. Сервер Кошелька проанализировал и установил, что полученный token в заголовке запроса POST /availability-info, /checkout, /refund недействителен.

2. Сервер Кошелька возвращает кассе ошибку.

3. Касса обрабатывает ошибку.

4. Кассир сообщает о невозможности совершить дальнейшие действия с картой.

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

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

Инициализация (init)

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

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

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

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

Верификация штрихкода (barcodeVerify)

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

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

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

Параметр	Тип данных	Обязательно	Описание
resultCode	String	Да	Возможные значения в зависимости от сценария: CARDSESSION_AVAILABLE 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 возвращается его значение. Если в fullBarcode не присутствует cardSession возвращается значение = null.
fullBarcode	String	Да	Значение штрихкода, полученное библиотекой от сканера кассы.

Получение токена (getToken)

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

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

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

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