Протокол VTK, разработанный компанией Vendotek — это протокол прикладного уровня для взаимодействия между POS-терминалом и контроллером торгового автомата (VMC) для передачи запросов через интерфейс последовательного порта (RS-232) или через интерфейс для обмена данными по TCP/IP.
Протокол VTK реализован на разных устройствах Vendotek: Vendotek V1, V2,V3,VX как прикладное ПО EftVending и на Vendotek VL, VN, VT - VTKPOS-V1, VTKPOS-V2, которые различаются уровнями функциональности.
Полезные ссылки
¶ Уровни функциоанльности
Скорость последовательного порта по умолчанию: 115200 бит/с, режим 8N1, без управления потоком. В ПО EftVending и VTKPOS-V2 скорость работы по серийному порту можно изменить.
Время ожидания получения последнего байта после получения первого байта: 8 секунд. (ПО VTKPOS-V1, VTKPOS-V2)
В ПО EftVending – межсимвольный интервал 100мс.
При использовании TCP/IP VMC должен открыть TCP-соединение с IP-адресом и TCP-портом POS. Порт по умолчанию — 62801. Рекомендуемое время ожидания соединения — 15 секунд.
Протокол VTK является общим для семейства устройств Vendotek, но реализация (поддерживаемые команды) может отличаться для разных моделей устройств.
Уровни функциональности, реализованные в разных проектах и на устройствах Vendotek V1,V2,V3,VX, Vendotek VL, VN, Vendotek VT (без экрана) с прикладным ПО Eftvending, VTKPOS-V1 и VTKPOS-V2.
Значения в таблице:
V- функционал поддерживается в данном ПО и на данном терминале
сервисное меню/техподдержка - способ настройки параметров
¶ Обмен сообщениями
¶ Формат сообщений
¶ Порядок обмена сообщениями (по RS-232)
В потоке данных отдельные сообщения выделяются по наличию стартового байта. Началом сообщения считается первый принятый байт со значением 0x1F.
Все оставшиеся байты данного сообщения должны быть получены в течение 8 секунд после получения стартового байта. Если за это время сообщение не пришло полностью, его приём следует прекратить и начать ожидание нового сообщения.
Сообщение приложения содержит набор параметров BER TLV (ISO/IEC 8825-1) с примитивным кодированием. Список параметров зависит от обрабатываемой операции. Неподдерживаемые параметры следует игнорировать, а анализ сообщения следует продолжить.
Каждый параметр имеет следующий формат:
Пример сообщения базового протокола VTK по последовательному каналу связи (шестнадцатеричный дамп) с расшифровкой
1f001d96fb010349444c11143230323630313237543038343035332b30333030977e
IDL: MessageName
OperationNumber: 12
KeepaliveIntervalS: 600
SystemInformation: STATE=READY
Таблицы с расшифровкой параметров, типов сообщений и тегов
¶ Типы сообщений
¶ Состояние ILDE - Начало работы
После загрузки для начала приема платежей необходимо перевести терминал в рабочее состояние - отправить сообщение IDL. Имя сообщения определяет его функцию.
Запрос
'IDL' MessageName
'20260123T094927+0300' LocalTime
1f001d96fb010349444c11143230323630313237543130313130362b303330300fc5
---
Ответ
'IDL' MessageName
'1' OperationNumber
'600' KeepaliveIntervalS
1f000e97fb010349444c03013105023230
В примере обмена сообщениями между ТА и терминалом на картинке содержатся следующие теги
¶ Местное время (тег 11)
(обязателен для VTKPOS-V1, для терминалов EftVending и VTKPOS-V2 необязателен )
Передается в формате ISO 8601 с ограничениями: в данной версии протокола разрешены только представления MMDDThhmmss+xxyy и YYYYMMDDThhmmss-xxyy. Пример: 20210514T105924+0300. Если длина тега превышает 20 байт, все дополнительные байты должны игнорироваться.
Если POS отправляет локальное время, в котором первый байт не равен «2», VMC должен вставлять фактическое локальное время во все сообщения до тех пор пока не получит от терминала IDL без времени или первый байт времени будет равен 2.
Прежде чем отправлять время в POS, VMC должен убедиться что его локальное время синхронизировано с внешним источником.
¶ Тип сообщения (тег 01)
В данном случае - тип сообщения IDL. Таблица с описанием всех сообщений здесь
¶ Номер операции (тег 03)
VMC должен получить номер операции из любого сообщения и сохранить его во временной переменной. POS должен получить номер операции из сообщения VRP/CDP/CRD и сохранить его в энергонезависимой памяти.
Перед отправкой сообщения VRP/CDP/CRD VMC должен увеличить номер операции и сохранить его в той же переменной. После этого VMC должен отправлять это значение во всех сообщениях перед новым запросом VRP/CDP/CRD. И VMC, и POS должны помещать это значение в сообщения INF.
Если POS получил несколько запросов VRP/CDP/CRD или несколько запросов FIN с одним и тем же номером операции, он обрабатывает их как повторы и возвращает предыдущий результат.
¶ Интервал Keepalive (тег 05) ###
Если VMC не получает никаких сообщений в течение 3*Tk+8 секунд, где Tk — интервал keepalive, VMC должен перейти в состояние INACTIVE и должен восстановить значения по умолчанию для переменных интервала keepalive и времени ожидания операции. Если используется протокол TCP/IP, VMC должен закрыть TCP-соединение перед переходом в состояние INACTIVE.
Например, если интервал keepalive составляет 30 секунд, а VMC не получает никаких сообщений в течение 3*30+8=98 секунд, VMC должен перейти в состояние INACTIVE.
¶ Возможные запросы из состояния IDLE
¶ Перевод в состояние DISABLED (DIS)
Запрос
DIS MessageName
'20260123T094927+0300' LocalTime
1f001d96fb010344495311143230323630313237543131303734332b303330308763
---
Ответ
'DIS' MessageName
'1' OperationNumber
'600' KeepaliveIntervalS
1f000e97fb010344495303013105023230
¶ Проведение продажи:
¶ Начало сеанса (STA) (опционально)
Ответ
'STA' MessageName
'1' OperationNumber
'600' KeepaliveIntervalS
1f000a97fb0103535441030131
¶ Запрос проведения продажи (VRP)
Запрос
'VRP' MessageName
'1' OperationNumber
'100' AmountMinorCurrency
1f001196fb010356525003013104053130303030861c
---
Ответ
'VRP' MessageName
'1' OperationNumber
'100' AmountMinorCurrency
1f001197fb010356525003013204053130303030
¶ Сумма с копейками (тег 04)
Посредством суммы в сообщении VRP терминал сообщает о результате транзакции, а VMC о результате выдачи товара или оказания услуги. Ненулевая сумма - операция одобрена, нулевая – в операции отказано.
¶ Возможные варианты из состояния VRP
¶ Запрос завершение операции (FIN)
Запрос
'FIN' MessageName
'1' OperationNumber
'100' AmountMinorCurrency
1f001196fb010346494e0301320405313030303077fd
---
Ответ
'FIN' MessageName
'1' OperationNumber
'100' AmountMinorCurrency
1f001197fb010346494e03013204053130303030
¶ Запрос прерывания операции (ABR)
Запрос
'ABR' MessageName
1f000796fb010341425281b6
¶ Пример обмена сообщениями при успешной безналичной продаже
*пример банковского слипа приведен далее
Важно обратить внимание, что в одном интервале вся операция проходит с одним Operation number. Номер каждой последующей операции инкрементируется
¶ Банковский чек (тег 13)
Банковский чек может быть передан с POS-терминала в ответах VRP и FIN. Если торговый автомат оснащён принтером, VMC может распечатать этот чек. Рекомендуется выбрать для печати чек из ответа VRP. Если VMC отправляет сообщение FIN с альтернативной суммой (не равной сумме VRP), рекомендуется также распечатать чек из ответа FIN.
Символы < LF > (байты 0x0A) в чеке должны обрабатываться как начало новой строки.
В ПО VTKPOS V1 и V2 банковский слип передается в формате json. В терминалах на EftVending в формате ASCII.
¶ Информация о смене состояния терминала - Stage ID ( тег 1C)
Сообщение Stage ID INF это сообщение с информированием ТА о том, что терминал перешел в новое состояние.
¶ Наличная продажа
¶ Частичный возврат/отмена
В рамках протокола VTK реализована опция частичного возврата/отмены (например для заправок или автоматов по розливу воды, когда после покупки часть суммы остается не истраченной и ее нужно вернуть).
В зависимости от реализации на стороне банковского хоста могут поддерживаться функции частичного возврата или частичной отмены.
¶ Последовательность экранов при оплате по разным сценариям
1 – ошибка транзакции
2– успешная транзакция, но ошибка выдачи
3 – успешная транзакция с последующей успешной выдачей товара
¶ Базовый уровень функциональности
¶ Получение хэш PAN (F1)
Хэш PANa банковской карты — это уникальный идентификатор карты, созданный с помощью односторонней криптографической функции. Он позволяет безопасно работать с данными карт для аналитических и защитных целей, не нарушая стандарты безопасности и не подвергая риску держателей карт. Использование "соли" делает этот механизм устойчивым к атакам с предвычислением.
Терминалы Vendotek получают, обрабатывают, но не хранят хэш PANы банковских карт.
¶ Настройка канала связи (F1)
Для получения доступа к сети Интернет терминал может быть настроен на использование одного из сетевых интерфейсов: Wi-Fi, Ethernet, SIM в зависимости от модели терминала.
Чтобы настроить или сменить канал связи:
- ПО EftVending - через TMS или меню терминала (чтобы перейти в Recovery меню терминала, необходимо нажать кнопку В1 после третьего звукового сигнала при старте терминала, далее перейти в раздел Connection (связь), выбрать необходимые настройки и нажать Apply and restart (принять и перезагрузить).
- ПО VTKPOS-V1 при старте терминала трижды коснуться надписей на экране для входа в сервисное меню, далее перейти в раздел Settings (Настройки), далее - Com Settings (настройки связи). В выпадающем окне connection mode выберите необходимый тип связи Internet. (Про транспорт VTK см. раздел Получение терминалом доступа в Интернет по протоколу VTK(F2)
- В ПО VTKPOS-V2 - через TMS или меню терминала (Меню техника -> Настройки -> Настройки сети -> и далее выберите из выпадающего списка необходимый канал связи. (В меню техника можно войти трижды коснувшись надписей на экране при старте терминала, либо по Wi-Fi). Wi-Fi меню поддерживается в VTKPOS-V2 на терминалах VL, VN, VT.
Обмен сообщениями терминала с устройством, предоставляющим доступ в Интернет (модем телеметрии либо внешний контроллер).
Полный список параметров для самостоятельной расшифровки сообщений в этой статье.
¶ Работа с Mifare картами (F1)
Запрос
MFR
3=4,1B=34119B0953DAE6
1f000796fb01034d46523813
---
Ответ
MFR
3=4,1B=34119B0953DAE6
1f001097fb01034d46520301331b04ef8189de
В ПО VTKPOS-V2 терминал может считать UID Mifare-карты, когда он получил команду VRP и ожидает банковскую/ Mifare-карту.
В ПО EftVending терминал отправляет сообщение MFR при прикладывании Mifare после отправки VRP автоматически.
¶ Изменение канала и интерфейса взаимодействия по VTK (F1)
Обмен по VTK с ТА может быть настроен по RS-232 либо по TCP/IP. Изменить настройки обмена:
- EftVending - через TMS (если профиль доступен для редактирования) либо через техподдержку Vendotek
- VTKPOS-V1 при старте послать info /n - для переключения в настроечный режим
- VTKPOS-V2 - через TMS или меню терминала (Меню техника -> Настройки -> Приложение -> Транспорт VTK) (В меню техника можно войти трижды коснувшись надписей на экране при старте терминала либо по Wi-Fi). Wi-Fi меню поддерживается в VTKPOS-V2 на терминалах VL, VN, VT.
¶ Продвинутый уровень функциональности (F2)
¶ Получение терминалом доступа в Интернет по протоколу VTK(F2)
¶ Обращение на сервер TMS - POS Management Data (F2)
Терминалы с ПО VTKPOS-V1 и VTKPOS-V2 могут синхронизироваться с сервером TMS по команде от ТА для:
Примеры запросов и ответов System info
¶ Send Keepalive
Запрос
1f002096fb010349444c11143230323630313237543134313034352b30333030100141e160
---
Ответ
1f001197fb010349444c03013305023230100141
¶ SW Update
Запрос
1f002096fb010349444c11143230323630313237543134313135392b3033303010014c32d1
---
Ответ
1f001197fb010349444c030133050232310014c
¶ Restart
Запрос
1f002096fb010349444c11143230323630313237543134313431302b3033303010015227c9
---
Ответ
1f001197fb010349444c03013305023230100152
¶ Log upload
Запрос
1f002196fb010349444c11143230323630313237543134313234352b3033303010024e5444df
---
Ответ
1f001297fb010349444c0301330502323010024e54
¶ Settlement
Запрос
1f002096fb010349444c11143230323630313237543134313331302b303330301001531e55
---
Ответ
1f001197fb010349444c03013305023230100153
¶ Запрос системной информации ( тег 12) (F2)
Терминалы с ПО VTKPOS-V1, VTKPOS-V2 поддерживают функцию ответа на запрос от VMC своего текущего статуса (System information).
- Варианты ответа на запрос STATUS (возможны комбинации ответов на запрос STATUS, например терминал готов принимать платежи, но в данный момент занят обменом данными через Интернет )
-
READY – терминал готов принимать платежи
-
NOT_READY – терминал не готов принимать платежи по причине:
-
NO_TIME - не получено локальное время от VMC,
-
NO_TMS_CONFIG- нет конфигурации для корректной работы,
-
NO_BANK_CONFIG - нет банковской конфигурации
-
DISABLED – терминал переведен в неактивное состояние по причине:
- DIS_RECEIVED - получено сообщение DIS от VMC,
- IDL_TIMEOUT- превышение таймаута ожидания IDL от VMC
-
BUSY – терминал находится в процессе выполнения задачи:
- CARD_WAIT - ожидание карты,
- IN_SERVICE - терминал находится в сервисном меню.
Примеры (при работе по RS-232)
¶ STATUS
Запрос
1f002596fb010349444c11143230323630313232543132333930302b3033303012065354415455532349
---
Ответ
1f001297fb010349444c030231320503363030120b53544154453d5245414459
¶ POS_PARAMS
- V - версия по
- SN - серийный номер терминала
- TID - банковский идентификатор
- VTK_MODE - режим работы терминала по протоколу VTK
('H=2,V=V3.23,SN=220000000894,TID=220000000894,VTK_MODE=VT2)
Запрос
1f002996fb010349444c11143230323630313232543132343232362b30333030120a504f535f504152414d5358a6
---
Ответ
1f004997fb010349444c030131050232301239483d322c563d56332e32332c534e3d3232303030303030303839342c5449443d3232303030303030303839342c56544b5f4d4f44453d56543
¶ BANK_PARAMS
- PROVIDER - установленный банк эквайер
Запрос
1f002a96fb010349444c11143230323630313232543132333031312b30333030120b42414e4b5f504152414d537ce3
---
Ответ
1f001d97fb010349444c03013305023230120d50524f56494445523d44454d4f
¶ NET_PARAMS
Канал связи для выхода в Интернет (UART_VTK, ETHERNET, WIFI)
Запрос
1f002996fb010349444c11143230323630313232543132323833332b30333030120a4e45545f504152414d530964
---
Ответ
1f001297fb010349444c030231320503363030120f434f4e4e454354494f4e3d57494649
¶ Расширенный уровень функциональности (F3)
¶ Фискализация на стороне терминала (F3)
Терминалы Vendotek с ПО Eftvending и VTKPOS-V2 поддерживают самостоятельное проведение фискализации, передавая данные в облачную онлайн-кассу. В этом режиме терминал отправляет данные о продаже в кассу, а в ответ получает QR-код для отображения на экране терминала ( или по запросу от VMC на экране ТА).
Терминалы, взаимодействующие с ТА по протоколу VTK могут отображать чек в виде QR кода по запросу от Управляющего устройства.
Пример запроса и ответа передачи QR кода в сообщении IDL
Запрос
1=IDL,a=Thank you!,11=20260129T134351+0300
1f002996fb010349444c0a0a5468616e6b20796f752111143230323630313239543133343335312b3033303066bb
---
Ответ
1=IDL,3=3,5=20
1f000e97fb010349444c03013305023230
¶ Работа с Mifare картами по протоколу NFC reader (F3)
Дискриминатор протоколов (прямой порядок байтов)
Протокол NFCReader: 0x96FC — от VMC; 0x97FC — от POS
- Для протокола NFCReader сообщение приложения содержит данные в кодировке TLV согласно спецификации функционального дизайна NFCReader. Поддерживаются не все функции протокола NFCReader. Различные версии POS-терминалов поддерживают разный набор функций.
Команды поддержанные в VTKPOS-V2 из NFCreader:
- Get Version
- Check Hardware
- Wait Card
- Power On Field
- Power Off Field
- Make Beep
- Classic Authenticate
- Classic Authenticate Key
- Classic Write Value
- Classic Read Value
- Classic Increment
- Classic Decrement
- Exchange TPDU
- Send Bytes to SAM
- Get SAM status
- Close SAM
Алгоритм работы с Mifare картой выглядит следующим образом:
- VMC посылает терминалу сообщение "VRP" по протоколу VTK с суммой для оплаты.
- Терминал начинает ожидать карту.
- К антенне терминала подносят Mifare или банковскую карту.
-
Терминал посылает в VMC сообщение "MFR" с UID и типом карты по протоколу VTK:
-
Если VMC поддерживает эту карту, то:
- VMC отвечает терминалу сообщением "MFR" по протоколу VTK.
- Терминал начинает ожидать подключения и сообщений по протоколу NFCREADER на порту 62901.
- После завершения работы с Mifare картой VMC посылает терминалу сообщение "ABR" по протоколу VTK, чтобы завершить сессию оплаты.
-
Если VMC не поддерживает эту карту, то:
- VMC отвечает терминалу сообщением "ABR" по протоколу VTK, чтобы отключить поле и завершить сессию оплаты.
-
Если это банковская карта и нужно списать с нее средства, то:
- VMC отвечает терминалу сообщением "VRP" с суммой для оплаты по протоколу VTK.
- Терминал списывает средства с карты и возвращает результат операции в VMC по протоколу VTK.
-
Если VMC поддерживает эту карту, то:
¶ Оплата по QR коду ( тег 0А) (F3)
ПО EftVending и VTKPOS-V2 поддерживают функцию оплаты по Системе Быстрых Платежей (СБП) – по QR коду. Существует два варианты передачи QR кода для оплаты.
При необходимости, QR код может отображаться не на экране Vendotek (или в случае отсутствия экрана у Vendotek VT),а на экране ТА.
на стороне управляющего устройства, которое присылает Host ID
выбор способа оплаты на экране терминала.
¶ Продажа нескольких позиций (F3)
Возможность покупки нескольких товаров в рамках одной транзакции реализована в ПО EftVending и VTKPOS-V2.
покупка трех товаров Test1 Test3 Test3 по ценам 1,2, 3 соответственно. Данные передаются в формате .csv через знак ; – т.е ProductID;ProductName.
В чеке все товары в рамках одной транзакции отображаются отдельными пунктами с общей итоговой суммой.
¶ Отображение изображение на экране терминала (F3)
ПО VTKPOS-V2 и EftVending поддерживает возможность отображения пользовательских изображений на экране терминала.
Для показа пользовательского экрана в EftVending потребуется отправлять на терминал сообщение IDL со следующим набором тегов (можно отправить в том числе и в ABR при прерывании ожидания карты):
“Image name” (15h) - имя экрана для отображения (при отсутствии тега отображается стартовый экран);
“Display text” (17h) - пользовательский текст для отображения;
“Display time in milliseconds” (14h) - время отображения изображения или текста.
Изображения загружаются на терминал с сервера ТМС силами службы поддержки
POS-терминал может обрабатывать имя изображения из сообщений IDL и VRP/CDP/CRD. Если имя изображения отсутствует или неизвестно, POS-терминал не меняет изображение на дисплее, игнорируя флаги, текст, координаты и цвет.
Если VMC отправляет имя изображения в сообщении IDL, и это имя известно POS-терминалу, POS-терминал отправляет это имя изображения в ответе IDL.
В ПО VTKPOS-V2 изображения для отображения на экране терминала загружаются с сервера ТМС силами службы поддержки.
¶ Расширенный + уровень функциональности (F3+)
¶ Управление процесс проведения сверки с банковским хостом (F3+)
В новой версии ПО и новой версии спецификации протокола VTK есть новое понятие "финансовый день" (Batch ID).
Номер финансового дня можно узнать в каждом сообщении IDL, DIS, VRP и FIN, которое придет от терминала, если в отправленном от управляющего устройства сообщении будет передан новый тег.
Есть опция присылать сообщение INF с новым номером финансового дня, если терминал выполнил сверку с банком и открыл новый финансовый день.
Запрос
1f003096fb010349444c11143230323630313330543134303930332b303330301211534554544c454d454e545f535441545553f650
---
Ответ
1f010349444c03013005023230121c42415443485f49443d33322c434f554e543d302c414d4f554e543d30
¶ Отображение сумм на экране ( F3+)
