API роботи з терміналами

Протокол	1	2	3	4	5	6	7	8	10	11	14	15	16	17
PrivatbankJSON	✅	✅	✅	❌	✅	✅	✅	❌	✅	✅	✅	✅	✅	✅
BPOS1	✅	✅	✅	✅	❌	✅	✅	✅	✅	✅	✅	✅	❌	✅
POSAPI	✅	✅	✅	❌	❌	✅	✅	❌	✅	✅	✅	❌	❌	✅
SSI JSON	✅	✅	✅	❌	❌	❌	❌	❌	✅	✅	✅	❌	❌	✅
А-Банк JSON	✅	✅	✅	❌	❌	❌	❌	❌	❌	✅	✅	❌	❌	❌
SmartOne JSON	✅	✅	✅	❌	❌	❌	❌	❌	✅	✅	❌	❌	❌	✅
BPOS Light	✅	✅	✅	❌	❌	❌	❌	❌	✅	✅	❌	❌	❌	❌
SimPays ККМ	✅	✅	✅	❌	❌	❌	❌	❌	✅	✅	❌	❌	❌	❌

Модель терміналу	1	2	3	4	5	6	7	8	10	11	14	15	16	17
Verifone X990/Newland N950	✅	✅	✅	❌	❌	❌	❌	❌	✅	✅	✅	❌	❌	✅
Castles Saturn 1000 (F2 та F3)	✅	✅	✅	❌	❌	❌	❌	❌	✅	✅	✅	❌	❌	✅
SmartOne Bank/SmartOne Bank Pro	✅	✅	✅	❌	❌	❌	❌	❌	✅	✅	❌	❌	❌	✅
Ingenico Axium DX4000/Ingenico Axium DX8000	✅	✅	✅	❌	❌	❌	❌	❌	✅	✅	❌	❌	❌	✅
PAX A910S	✅	✅	✅	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	✅

Банк що надає термінал у смартфоні	1	2	3	4	5	6	7	8	10	11	14	15	16	17
Приватбанк	✅	✅	Тимчасово не працює з боку банку, але реалізовано	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	✅
Monobank	✅	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	✅

Протокол	1	2	3	4	5	6
PrivatbankJSON	✅	✅	✅	✅	✅	✅
BPOS1	❌	✅	❌	✅	✅	✅
POSAPI	❌	✅	❌	✅	✅	✅
SSI JSON	❌	✅	❌	✅	❌	✅
А-Банк JSON	❌	✅	❌	❌	❌	✅
SmartOne JSON	❌	✅	❌	❌	❌	✅
BPOS Light	❌	✅	❌	❌	❌	✅
SimPays ККМ	❌	✅	❌	❌	❌	✅

Модель терміналу	1	2	3	4	5	6
Verifone X990/Newland N950	❌	✅	❌	❌	❌	✅
Castles Saturn 1000 (F2 та F3)	❌	✅	❌	❌	❌	✅
SmartOne Bank/SmartOne Bank Pro	❌	✅	❌	❌	❌	✅
Ingenico Axium DX4000/Ingenico Axium DX8000	❌	✅	❌	❌	❌	✅
PAX A910S	❌	✅	❌	❌	❌	✅

Банк що надає термінал у смартфоні	1	2	3	4	5	6
Приватбанк	❌	❌	❌	❌	❌	✅
Monobank	❌	❌	❌	❌	❌	✅

Протокол	1	2	3	4	5
PrivatbankJSON	✅	✅	✅	✅	✅
BPOS1	❌	✅	✅	✅	✅
POSAPI	❌	❌	✅	✅	❌
SSI JSON	❌	✅	❌	✅	✅
А-Банк JSON	❌	❌	❌	❌	❌
SmartOne JSON	❌	❌	❌	✅	❌
BPOS Light	❌	❌	❌	❌	❌
SimPays ККМ	❌	❌	❌	❌	❌

Модель терміналу	1	2	3	4	5
Verifone X990/Newland N950	❌	✅	❌	✅	✅
Castles Saturn 1000 (F2 та F3)	❌	❌	❌	✅	❌
SmartOne Bank/SmartOne Bank Pro	❌	❌	❌	✅	❌
Ingenico Axium DX4000/Ingenico Axium DX8000	❌	❌	❌	✅	❌
PAX A910S	❌	❌	❌	❌	❌

Банк що надає термінал у смартфоні	1	2	3	4	5
Приватбанк	❌	❌	❌	✅	❌
Monobank	❌	❌	❌	✅	❌

Ключ	Тип json даних	Зміст	Обов'язковий
source	string	Назва відправника завдання. При інтеграції рекомендовано використовувати назву POS системи або компанії. Може бути порожнім.	❌
device	string	Назва терміналу або tap2phone створеного в ДМ для ідентифікації.	✅
transaction_id	string	UUID (v5). Ідентифікатор транзакції що використовується як мітка для завдання для пошуку при повторному запиті. Якщо передати значення відмінне від UUID формату, воно буде замінено на UUID що згенерував ДМ та повернуто у відповідь. Використовується лише для завдань роботи з терміналами.	❌
transaction_search	number	Параметр дій з пошуком транзакції. 0 - Пошук транзакції не відбувається, запит одразу йде на термінал. 1 - Пошук транзакції перед відправкою даних на термінал. Якщо знайдено, буде повернуто json у відповідь на запит. Якщо транзакцію не було знайдено в БД буде повернуто відповідь що такої транзакції неіснує і дії пов'язані з цією транзакцією(оплата, повернення, скасування) не будуть відправлені на термінал. 2 - Пошук транзакції перед відправкою даних на термінал. Аналогічно 1, за виключенням того, якщо транзакцію не було знайдено в БД запит буде відправлено на термінал. За замовчуванням = 0 Використовується лише для завдань роботи з терміналами і тільк в парі з transaction_id.	❌
type	number	Тип завдання. Для завдань роботи з терміналами завжди 3.	✅
pay	object	Об'єкт із даними для завдань роботи з терміналами. Використовується тільки для запитів на термінал("type": 3) та в пакетному режимі ПРРО.	✅

Ключ	Тип json даних	Зміст	Обов'язковий
task	number	Номер завдання для роботи з терміналами. Номер вказується згідно списку доступних завдань по терміналам.	✅
subtask	number	Окремий додатковий функціонал який змінює логіку роботи деяких завдань. Наразі змінює логіку проведення повернень по терміналам по протоколу PrivatBankJSON. 1 - повернення виконується через операцію "Сервіс повернення" замість звичайного повренненя, 0 - виконання повренння буде залежати від налаштування "Виконувати повернення через операцію "Сервіс повернення" замість звичайного повернення." на сторінці "Додаткові налаштування терміналу". За замовчуванням = 0	❌
cancel_on_disconnect	boolean	Параметр що визначає необхідність виконати скасування проведеної оплати чи повернення по терміналу якщо облікова програма не змогла отримати відповідь. Якщо на момент успішного завершення операції по терміналу DM не зможе повернути http відповідь бо ініціатор запиту - закрив сокет для уникнення розбіжностей буде виконано автоматичне скасування останньої оплати. true - виконувати, false (за замовчуванням) - не виконувати.	❌
sum	number	Сума операції згідно обраного завдання (task). Обов'язковий лише для операцій що потребують вказання суми (наприклад оплата). 2 знаки після коми.	✔
sumcash	number	Обов'язковий тільки для операції Оплата товару/послуги + видача готівки ("task": 14). Сума готівки до видачі покупцю. 2 знаки після коми.	✔
merch	string	Ідентифікатор організації – мерчанта. Використовується для визначення мерчанта (торгівця) по якому буде проведено оплату. У випадку якщо термінал містить кілька мерчантів і значення merch не передано, на терміналі може бути запропоновано вручну обрати зі списку мерчанта на користь якого потрібно провести оплату або буде повернуто помилку (залежить від терміналу). Перелік доступних мерчантів можна отримати через метод /dm/getmerchantlist з терміналу або дізнатись в банку. Для більшості терміналів передавати значення обов'язково. Не вказується для tap2phone.	✔
submerch	string	Тільки для PrivatBankJSON. Номер субмерчанта наданий Приватбанком.	❌
get_receipt	boolean	Тільки для BPOS1. Параметр що визначає чи потрібно отримати з терміналу сліп чек про завершену операцію в текстовому форматі, наприклад щоб роздрукувати його на чековому принтері замість друку з терміналу. Працює для всіх операцій будь то оплата, повернення чи оплата частинами. Друковану форму текстового чеку налаштовує банк. За замовчуванням false. Якщо true друкований чек буде повернуто в значенні ключа info.receipt після завершення операції.	❌
refundid	string	Обов'язковий тільки для повернення (`"task": 2`). Ідентифікатор платежу (RRN код 12 цифр), по якому робиться повернення. Для терміналів Монобанку в дане поле передається код авторизації (6 цифр), для терміналу у смартфоні від Приватбанку передається унікальний ідентифікатор операції на сервері банку який повертається у відповіді на успішну оплату в ключі info.cancelid.	✔
cancelid	string	Обов'язковий тільки для cкасування проведеної операції на терміналі (`"task": 3`). Унікальний ідентифікатор операції або номер чеку всередині терміналу. Для завдання 3 означає номер операції який потрібно скасувати, для завдання `"task": 17` означає ідентифікатор чи номер операції, дані по якій потрібно отримати з терміналу. Скасування по завданню 3 можливо робити якщо після операції не було знято загальний звіт з терміналу.	✔
cancelid2	string	Обов'язковий тільки для cкасування проведеної операції на терміналі (`"task": 3`) при роботі з терміналами по протоколу А-Банк JSON. Номер чеку операції з терміналу який потрібно скасувати. Передається додатково до ключа cancelid так як для терміналів А-Банку є обов'язковим 2 ключа для скасування. Скасування по завданню 3 можливо робити якщо після операції не було знято загальний звіт з терміналу.	✔
auth_code	string	Обов'язковий тільки для повернення по терміналам Монобанку (`"task": 2`). Так як термінали Монобанку повернення виконують по коду авторизації можна або код авторизації передавати в refundid або зробити універсальну схему: в refundid передавати RRN код, а у auth_code - код авторизації. В такому випадку не залежно від того якого банку термінал - повернення завжди будуть працювати.	✔
rec_name	string	Обов'язковий тільки для BPOS1 та операції P2P переказ (`"task": 4`). Ім'я отримувача для проведення переказу. Обов'язково латиницею, інакше буде помилка при проведенні переказу.	✔
rec_surname	string	Обов'язковий тільки для BPOS1 та операції P2P переказ (`"task": 4`). Прізвище отримувача для проведення переказу. Обов'язково латиницею, інакше буде помилка при проведенні переказу.	✔
rec_pan	string	Обов'язковий тільки для BPOS1 та операції P2P переказ (`"task": 4`). Номер картки отримувача для проведення переказу.	✔
installment_id	number	Обов'язковий тільки для BPOS1 та операції оформлення оплати частинами (`"task": 15`). Тип розстрочки. 1 - Розстрочка за рахунок покупця 2 - Розстрочка за рахунок торгівця.	✔
amountOfParts	number	Обов'язковий тільки для оформлення оплати частинами (`"task": 15`). Кількість частин на яку розділяється платіж.	✔
agreementNum	string	Обов'язковий тільки для PrivatBankJSON та операції Повернення по оплаті частинами (`"task": 16`). Номер договору, по якому робиться повернення. Повертає банк у відповідь на успішне оформлення оплати частинами.	✔
param	string	Обов'язковий тільки для PrivatBankJSON та операції Універсальний сервіс (`"task": 5`). Кількість платежів в разі оформлення миттєвої розстрочки або оплати частинами.	✔
srvNum	string	Обов'язковий тільки для PrivatBankJSON та операції Універсальний сервіс (`"task": 5`). Номер сервісу, номери можна дізнатись в Приватбанку.	✔
oper_action	number	Обов'язковий тільки для завершення проведення операції з очікуванням підтвердження/корекції (`"task": 7`). Подальша дія з оплатою 0 - скасувати оплату (за замовчуванням якщо не передано) 1 - продовжити оплату (карта повторно не прикладається).	✔

Тег	Тип json даних	Зміст
transaction_id	string	Ідентифікатор операції. Аналогічне значенню що передано в запиті, за виключенням випадків коли передане в запиті значення не відповідає формату UUID (v5). В такому разі буде повернуто значення згенероване ДМ.
transaction_search	number	Дії з пошуком транзакції. Аналогічне значенню що передано в запиті.
info	object	Об'єкт із даними отриманими після завершення операції по терміналу.
ver	number	`DEPRECATED`. Версія схеми. Завжди дорівнює 6. (повертається лише для сумісності з попередніми версіями)
resp_ver	number	Версія JSON відповіді. Змінюється на +1 з новим релізом застосунку якщо у відповіді повертатимуться нові дані.
source	string	Назва відправника завдання. Наразі завжди порожнє.
device	string	Назва пристрою, в даному випадку назва терміналу або tap2phone, створеного в ДМ до якого був запит.
tag	string	Для завдань роботи з терміналами завжди буде порожнім.
type	number	Для завдань роботи з терміналами завжди буде 3.
task	number	Номер завдання. Дорівнює тому ж значенню що і в запиті.
task_status	number	Значення статусу виконання завдання: 1 - операцію виконано успішно 3 - помилка при оплаті, при цьому значення res завжди буде більше 0.
dt	string	Дата та час виконання завдання у форматі рядка: YYYYMMDDHHMMSSTTT
res	number	Код результату виконання завдання: 0 = ОК, >0 код помилки
res_action	number	Подальші рекомендовані дії для дотримання транзакційної цілісності. Детальніше.
errortxt	string	Текстова інформація про помилку в ДМ або помилка отримана від терміналу. Якщо res = 0 буде порожнім
aq_errortxt	string	Для завдань роботи з терміналами завжди буде порожнім.
warnings	array	Для завдань роботи з терміналами завжди буде порожнім.

Тег	Тип json даних	Зміст
dt	string	Дата та час виконання запиту терміналом у форматі рядка. Формат дати буде різним залежно від того як її повертає конкретний термінал.
termid	string	Код або ідентифікатор банківського термінала.
bankid	string	Ідентифікатор торгівця у екваєра (в системі банку), або номер чи ідентифікатор мерчанту.
payid	string	Номер/ідентифікатор платіжної операції або код авторизації.
cancelid	string	Ідентифікатор операції або внутрішній номер чеку всередині терміналу. Використовується в подальшому в разі необхідності скасування операції оплати чи повернення (`"task": 3`) або для повторного пошуку даних про операцію (`"task": 17`)
cancelid2	string	Повертається тільки при роботі з терміналами по протоколу А-Банк JSON. Внутрішній номер чеку всередині терміналу. Використовується в подальшому разом із значенням cancelid в разі необхідності скасування операції оплати чи повернення (`"task": 3`)
refundid	string	Унікальний ідентифікатор транзакції (RRN код) який в подальшому використовується для повернення.
cardmask	string	Замаскований номер платіжного засобу картки.
paysys	string	Назва платіжної системи.
sum	number	Сума операції. 2 знаки після коми.
sumcash	number	Сума видачі готівки. Дорівнює 0 для всіх операцій окрім видачі коштів. Оплата товару/послуги + видача готівки. (`"task": 14`). 2 знаки після коми.
discount	number	Сума знижки з оплати на рівні банку при проведенні операції. 2 знаки після коми.
curr	string	Валюта операції. Наразі завжди дорівнює "ГРН"
restxt	string	Результат виконання операції терміналом. Повертається лише для частини протоколів роботи з терміналами.
sliptxt	string	`DEPRECATED`Наразі завжди має пусте значення.
isprint	number	`DEPRECATED`Наразі завжди = 1.
devinfo	string	`DEPRECATED`Наразі завжди має пусте значення.
deb_amount	number	Загальна сума оплат/продажів за день. Повертається лише при виконанні операцій X-Баланс (Друк підсумків без закриття зміни на терміналі.) (`"task": 10`) або Загальний звіт (Закриття зміни на терміналі та друк підсумків.) (`"task": 11`). Якщо протокол терміналу не підтримує повернення підсумків, а лише друк значення буде 0.
deb_num	number	Кількість операцій оплат за день. Повертається лише при виконанні операцій X-Баланс (Друк підсумків без закриття зміни на терміналі.) (`"task": 10`) або Загальний звіт (Закриття зміни на терміналі та друк підсумків.) (`"task": 11`). Якщо протокол терміналу не підтримує повернення підсумків, а лише друк значення буде 0.
cred_amount	number	Загальна сума операцій повернення за день. Повертається лише при виконанні операцій X-Баланс (Друк підсумків без закриття зміни на терміналі.) (`"task": 10`) або Загальний звіт (Закриття зміни на терміналі та друк підсумків.) (`"task": 11`). Якщо протокол терміналу не підтримує повернення підсумків, а лише друк значення буде 0.
cred_num	number	Кількість операцій повернення за день. Повертається лише при виконанні операцій X-Баланс (Друк підсумків без закриття зміни на терміналі.) (`"task": 10`) або Загальний звіт (Закриття зміни на терміналі та друк підсумків.) (`"task": 11`). Якщо протокол терміналу не підтримує повернення підсумків, а лише друк значення буде 0.
canc_amount	number	Загальна сума скасованих операцій за день. Повертається лише при виконанні операцій X-Баланс (Друк підсумків без закриття зміни на терміналі.) (`"task": 10`) або Загальний звіт (Закриття зміни на терміналі та друк підсумків.) (`"task": 11`). Якщо протокол терміналу не підтримує повернення підсумків, а лише друк значення буде 0.
canc_num	number	кількість скасованих операцій за день. Повертається лише при виконанні операцій X-Баланс (Друк підсумків без закриття зміни на терміналі.) (`"task": 10`) або Загальний звіт (Закриття зміни на терміналі та друк підсумків.) (`"task": 11`). Якщо протокол терміналу не підтримує повернення підсумків, а лише друк значення буде 0.
tx_num	number	Загальна кількість всіх операцій за день. Повертається лише при виконанні операцій X-Баланс (Друк підсумків без закриття зміни на терміналі.) (`"task": 10`) або Загальний звіт (Закриття зміни на терміналі та друк підсумків.) (`"task": 11`). Якщо протокол терміналу не підтримує повернення підсумків, а лише друк значення буде 0.
receipt	string	Друкована форма сліп чеку що друкує термінал у вигляді тексту з форматуванням. Повертається не для всіх протоколів роботи з терміналами.
hstFld63Sf89	string	Тільки для PrivatBankJSON. Дані з хоста(банку).
merch	string	Внутрішній омер мерчанту в терміналі.
submerch	string	Тільки для PrivatBankJSON. Номер субмерчанта отриманий від Приватбанку.
reference	string	Тільки для терміналів по протоколу А-Банк JSON - інакше буде порожнє значення. Порядковий номер операції на терміналі (враховуються всі успішні і неуспішні запити на термінал).
purchase_dt	string	Дата та час оплати на терміналі у форматі рядка. Формат: YYYYMMDDhhmmss
pan	string	`DEPRECATED`Наразі завди порожнє.
acquirerid	string	`DEPRECATED`Наразі завди порожнє.
agreementNum	string	Тільки для PrivatBankJSON та тільки у випадку використання універсального сервісу (`"task": 5`). Номер договору після завершення оформленням миттєвої розстрочки чи оплати частинами.
scenario_data	string	Тільки для BPOS1 та тільки у випадку використання операції через сценарії (`"task": 4`, `"task": 8`, `"task": 14`, `"task": 15`). XML відповідь з результатом виконання операції від терміналу в форматі рядка.
transaction_id	string	Внутрішній ідентифікатор операції.
oper_jwt	string	Тільки при використання tap2phone від Приватбанку. JWT токен операції по якому можна виконати повторний запит результату виконаної оплати чи повернення.
commission	number	Сума комісії з оплати (до 2-х знаків після коми). Так як термінали її не повертають розраховується автоматично згідно суми оплати і відсотка комісії банку що був вказаний при налаштуванні терміналу.
bank_trn_id	string	Bank transaction ID або унікальний внутрішній номер карткової операції, наданий терміналом, для подальшої доставки чеку у застосунок банку по програмі Національний чек (єЧек). Потрібно передати при фіскалізації чеку у ключ fiscal.bank_trn_id. Якщо термінал не підтримує повернення даного ідентифікатора або банк покупця не долучився до програми Національний чек - значення буде порожнє.

Параметр	Зміст	Обов'язковий
dev_name	Назва терміналу, створеного в ДМ.	✅

Параметр	Зміст	Обов'язковий
dev_name	Назва терміналу, створеного в ДМ.	✅

Тег	Тип json даних	Зміст
merchListValue	string	`DEPRECATED`Список мерчантів та їх кодів в даному терміналі.
merchList	array	Масив об'єктів з інформацією про мерчантів в терміналі. Кожен об'єкт в масиві є окремим мерчантом з його найменуванням і кодом.

Тег	Тип json даних	Зміст
num	string	Номер або код мерчанта. Може бути як числовий одноцифровий так і буквенний залежно від терміналу і протоколу. Використовується для виконання запитів на термінал в значенні ключа merch та при налаштуванні пакетного режиму.
id	string	Ідентифікатор або назва мерчанта для розуміння що це за мерчант. Для терміналів які не повертають назви для ідентифікації в даному полі буде вказано: "МерчантN" де N порядковий номер мерчанту.

Параметр	Зміст	Обов'язковий
dev_name	Назва терміналу, створеного в ДМ.	✅

Тег	Тип json даних	Зміст
maskListValue	string	Список масок мерчантів та їх кодів в даному терміналі.

Параметр	Зміст	Обов'язковий
dev_name	Назва терміналу, створеного в ДМ.	✅

Параметр	Зміст	Обов'язковий
dev_name	Назва терміналу, створеного в ДМ.	✅

Тег	Тип json даних	Зміст
status_code	string	Внутрішній код статусу на терміналі.
status_message	string	Повідомлення в якому статусі знаходиться термінал.

Параметр	Зміст	Обов'язковий
dev_name	Назва терміналу, створеного в ДМ.	✅
status	Яку операцію повернути. 0 або інше значення, або не передано - остання транзакція по терміналу не залежно від статусу (успішна чи помилка) 1 - остання успішна транзакція	❌

¶ Початок роботи із терміналами

¶ Для початку роботи в тестовому режимі потрібно:

¶ Для того щоб почати працювати з робочим терміналом:

¶ Доступні завдання

¶ Додатковий функціонал

¶ Загальна інформація по обміну даними та наявні обмеження

¶ Структура JSON Body запиту

¶ Структура JSON Body відповіді

¶ Приклади запитів

¶ Додаткові методи при роботі з терміналами