¶ Загальна інформація перед початком налаштування
Для того щоб мати можливість прийняти оплату від клієнта банківською карткою та друкувати фіскальні чеки за допомогою терміналу необхідно:
-щоб на терміналі виробником/банком було встановлено платіжний застосунок(або кілька застосунків від різних банків на різних портах, за потреби) для проведення операцій.
-підключений протокол SSI JSON для роботи з зовнішними системами.
Доступні термінали для підключення:
- термінали Newland серії SP,
- термінали unattended для систем самообслуговання Newland U1000,
- Android термінали Verifone X990 всіх формфакторів,
а також Андроїд терміналами інших виробників, з програмним забезпеченням SSI та протоколом SSI JSON на них.
Банки еквайри платіжні застосунки яких можуть бути налаштовані на перерахованих терміналах станом на 28.08.2024:
- Ощадбанк
- Райффайзен банк
- ПУМБ
- А-Банк
- Monobank
- Таскомбанк
- КІБ
- Восток Банк
- Південний Банк
- Укрексімбанк
Деталі уточнити можна у виробника або банку про доступність.
Після підключення терміналу до застосунку можна проводити розрахунок з покупцями формуючи чеки як через вебкабінет Вчасно.Каса так і з вашої облікової системи яка уже працює з ПРРО Вчасно.Каса.
Друкувати чеки, формуючи їх через вебкабінет Вчасно.Каса використовуючи даний термінал наразі не можливо. Друк доступний тільки при роботі ПРРО безпосередньо в Device Manager.
Для підключення потрібно обрати інтерфейс через який банківський термінал зможе отримувати інформацію для проведення розрахунків:
- По мережі (
Ethernet/wi-fi) - На терміналі має бути налаштовано даний тип з'єднання. Додатково потрібно підключити термінал до маршрутизатора Ethernet кабелем, якщо термінал має відповідний порт, або підключити термінал до мережі wi-fi якщо термінал дозволяє підключення по wi-fi.
Можливість підключити термінал по USB/COM наразі не реалізована.
За потреби банк може налаштувати на одному терміналі кілька торгівців (мерчантів) в межах одного банку та кілька платіжних застосунків від різних банків.
- у випадку мультимерчанта через один фізичний термінал можна проводити розрахунки по кількох ФОП або юр. особах.
- у випадку різних застосунків банків, кожен застосунок налаштовується на терміналі на окремому порті по якому(якщо застосунок один порт за замовчуванням 3000) в device manager можна визначити через який застосунок буде відбуватись оплата.
Device Manager підтримує обидві можливості роботи. У випадку різних застосунків банків, потрібно для роботи із кожним застосунком створювати окремий термінал в device manager та вказувати потрібний порт застосунку на терміналі.
Налаштування будуть описані нижче.
¶ Підключення терміналу в застосунок
Перед початком налаштування необхідно встановити device manager на ваш пристрій. Інструкція.
-
Для створення терміналу як пристрою в застосунку переходимо на сторінку підключення пристроїв.
За посиланням http://localhost:3939/dm/dashboard або можна перейти через інтерфейс ПРРО
-
Натискаємо
ДОДАТИ ПРИСТРІЙабоДОДАТИ НОВИЙ ПРИСТРІЙ
-
На першому кроці потрібно вказати назву для терміналу (на власний розсуд, але назва терміналу має бути унікальна в розрізі всіх пристроїв включаючи створені ПРРО), обрати тип пристрою
Банківський терміналта натиснутиНАСТУПНИЙ КРОК
Назву терміналу наполегливо рекомендуємо вказувати без пробілів та спеціальних символів типу знаку табуляції(
\t) чи лапок.
- Далі необхідно встановити налаштування для вашого терміналу.
- В пункті
Оберіть банквибираєтеІнший банк - В пункті
Оберіть протоколвибираєтеSSI JSON - В пункті
Назва банкувкажіть назву банку через який будуть проводитись оплати, цей пункт не є обов'язковим так як програмне забезпечення терміналу самостійно визначає та повертає у відповідь назву банку.
-
В пункті
Оберіть інтерфейс підключеннязалишаєтеEthernet- у випадку підключення терміналу через мережу. -
Після вибору потрібного інтерфейсу потрібно вказати дані для підключення, або натиснути кнопку "Пошук".
Після натиснення на кнопку"Пошук"або"Розширений пошук"додаток автоматично спробує знайти ваш термінал, та заповнить всі необхідні дані, якщо пристрій доступний.
Важливо! Якщо на терміналі немає платіжного застосунку, він не налаштований або порт застосунку не 3000 - автоматичний пошук термінал не знайде, при цьому якщо відомо IP адресу терміналу(порт не потрібно) можна друкувати чеки через термінал при наявності будь якого платіжного застосунку.
Якщо пошук не знайшов ваш термінал - спробуйте вказати дані вручну:
Якщо було обрано інтерфейс Ethernet
Потрібно вказати IP адресу терміналу. Порт буде встановлено за замовчуванням 3000, у випадку якщо порт терміналу відрізняється від стандартного його можна вказати через : після IP адресу, наприклад 192.168.1.103:2000
Приклад перегляду IP адреси через сайт маршрутизатора tp-link(http://tplinkwifi.net/#networkMap) для стаціонарних терміналів. Можливо також здійснити пошук ІР адресу терміналу по МАС термінала в налаштуваннях роутера. МАС адрес може бути вказано на самому терміналі або можна уточнити у банку.
Якщо термінал відсутній в списку але ethernet кабель підключено - це означає що термінал не може працювати через Ethernet. Потрібно звернутись в банк для уточнення деталей і налаштування.
Як видно з фото вище даний термінал з MAC 54-65-03-8E-FA-84 має ip адресу 192.168.1.101 яку потрібно вказати в додатку.
Також рекомендовано закріпити за терміналом фіксовану адресу на маршрутизаторі щоб вона не змінювалась із перезавантаженням терміналу і не потрібно було вказувати нову адресу.
На різних моделях маршрутизаторів налаштування можуть відрізнятись.
Приклад встановлення налаштування через сайт маршрутизатора tp-link(http://tplinkwifi.net/#networkMap)
- З головної переходимо на вкладку
Додатково - Вибираємо пункт
Безпека, підпунктIP та MAC Прив'язка - Вмикаємо налаштування
IP та MAC Прив'язка - Шукаємо в списку пристроїв термінал та вмикаємо
Пов'язати - Знизу екрану буде відображено текст "Операція успішна"
- Після заповнення всіх вищевказаних полів натискаєте
СТВОРИТИ
Приклад заповнення для Ethernet:
¶ Перевірка роботи терміналу
-
Після створення терміналу відобразиться сторінка його налаштування.
Для друку на терміналі додатковово налаштовувати нічого не потрібно, в device manager було автоматично встановлено налаштування для коректного друку. -
Для перевірки коректності роботи друку можна натиснути
Тест друку.
Якщо термінал налаштовано коректно, на терміналі надрукується невеликий тестовий текст.
У разі помилки - потрібно перевірити коректність введених даних, а саме IP адреси терміналу. -
Для перевірки коректності підключення терміналу та роботи платіжного застосунку можна натиснути
Перевірити зв'язок з терміналом. Буде виконано спробу з'єднатись з терміналом.
Якщо термінал налаштовано коректно, внизу екрану відобразиться повідомлення:
Зв'язок з терміналом встановлено
У разі помилки - потрібно перевірити коректність введених даних, а саме IP адреси та порту терміналу
Якщо перевірка зв'язку виконана успішно та тестовий друк працює - налаштування завершено і термінал готовий до роботи.
¶ Підключення до облікової системи
Після завершення налаштування терміналу в додатку можна підключити його для роботи:
- Якщо фіскалізація чеків здійснюється через вебкабінет Вчасно.Каса інформацію по його підключенню можна знайти за посиланням (
Крок 3. Синхронізація терміналу з кабінетом Вчасно Каса):
- Якщо фіскалізація чеків здійснюється через вашу облікову систему доступно 3 способи для роботи залежно від того як налаштована взаємодія розробниками облікової системи.
1 - Через пакетний режим (підключення терміналу до 1С або до іншої облікової системи):
Додатково при налаштуванні пакетного режиму потрібно обрати термінал як принтер так і термінал у списках якщо потрібно і друкувати чеки і проводити оплати. Також обов'язково вказати код мерчанта, його можна перевірити на сторінці налаштування терміналу натиснувши на "ОТРИМАТИ СПИСОК МЕРЧАНТІВ".
Приклад:
2 - Через режим фіскалізації з друком якщо термінал буде використовуватись лише як принтер.
3 - Інтеграція з терміналами через API: В даному випадку потрібно уточнити в розробників облікової системи які налаштування потрібно виконати.
¶ Робота з помилками
В даному розділі описано можливі помилки при налаштування та роботі з терміналами що використовують протокол SSI JSON та способи їх вирішення.
¶ Помилки при підключення/налаштуванні терміналу
- У випадку якщо термінал недоступний по IP адресу та порту:
Помилка при з'єднанні за вказаною адресою: 192.168.1.108
Буде ip адреса яка виставлена в налаштуваннях терміналу в ДМ.
Рішення: При отриманні даної помилки потрібно перевірити коректність введення IP адреси терміналу та порту на якому працює платіжний застосунок якщо порт не 3000. Скоріше за все адрес або порт вказано некоректно.
Якщо все перевірено, але помилка повторюється, за деталями та вирішенням помилки рекомендовано звернутись до виробника терміналу або банку.
¶ Додаткова інформація по організації взаємодії з терміналом
В розділі зібрана технічна інформація по роботі з терміналом. Даний розділ рекомендований для ознайомлення технічним спеціалістам та розробникам які безпосередньо будуть налаштовувати роботу терміналу і взаємодію з ним через Device Manager
¶ Принтер всередині терміналу.
- Принт сервіс працює на окремому порту в терміналі, його вказувати не потрібно в налаштуваннях, він завжди сталий. В налаштуваннях підключення терміналу потрібно вказати саме порт платіжного застосунку.
- Термінал може повноцінно замінити принтер чеків, тобто він може друкувати всю ту ж саму інформацію що і звичайний чековий принтер. Наприклад окрім чеків можна через службовий звіт (
"task": 5) по ПРРО виконавши його в пакетному режимі чи через ендпоінт/dm/execute-prnз підключеним терміналом друкувати будь який текст чи QR коли чи ШК. - Друк завжди відбувається під 58мм папір (32 символи в 1 рядок). Друк завжди відбувається картинкою яку ДМ формує автоматично перед відправкою. Без обмежень по довжині. Додаткові налаштування друку наразі не можливі, всі налаштування виставляються автоматично при створенні пристрою.
- Таймаут для друку 8 секунд. Якщо чек було успішно фіскалізовано, але принт сервіс терміналу не відповідає протягом цього часу - при роботі в пакетному режимі чи через ендпоінт
/dm/execute-prnбуде повернуто в json відповідіinfo.isprint0 та повернуто відповідь про успішну фіскалізацію чеку(resбуде 0).
¶ Робота з платіжним застосунком
- Підтримувані завдання в протоколі SSI JSON описані за посиланням:
- Підтримувані завдання
Інші операції, які не перераховані, будуть розглядатись на допрацювання після звернень на техпідтримку Вчасно.Каса.
-
Обов'язково при запитах на термінал потрібно вказати кореткний номер мерчанта. При роботі в пакетному режимі номер вказується в налаштуваннях пакетного режиму, при реалізації API для роботи з терміналами - значення має бути передано в кожному запиті в
pay.merch. -
Всі запити на термінал(успішні транзакції та запити помилками) додатково зберігаються в deivce manager. Наразі є можливість отримати останню успішну операцію або останню операцію не залежно від статусу через
/dm/lasttransaction. Інформація по операцію отримуєтсья з БД ДМ-а.
При реалізації роботи з терміналом через API роботи з терміналами, а не через пакетний режим є додатковий функціонал, майже аналогічно ПРРО, для роботи в транзакційному режимі.
Для цього в запиті має бути переданоtransaction_idтаtransaction_search, по transaction_id буде виконуватись синхронізація по операціям на термінал. Деталі знаходяться в описі API
Реалізація даного фукнціоналу з боку облікової системи забезпечує 100% стабільність роботи та запобігає дублюванню в разі неотримання відповіді обліковою системою на запит.
- Рекомендований таймаут запиту до терміналу 4хв 10 секунд.
Таймаут комунікації ДМ з терміналом2хв. Якщо термінал оброблює операцію довше як 2хв запускається автоматичний механізм вирішення колізій, також цей механізм запускається в разі обриву зв'язку з терміналом при очікуванні відповіді.
Таймаут на рішення колізії2хвдодатково.
При рішенні колізії якщо попередня операція завершена - ДМ поверне її статус отриманий від терміналу(успіх + дані по операціх або помилку).
Якщо операція не завершена - ДМ буде очікувати зміну статусу на "завершена" в самому терміналі.
Тільки після автоматичного рішення колізії - ДМ поверне відповідь на оригінальний запит.
Така схема розроблена для уникнення розбіжностей по операціям в терміналі, в ДМ і в обліковій системі.
- Додатково є можливість запитувати статус останньої операції з терміналу за допомогою
"task":17. За допомогою цього завдання можна додатково синхронізовувати дані по останній операції на терміналі і в обліковій системі.