Як обрати протокол підключення банківського термінала до Торгсофт: BPOS, PosApi, SSI, JSON та OschadPAY

Коли банківський термінал підключений до Торгсофт, касиру не потрібно вручну набирати на ньому суму покупки: у Торгсофт обирають оплату карткою, програма передає суму на термінал і отримує результат операції. Такий режим називають інтеграцією банківського термінала з касою або касовим суміщенням. 

Підприємці зазвичай запитують, який протокол замовити в банку, чи підійде конкретна модель термінала, що краще для локальної каси або віддаленого сервера, чи потрібна статична IP-адреса та як працювати з кількома ФОП через один термінал. За зверненнями до техпідтримки видно, що основне питання — не знайти «найкращий» протокол, а правильно узгодити між банком, терміналом і Торгсофт один і той самий спосіб підключення.

Що таке протокол банківського термінала

Протокол — це спосіб, за яким Торгсофт і банківський термінал обмінюються даними.

Наприклад, Торгсофт передає терміналу:

• суму до оплати;

• команду на оплату або повернення;

• за потреби — дані мерчанта.

Термінал повертає результат операції та доступні реквізити платежу.

У Торгсофт підтримуються різні способи інтеграції, зокрема BPOS, PosApi, SSIAxECR, SSI_JSON, WebSocket/JSON, JSON (COM/TCP), OschadPAY, BankCore, QRPayMono та інші актуальні варіанти. Для частини протоколів банк має надати драйвери або бібліотеки.

 Важливо не плутати три речі:

• протокол — як Торгсофт і термінал обмінюються командами;

• підключення — як фізично або через мережу вони з'єднані: USB/COM, Ethernet, Wi-Fi;

• мерчант — банківський ідентифікатор торговця, пов'язаний із конкретним ФОП і рахунком.

Тобто термінал може працювати через Wi-Fi, але при цьому використовувати BPOS або JSON. Wi-Fi — це не протокол еквайрингу.

Головне правило вибору

Не потрібно самостійно обирати BPOS, PosApi або JSON тільки за назвою банку чи моделлю термінала.

Спочатку потрібно дізнатися у банку:

1. Чи може цей термінал працювати в режимі інтеграції з касою.

2. Який саме протокол банк може налаштувати на цьому терміналі.

3. Як термінал буде підключений: USB/COM, Ethernet або Wi-Fi.

4. Які драйвери й бібліотеки банк надає для інтеграції.

5. Чи налаштовані потрібні мерчанти для оплати та повернення.

Після цього в Торгсофт вибирається відповідний протокол.

Це не формальність. У техпідтримці був випадок із Newland N950 від ПриватБанку: сам термінал був справний, але підключити його до Торгсофт не вдалося, бо банк не налаштував пристрій на роботу в режимі касового суміщення. Клієнту рекомендували звернутися до банку та налаштувати JSON через Wi-Fi.

Отже, самої сумісної моделі термінала недостатньо. На ньому має бути правильно налаштований потрібний режим.

Коротко: чим відрізняються основні варіанти

Немає сенсу порівнювати їх за принципом «цей кращий, цей гірший». Потрібен той варіант, який одночасно підтримують банк, конкретне обладнання та Торгсофт.

BPOS і BPOS1

Для BPOS банк надає необхідні драйвери та бібліотеку ECRCommX.dll. Торгсофт підтримує цей протокол для інтеграції з банківськими терміналами.

У BPOS є важлива особливість: на практиці зустрічаються два режими.

Це має значення в ситуації, коли на терміналі оплата завершилася, але програма через збій зв'язку не отримала або не підтвердила результат. В інструкції з підключення POS-терміналів ПриватБанку описано саме таку різницю між BPOS і BPOS1.

Підприємцю не потрібно самостійно «перемикати BPOS на BPOS1». Якщо в роботі виникають розбіжності між результатом на терміналі та касою, потрібно перевірити з банком, який режим налаштований.

У зверненнях до техпідтримки Торгсофт BPOS також зустрічається при мережевому підключенні Ingenico через Ethernet: налаштовувався порт, резервувалася IP-адреса термінала та перевірявся зв'язок.

Коли обирати BPOS

Якщо банк повідомляє, що конкретний термінал для касового суміщення працює через BPOS, і надає потрібні компоненти для підключення, цей протокол можна використовувати в Торгсофт.

Якщо каса працює віддалено через RDP, варто одразу повідомити про це банку і техпідтримці Торгсофт: для такого сценарію важливими стають не тільки протокол, а й мережеве підключення та коректне підтвердження операцій.

PosApi

У Торгсофт PosApi підтримується як окремий протокол. Для нього потрібні драйвер термінала та бібліотека Posapi.dll, які отримують для відповідного банківського обладнання. В актуальній довідці Торгсофт є, зокрема, окрема інструкція для Verifone VX520 Райффайзен Банку.

Для підприємця логіка проста: банк каже, що термінал працює з касою через PosApi → банк надає потрібне програмне забезпечення → у Торгсофт налаштовується PosApi.

Немає потреби обирати PosApi тільки тому, що термінал певного бренду. В актуальній довідці Торгсофт окремо зазначено, що поле з типом банківського термінала має допоміжний характер, а на алгоритм роботи впливає саме вибраний протокол.

SSI: SSIAxECR і SSI_JSON

У Торгсофт є два окремі варіанти:

• SSIAxECR;

• SSI_JSON.

Їх не слід сприймати як одну взаємозамінну настройку.

Наприклад, у довідці Торгсофт є окрема інструкція SSIAxECR для Verifone X990, а SSI_JSON налаштовується як інший протокол.

Тому при отриманні термінала недостатньо запитати у банку: «У нас SSI?». Потрібно уточнити точну назву протоколу, який налаштований на пристрої.

Що запитати у банку

Достатньо сформулювати так: "Термінал потрібно інтегрувати з касовою програмою Торгсофт. Уточніть, будь ласка, який протокол SSI налаштований: SSIAxECR чи SSI_JSON, і надайте параметри для підключення".

Це набагато корисніше, ніж самостійно підбирати налаштування в програмі.

JSON: назва одна, варіантів кілька

З JSON підприємці найчастіше плутаються через те, що JSON — це не одна-єдина настройка термінала.

У Торгсофт є, зокрема:

• WebSocket/JSON;

• JSON (COM/TCP).

Для WebSocket/JSON у довідці передбачені окремі компоненти для мережевого та USB/COM-підключення. Для JSON (COM/TCP) використовується інший спосіб обміну.

Тому відповідь банку «термінал працює по JSON» ще недостатня. Потрібно уточнити:

• який саме варіант JSON;

• USB/COM чи мережеве підключення;

• якщо через мережу — IP-адресу і порт;

• чи вже переведений термінал банком у режим роботи з касою.

Це підтверджується практикою підтримки. З Newland N950 від ПриватБанку зустрічалися як Wi-Fi-підключення в локальній мережі, так і інші варіанти суміщення. Техпідтримка перевіряла IP-адресу, налаштування роутера і зв'язок із терміналом.

Тому формула «Newland = JSON = будь-які налаштування підійдуть» неправильна. Потрібно знати, як саме цей конкретний пристрій налаштований банком.

OschadPAY: окремий сценарій зі смартфоном

OschadPAY відрізняється від BPOS, PosApi та інших варіантів для звичайних POS-терміналів.

У Торгсофт інтеграцію з OschadPAY додано для приймання безконтактних платежів через смартфон. Телефон із відповідною підтримкою використовується для приймання карткової оплати без окремого стаціонарного POS-термінала.

Тому OschadPAY має сенс розглядати, якщо потрібен саме такий сценарій, наприклад для мобільної каси або торгівлі, де незручно встановлювати окремий банківський термінал.

Якщо магазин отримав від Ощадбанку звичайний POS-термінал, не потрібно автоматично вибирати OschadPAY. Спочатку слід уточнити у банку, який спосіб касового суміщення використовується саме для виданого обладнання.

USB, Ethernet чи Wi-Fi

Протокол і спосіб підключення потрібно обирати разом.

Якщо Торгсофт працює на комп'ютері біля каси

USB/COM може бути зручним, якщо саме таке підключення передбачив банк для цього термінала.

У такому сценарії немає окремого мережевого маршруту між програмою та терміналом.

Якщо термінал працює через Ethernet або Wi-Fi

Термінал має власну IP-адресу в мережі. Важливо, щоб вона не змінювалася несподівано.

У реальних зверненнях техпідтримка:

• перевіряє IP термінала;

• резервує адресу в роутері;

• перевіряє потрібний порт;

• перевіряє доступність пристрою;

• після цього проводить тестову оплату.

Якщо роутер видав терміналу іншу IP-адресу, Торгсофт може просто перестати знаходити його, хоча сам POS продовжить працювати як окремий банківський термінал.

Що змінюється при роботі через віддалений сервер або RDP

Тут важливо зрозуміти розташування двох пристроїв:

• POS-термінал фізично стоїть у магазині;

• Торгсофт може працювати на сервері в іншому місці.

Отже, сервер повинен мати можливість передати команду на термінал у магазині та отримати відповідь.

Через це при віддаленій роботі потрібно перевіряти:

• який протокол використовується;

• чи підтримує він обраний мережевий сценарій;

• IP-адресу термінала;

• потрібний порт;

• налаштування роутера та firewall;

• доступність термінала із середовища, де працює Торгсофт.

У контактах техпідтримки є випадки, коли зв'язку з POS не було саме через мережеві параметри або зміну IP. Є також випадок, коли для роботи магазину знадобилася статична IP-адреса.

Але правило «для будь-якого RDP обов'язково купити зовнішню статичну IP і зробити Port Forwarding» некоректне. Це залежить від того, як побудована конкретна мережа. Спочатку потрібно визначити схему підключення.

Якщо на одному терміналі працює кілька ФОП

Протокол сам по собі це питання не вирішує.

Для кожного підприємця потрібно правильно зв'язати: ФОП → розрахунковий рахунок → мерчант → банківський термінал.

У зверненнях до техпідтримки регулярно зустрічаються:

• додавання нового ФОП;

• перевірка його наявності в терміналі;

• додавання відповідного мерчанта в Торгсофт;

• налаштування зв'язків із рахунками;

• перевірка оплати та повернення.

Якщо банк не додав потрібного мерчанта на термінал, налаштувати його тільки в Торгсофт недостатньо.

Це важливо перевірити до початку роботи каси, а не після того, як перший платіж потрапив на рахунок іншого ФОП.

Чому термінал підключився, але оплата все одно працює неправильно

Факт, що Торгсофт бачить термінал, означає тільки те, що встановлено зв'язок.

Після підключення можуть залишитися інші питання:

• вибраний неправильний мерчант;

• термінал налаштований банком на інший режим;

• програма і POS по-різному визначили результат операції;

• оплата проходить, а повернення не налаштоване;

• після зміни роутера термінал отримав іншу IP-адресу.

Тому після налаштування потрібно перевіряти не тільки зв'язок, а весь цикл роботи.

Як правильно перевірити термінал після підключення

Після налаштування варто пройти короткий тест.

1. Перевірити зв'язок із терміналом.

2. Провести невелику тестову оплату.

3. Перевірити, що сума передалася з Торгсофт автоматично.

4. Перевірити Merchant ID і потрібного ФОП.

5. Переконатися, що продаж правильно завершився в Торгсофт.

6. Перевірити фіскальний чек, якщо використовується РРО/пРРО.

7. Провести тестове повернення.

8. Переконатися, що гроші та документи відобразилися правильно.

Саме тестову оплату, перевірку мерчанта і тестове повернення база знань Торгсофт рекомендує після налаштування банківського термінала.

Це дозволяє одразу знайти ситуацію, коли продаж працює, а повернення — ні.

Що сказати банку перед отриманням термінала

Підприємцю не обов'язково знати всі технічні відмінності BPOS, SSI або JSON.

Банку достатньо передати конкретну задачу: "Потрібен банківський термінал для інтеграції з програмою Торгсофт у режимі касового суміщення. Підкажіть, який протокол інтеграції доступний для цієї моделі та банку, яким способом термінал підключається до каси та які драйвери, бібліотеки й параметри потрібно отримати для підключення".

Якщо Торгсофт працює через віддалений сервер, це потрібно сказати одразу.

Якщо на одному терміналі працюватимуть кілька ФОП, це також потрібно погодити з банком до налаштування.

Як обрати протокол: практична схема

◆ Якщо термінал уже є, спочатку дізнайтеся у банку, який протокол касового суміщення на ньому налаштований. Після цього звірте його з підтримуваними протоколами Торгсофт.

◆ Якщо термінал тільки замовляєте, повідомте банку, що потрібна інтеграція з Торгсофт, і уточніть доступний протокол та спосіб підключення.

◆ Якщо Торгсофт працює на віддаленому сервері, до вибору протоколу додайте перевірку мережевого доступу до POS.

◆ Якщо працює кілька ФОП, окремо погодьте з банком мерчанти для кожного підприємства.

◆ Якщо потрібна оплата смартфоном без окремого POS, можна розглядати OschadPAY як окремий сценарій.

Головне

Не потрібно обирати BPOS, PosApi, SSI або JSON за принципом «який сучасніший». Для магазину правильний протокол — той, який банк налаштував на конкретному терміналі, Торгсофт підтримує, а обрана схема підключення дозволяє стабільно передавати оплату й отримувати результат.

Перед запуском каси достатньо перевірити п'ять речей: протокол → спосіб підключення → IP/порт за потреби → мерчант → тестова оплата і повернення.

Саме ці пункти найчастіше визначають, чи буде інтеграція працювати коректно в щоденній торгівлі.