¶ Загальна інформація
Device Manager (далі ДМ) окрім формування фіскальних чеків та їх друку на підключений принтер підтримує також можливість примайти оплати за допомогою терміналу.
Перелік доступних способів прийняти оплату картою поповнився можливістю підключення терміналу у смартфоні.
Далі розповідаємо як це працює, які є можливості та як налаштувати і прийняти першу оплату.
¶ Як це працює та доступні можливості
Процес проведення оплати/повернення виглядає так:
- Облікова чи POS система надсилає API запит на Device Manager.
- Device Manager створює оплату чи повернення за допомогою платіжного застосунку банку.
- Покупець підносить картку або свій пристрій (смартфон, годинник, фітнес браслет) з NFC до вашого.
- По завершенню оплати ДМ повертає відповідь обліковій системі із даними про операцію або формує одразу фіскальний чек (залежить від схеми роботи).
Як результат - оплата проведена, чек сформовано без потреби вручну окремо вводити суму в платіжному застосунку і окремо проводити чек.
Які можливості відкриває використання ДМ разом з терміналом у смартфоні:
- При використання облікової чи касової програми на самому Android пристрої з NFC таким способом можна звільнити робоче місце від класичного терміналу замінивши його терміналом і смартфоні.
- У разі роботи на комп'ютері при використанні касової чи облікової програми додатково можна встановити ДМ на мобільний пристрій і використовувати ваш телефон чи планшет як повноцінна заміна терміналу.
- Не залежно від способу роботи при використанні термінала в смартфоні немає щомісячної орендної плати, навідміну від класичних чи android POS терміналів.
¶ Способи роботи
Для роботи доступно кілька способів. Використовувати той чи інший спосіб ви можете на власний розсуд.
Для кращого розуміння порівняємо схеми із класичною схемою підключення POS терміналу до ПК.
Класична схема:
З облікова система відправляє API запити (на оплату, фіскалізацію та друк) на локально встановлений ДМ на пристрої, POS термінал та принтер, при цьому, може бути підключено як до облікової програми так і напряму в ДМ.
- Використання додаткового Device Manager на Android пристрої з терміналом у смартфоні як заміна класичного терміналу при формуванні чеків з вашого комп'ютера.
При використанні даної схеми у вас буде 2 екземпляри Device Manager, один на вашому комп'ютері, а інший на Android мобільному пристрої.
На комп'ютері буде налаштовано ПРРО та принтер (за потреби), а на телефоні лише tap2phone або термінал у смартфоні.
В такому разі коли покупець розраховується картою - облікова система відправляє API запит на оплату на Device Manager на телефоні, після завершення оплати у відповідь на запит отримує дані про операцію та відправляє запит на Device Manager на пк на фіскалізацію чеку уже із даними про операцію та його друку після фіскалізації.
Так як даний варіант роботи передбачає з'єднання по локальній мережі комп'ютера з мобільним Device Manager, можливі проблеми зі зміною динамічної IP адреси пристрою після його перепідключення до wi-fi мережі, а також це унеможливлює відправку API запитів на телефон за відсутності wi-fi.
Щоб вирішити ці "моменти" можливий альтернативний варіант підключення до мобільного Device Manager
При використанні даної схеми у вас так само буде 2 екземпляри Device Manager, один на вашому комп'ютері, а інший на Android мобільному пристрої, проте в такому разі коли покупець розраховується картою - облікова система відправляє API запит на оплату на Device Manager на телефоні через кабінет Вчасно.Каса.
В такому випадку зміна IP мобільного пристрою чи відсутність wi-fi не повпливають на роботу. Головне щоб ПК був підключений до інтернету за допомогою кабелю та був наявний мобільний інтернет на телефоні.
Деталі по налаштуванню і роботі по даній схемі:
- Використання Device Manager на Android пристрої як основного разом з ПРРО та принтером (опціонально) з вашої облікової чи касової програми на цьому ж Android пристрої.
При використанні даної схеми у вас буде лише один Device Manager, на мобільному пристрої, комунікацію з яким по API здійснює облікова програма. Коли покупець розраховується картою - облікова система відправляє API запит на оплату на Device Manager (або одразу відправляє запит на фіскалізацію чеку в пакетному режимі) і після завершення оплати формується чек.
¶ Кроки до початку роботи
Звертаємо увагу що наразі підтримується підключення лише терміналу у смартфоні від Приватбанку. Рішення від інших банків будуть додані згодом.
Щоб почати роботу потрібно:
-
Замовити термінал у смартфоні у Приватбанку. Обов'язково створити магазин, касирів та надати доступ касирам до потрібного магазину.
Інструкція з авторизації розміщена на сайті Приватбанку. -
Виконати налаштування терміналу у смартфоні у кабінеті Вчасно.Каса на вкладці Еквайринг.
-
Після налаштування терміналу у смартфоні потрібно сформувати та скопіювати його токен.
-
Далі необхідно встановити Device Manager на ваш телефон чи планшет.
-
Одразу після запуску потрібно надати додаткові дозволи для застосунку:
Наразі при запуску всі дозволи одразу запитуватись не будуть, вони були перенесені у окремий пунктДозволизліва зверху.
По відкриттю даного розділу буде відображено перелік необхідних дозволів.
Потрібно надати перші 3, а саме:
Робота застосунку у фоновому режиміСповіщенняВідображення поверх інших застосунків
Звертаємо увагу що дозвіл на Сповіщення та Відображення поверх інших застосунків на старіших версіях Android надаються системою автоматично без додаткових дій.
-
Після того як всі дозволи були надані для створення терміналу у смартфоні переходимо на сторінку підключення пристроїв.
За посиланнямhttp://localhost:3939/dm/dashboard(у разі налаштування через браузер на мобільному пристрої) або можна перейти через інтерфейс ПРРО
-
Натискаємо
ДОДАТИ НОВИЙ ПРИСТРІЙабо на знак+зверху справа. -
У вікні вводимо унікальну назву для вашого терміналу у смартфоні яка буде використовуватись для відправки запитів на оплату. Рекомендовано використовувати назву без пробілів та спец символів. Далі обираємо тип "Термінал у смартфоні" і натискаємо
НАСТУПНИЙ КРОК
-
У поле "Токен терміналу у смартфоні" потрібно додати скопійований токен у кабінеті Вчасно.Каса на вкладці "Еквайринг" та натиснути "Створити".
-
Якщо вказано унікальну назву та токен вказано коректно, буде додано термінал у смартфоні.
Після відкриття сторінки з налаштуваннями можна на даному екрані через "провести операцію по терміналу" здійснити тестову оплату.
Налаштування завершено. Можна проводити оплати.
¶ Прийом оплат та особливості роботи при інтеграції
Важливо!
- Перед прийомом оплат переконайтесь що:
- Ви авторизувались та налаштували платіжний застосунок банку. Інструкція з авторизації розміщена на сайті Приватбанку.
- На пристрої увімкнено
NFCтадоступ до розташування або геолокації. - На пристрої наявний інтернет (мобільний або wi-fi).
- Якщо адміністратори вашої мережі обмежують доступ до сторонніх ресурсів обов'язково перевірте чи немає мережевих блокувань доступу з мобільного пристрою до
kasa.vchasno.uaпо порту 443. Якщо блокування наявні - їх потрібно зняти.
- Доступні операції при роботі за допомогою терміналу у смартфоні:
pkg- завдання доступно в пакетному режимі. Якщо помітки немає - завдання доступно лише при окремому запиті на термінал.
- Оплата (
"task": 1) +pkg(чек на продаж по ПРРО); - Повернення (
"task": 2) +pkg(чек на повернення по ПРРО); - Скасування операції (
"task": 3) +pkg(чек на повернення по ПРРО); - Отримання статусу та даних раніше проведеної операції по терміналу (
"task": 17).
- Структура запитів і відповіді при роботі з tap2phone практично не відрізняється від процесу роботи зі звичайними терміналами, за виключенням тощо що в запиті на оплату не потрібно передавати номер мерчанту, а в запиті на повернення потрібно вказувати не RRN або код авторизації, а унікальний ідентифікатор транзакції що формує Приватбанк який повертаєься у відповіді в
info.cancelid
Приклад запиту на оплату ("task": 1)
{
"source": "API",
"device": "Privat",
"type": 3,
"pay": {
"task": 1,
"sum": 10.23
}
}
Приклад відповіді на успішну оплату:
{
"transaction_id": "ee52c2ba-1844-4ac7-adec-bdc3597575fc",
"transaction_search": 0,
"info": {
"dt": "20251219145326",
"termid": "M1330I00",
"bankid": "M1330I00",
"bankname": "Приватбанк",
"payid": "420220",
"cancelid": "PAX694566e69ec6d3.09137775",
"refundid": "106064054534",
"cardmask": "4394********0993",
"paysys": "Visa",
"sum": 10.23,
"discount": 0.0,
"sumcash": 0.0,
"curr": "ГРН",
"restxt": "",
"sliptxt": "",
"isprint": 0,
"devinfo": "",
"deb_amount": 0.0,
"deb_num": 0,
"cred_amount": 0.0,
"cred_num": 0,
"canc_amount": 0.0,
"canc_num": 0,
"tx_num": 0,
"receipt": "",
"hstFld63Sf89": "",
"merch": "M1330I00",
"submerch": "",
"reference": "",
"purchase_dt": "20251219145326",
"pan": "",
"acquirerid": "",
"agreementNum": "",
"scenario_data": "",
"transaction_id": "ee52c2ba-1844-4ac7-adec-bdc3597575fc",
"oper_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9LnsiY2xpZW50X2lkIjoiMTExMSIsImludGVncmF0b3JfaWQiOiIxMTExIiwib3BlcmF0aW9uIjoicGF5IiwiZXhwIjoxMTExLCJhbW91bnQiOjEsImhhc2giOiIzYzY4MTExMTE2M2M1ZjFhNmQ0MTNhMmE2ZDA2NmVmZTljNGU5OGE5NGU1MTgiLCJwdXJwb3NlIjoiIn0unZrld4TeVLNfgYhfTGBpD0nXNHyWwJQJBuKmlbkbyhM",
"commission": 0.0
},
"ver": 6,
"resp_ver": 4,
"source": "",
"device": "Privat",
"tag": "",
"task_status": 1,
"type": 3.0,
"task": 1.0,
"dt": "20251219165339010",
"res": 0,
"res_action": 0,
"errortxt": "",
"aq_errortxt": "",
"warnings": []
}
Приклад запиту на повернення ("task": 2)
Зверніть увагу що в значення ключа refundid передається унікальний ідентифікатор операції на стороні Приватбанку, а не "rrn" чи "код авторизації" операції оплати. За потреби зробити часткове повернення в ключ "sum" передається частина оригінальної суми.
{
"source": "API",
"device": "Privat",
"type": 3,
"pay": {
"task": 1,
"sum": 10.23,
"refundid": "PAX694566e69ec6d3.09137775"
}
}
Приклад відповіді на успішне повернення:
{
"transaction_id": "52a27da5-4bba-4fb3-8a15-a2a4eccbfe22",
"transaction_search": 0,
"info": {
"dt": "20251219145326",
"termid": "M1330I00",
"bankid": "M1330I00",
"bankname": "Приватбанк",
"payid": "420220",
"cancelid": "PAX694566e69ec6d3.09137775",
"refundid": "106064054534",
"cardmask": "4394********0993",
"paysys": "Visa",
"sum": 10.23,
"discount": 0.0,
"sumcash": 0.0,
"curr": "ГРН",
"restxt": "",
"sliptxt": "",
"isprint": 0,
"devinfo": "",
"deb_amount": 0.0,
"deb_num": 0,
"cred_amount": 0.0,
"cred_num": 0,
"canc_amount": 0.0,
"canc_num": 0,
"tx_num": 0,
"receipt": "",
"hstFld63Sf89": "",
"merch": "M1330I00",
"submerch": "",
"reference": "",
"purchase_dt": "20251219145326",
"pan": "",
"acquirerid": "",
"agreementNum": "",
"scenario_data": "",
"transaction_id": "52a27da5-4bba-4fb3-8a15-a2a4eccbfe22",
"oper_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9LnsiY2xpZW50X2lkIjoiMTExMTEiLCJpbnRlZ3JhdG9yX2lkIjoiMTExMTEiLCJvcGVyYXRpb24iOiJyZWZ1bmQiLCJleHAiOjExMTExMSwiYW1vdW50IjoxLCJoYXNoIjoiM2M2ODYzYzVmMWExMTE2ZDQxMTNhMmE2ZDA2MTZlMWZlOTFjMTRlOThhOTRlNTE4IiwidHJhbnNhY3Rpb25faWQiOiJQQVg2OTQ1NjZlNjllYzZkMy4wOTEzNzc3NSJ9LrHIn0hY9myhb+iSLVzUUWumoN2Hqe+bEbp4l256DgDi",
"commission": 0.0
},
"ver": 6,
"resp_ver": 4,
"source": "",
"device": "Privat",
"tag": "",
"task_status": 1,
"type": 3.0,
"task": 2.0,
"dt": "20251219170510382",
"res": 0,
"res_action": 0,
"errortxt": "",
"aq_errortxt": "",
"warnings": []
}
Приклад запиту на скасування операції ("task": 3)
Зверніть увагу що в значення ключа cancelid передається унікальний ідентифікатор операції на стороні Приватбанку. Часткове скасування з введенням частини суми у даному випадку недоступне.
{
"source": "API",
"device": "Privat",
"type": 3,
"pay": {
"task": 1,
"cancelid": "PAX694566e69ec6d3.09137775"
}
}
Приклад запиту на отримання статусу та даних раніше проведеної операції по терміналу ("task": 17).
Звертаємо увагу що в значення ключа oper_jwt передається oper_jwt що було повернуто у відповідь на операцію оплати чи повернення. У відповідь повернеться JSON ідентичний тому що був на оригінальну оплату чи повернення.
{
"source": "DM_API",
"device": "Privat",
"type": 3,
"pay": {
"task": 17,
"oper_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9LnsiY2xpZW50X2lkIjoiMTExMTEiLCJpbnRlZ3JhdG9yX2lkIjoiMTExMTEiLCJvcGVyYXRpb24iOiJyZWZ1bmQiLCJleHAiOjExMTExMSwiYW1vdW50IjoxLCJoYXNoIjoiM2M2ODYzYzVmMWExMTE2ZDQxMTNhMmE2ZDA2MTZlMWZlOTFjMTRlOThhOTRlNTE4IiwidHJhbnNhY3Rpb25faWQiOiJQQVg2OTQ1NjZlNjllYzZkMy4wOTEzNzc3NSJ9LrHIn0hY9myhb+iSLVzUUWumoN2Hqe+bEbp4l256DgDi"
}
}
Приклади помилок:
Сума повернення більше ніж сума продажу:
{
"ver": 6,
"resp_ver": 4,
"source": "",
"device": "Privat",
"tag": "",
"task_status": 3,
"type": 3.0,
"task": 2.0,
"dt": "20251219170642614",
"res": 5000,
"res_action": 1,
"errortxt": "Операція відхилена. Сума операцій на повернення (разом із поточною) більше за суму операції.",
"aq_errortxt": "",
"warnings": []
}
Операцію скасовано (натиснули значок "X" у застосунку tapxphone замість прикладання картки)
{
"ver": 6,
"resp_ver": 4,
"source": "",
"device": "Privat",
"tag": "",
"task_status": 3,
"type": 3.0,
"task": 1.0,
"dt": "20251219172911897",
"res": 5000,
"res_action": 1,
"errortxt": "Операція відхилена",
"aq_errortxt": "",
"warnings": []
}
Не встановлено застосунок Термінал від Приватбанку
{
"ver": 6,
"resp_ver": 4,
"source": "",
"device": "Privat",
"tag": "",
"task_status": 3,
"type": 3.0,
"task": 1.0,
"dt": "20251219173426239",
"res": 5000,
"res_action": 1,
"errortxt": "Платіжний застосунок не встановлено",
"aq_errortxt": "",
"warnings": []
}
Не встановлено застосунок Термінал від Приватбанку
{
"ver": 6,
"resp_ver": 4,
"source": "",
"device": "Privat",
"tag": "",
"task_status": 3,
"type": 3.0,
"task": 1.0,
"dt": "20251219173426239",
"res": 5000,
"res_action": 1,
"errortxt": "Платіжний застосунок не встановлено",
"aq_errortxt": "",
"warnings": []
}
Не коректно вказано ідентифікатор операції при проведенні повернення
{
"ver": 6,
"resp_ver": 4,
"source": "",
"device": "Privat",
"tag": "",
"task_status": 3,
"type": 1.0,
"task": 2.0,
"dt": "20251222101051673",
"res": 5000,
"res_action": 1,
"errortxt": "Операція відхилена. Не вдалось сформувати заявку на повернення коштів. Спробуйте пізніше.",
"aq_errortxt": "",
"warnings": []
}
Вичерпано час (20 секунд) на очікування запуску Device Manager зі сповіщення для проведення оплати.
{
"ver": 6,
"resp_ver": 4,
"source": "",
"device": "Privat",
"tag": "",
"task_status": 3,
"type": 1.0,
"task": 2.0,
"dt": "20251222101051673",
"res": 5000,
"res_action": 1,
"errortxt": "Вичерпано час очікування запуску застосунку із сповіщення. Повторіть останній запит..",
"aq_errortxt": "",
"warnings": []
}
-
При використанні терміналу у смартфоні для роботи в пакетному режимі додатково окремо відправляти запит на оплату немає потреби, ДМ це робить автоматично і після фіскалізує чек. Основна вимога це в чеках на повернення обов'язково вказувати ідентифікатор операції.
-
Для того щоб прийняти оплату екран мобільного пристрою має бути увімкнено і сам пристрій розблоковано (екран може бути вимкнено тільки у випадку виконання task 17),
Також у зв'язку з деякими обмеженнями Android для того щоб мати можливість запустити платіжний застосунок, Device Manager має бути відкритий на екрані пристрою. Так як DM працює як сервіс процес оплати якщо інтерфейс застосунку відкритий або згорнутий буде дещо відрізнятись.
Для початку розберемо процес оплати якщо застосунок DM на головному екрані пристрою
-
Виконуємо оплату на 1 грн (Як приклад)
-
Запускається застосунок термінал від Приватбанку де потрібно натиснути
Прийняти платіж карткою.
-
На наступному етапі потрібно прикласти картку до телефону та зачекати завершення платежу.
-
Далі застосунок термінал відобразить сліп-чек про оплату. На цьому кроці потрібно натиснути
Повернутися.
-
Застосунок Device Manager отримає результат операції від застосунку Термінал і оплата на цьому вважається успішною
Тепер процес оплати якщо застосунок DM працює у фоні, а на екрані знаходиться інший застосунок (у даному випадку, для прикладу, використовується застосунок Вчасно.Каса, проте на його місці може бути будь який інший застосунок що інтегровано з Device Manager)
- Додаються товари до чеку та на екрані оплата обирається спосіб оплати "Картка".
- По натисненню на кнопку "Оплатити" застосунок Вчасно.Каса в пакетному режимі відправляє запит на фіскалізацію чеку на Device Manager.
Приклад запиту
curl --location 'http://127.0.0.1:3939/dm/execute-pkg' \
--header 'Content-Type: application/json' \
--data '{
"source": "API",
"tag": "",
"device": "postgres1",
"need_pf_img": 2,
"type": 1,
"skipprint": false,
"skipterm": false,
"pay": {
"task": 1
},
"fiscal": {
"task": 1,
"receipt": {
"sum": 1,
"rows": [
{
"code": 308,
"name": "борг",
"cnt": 1,
"price": 1,
"taxgrp": 1
}
],
"pays": [
{
"type": 2,
"sum": 1
}
]
}
}
}'
- Так як до каси підключено термінал у смартфоні та у чека тип оплати картка - створюється оплата.
- Якщо всі дозволи для застосунку при його налаштуванні було надано - застосунок відкриється на головний екран і одразу створить оплату.
Якщо дозволу на відображення поверх інших застосунків не було надано - ДМ надсилає сповіщення на яке потрібно натиснути для початку проведення оплати. Звертаємо увагу що час очікування запуску Device Manager через сповіщення складає 20 секунд, якщо за цей час не вдалось натиснути на сповіщення - оплата буде скасована і чек не буде фіскалізовано, потрібно відправляти запит повторно. Після переходу за сповіщенням на головний екран буде відкрито Device Manager і одразу створено оплату.
-
Натискаємо в застосунку Приватбанку
Прийняти платіж карткою.
-
На наступному етапі потрібно прикласти картку до телефону та зачекати завершення платежу.
-
Далі застосунок термінал відобразить сліп-чек про оплату. На цьому кроці потрібно натиснути
Повернутися.
-
Застосунок Device Manager отримає результат операції від застосунку Термінал і оплата на цьому вважається успішною. Після завершення оплати на екрані залишиться застосунок Device Manager, потрібно лише повернутись назад до вашого касового застосунку.
-
Після повернення назад, чек уже буде успішно фіскалізовано з усіма даними про операцію.
- Нештатні ситуації та їх опрацювання.
Під час роботи, найчастіше у разі проблем з мережею, можливі випадки коли облікова система чи касова програма не зможе отримати відповіді від Device Manager або ж Device Manager не зможе отримати результат виконання операції оплати чи повернення від платіжного застосунку.
На такі випадки рекомендовано реалізувати транзакційний режим.
Транзакційний режим потрібен у випадку якщо облікова чи касова програма не змогла отримати відповіді від Device Manager на відправлений запит. В такому випадку вона може зробити повторний запит з переданим значенням ідентифікатору транзакції і отримати відповідь.
Транзакційний режим при роботі банківськими терміналами