API документація

Термінал в смартфоні iOS

Для інтеграції з Терміналом в смартфоні на iOS у вас має бути зареєстрований термінал. Подати заявку на реєстрацію можна на сайті https://monobank.ua/terminal

Виклик застосунку “Термінал by mono” та передача параметрів для проведення оплати

Для правильного формування запиту вам знадобиться отримати ряд параметрів

terminal - отримується за допомогою методу отримання списку терміналів
integratorId - необхідно звернутися до нас в підтримки, щоб ми вам його надали

Виклик застосунку через deeplink

Приклад deeplink:

terminal.mono.bank://payment/start?id=68df72a6-da85-42fc-8fe8-7d9b8250d8ae&integratorId=19122dda-f00b-46cd-8033-0e20d23f3b78&terminal=MT500040&amount=1000&purpose=Оплата%20замовлення&callbackSuccess=https://example.com/success&callbackFail=https://example.com/success&deeplinkCallback=myapp://payment.com

Опис параметрів:

Поле	Тип	Обов’язкове	Опис
id	string	так	Унікальний ідентифікатор платежу (до 250 символів), генерується інтегратором.
integratorId	string	так	Ідентифікатор інтегратора (генерує mono, надається партнеру).
terminal	string	так	id терміналу (MT%).
amount	number	так	Сума платежу в копійках (наприклад, 10800 = 108.00 грн).
purpose	string	так	Призначення платежу. Максимальна довжина – 250 символів.
paymentType	string	ні	Тип операції: purchase (покупка, за замовчуванням) або refund (повернення).
paymentFlow	string	ні	Тип оплати: nfc (за замовчуванням).
rrn	string	ні	RRN NFC (обовʼязково для типу операції refund).
callbackSuccess	string (URL)	так	Посилання для виклику при успішному платежі.
callbackFail	string (URL)	так	Посилання для виклику при неуспішному платежі.
deeplinkCallback	string (URL)	ні	Діплінк для підняття аплікації інтегратора.

Рекомендуємо передавати саме universal link у параметрі `deeplinkCallback`. На відміну від schema url (наприклад, `myapp://`), universal link не вимагає додаткових змін у коді застосунку або оновлення в App Store для коректної роботи. Universal link відкриває застосунок, якщо він встановлений, або відкриває веб-сторінку, якщо застосунок не встановлено.

Приклад: deeplinkCallback: https://yourapp.com/payment-callback

Отримання відповіді

Отримання відповіді про успішну оплату або повернення.

Параметри будуть надіслані у callbackSuccess метод POST який був переданий інтегратором у deeplink:

Поле	Тип	Обов’язкове	Опис
bank	string	так	АТ Універсал Банк – константа
terminal	string	так	id терміналу (MT%)
paymentType	string	так	purchase – Продаж, refund – Повернення
maskedPan	string	так	Маска картки платника
cardMask	string	так	Mastercard, Visa
approvalCode	string	так	Код авторизації
rrn	string	так	rrn
amount	string	так	Сума
ccy	string	так	Код валюти
dataTime	string	так	Дата і час транзакції

Приклад відповіді:

json

				{
	"bank":"АТ Універсал Банк",
	"terminal":"MT500550",
	"paymentType":"purchase",
	"amount":1000,
	"ccy":"UAH",
	"status":"success",
	"dataTime":"2025-07-24 15:26:09",
	"maskedPan":"537511******12",
	"cardMask":"mastercard",
	"approvalCode":"123456", 
	"rrn": "123456789012"
}

Отримання відповіді на неуспішну оплату/повернення.

Параметри будуть надіслані у callbackFail метод POST який був переданий інтегратором у deeplink:

Поле	Тип	Обов’язкове	Опис
responseCode	string	так	Код помилки платіжної системи
bank	string	так	АТ Універсал Банк – константа
terminal	string	так	id терміналу (MT%)
paymentType	string	так	purchase – Продаж, refund – Повернення
maskedPan	string	так	Маска картки платника
cardMask	string	так	Mastercard, Visa
approvalCode	string	так	Код авторизації
rrn	string	так	rrn
amount	string	так	Сума
ccy	string	так	Код валюти
dataTime	string	так	Дата і час транзакції

Приклад відповіді:

json

				{
	"responseCode": "59",
	"bank": "АТ Універсал Банк",
	"terminal": "MT500550",
	"paymentType": "purchase",
	"amount": 1000,
	"ccy": "UAH",
	"status": "rejected",
	"dataTime": "2025-07-24 15:29:56",
	"maskedPan": "44727718******12",
	"cardMask": "visa",
	"rrn": "123456789012"
}

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

Коди responseCode

Код помилки	Опис
06	Потрібен пін або 3дс
22	Перевищено еквайринговий ліміт
25	Слабкий PIN
50	Несанкціоноване використання
51	Закінчився термін дії картки
52	Невірна карта
53	Невірний PIN-код
54	Системна помилка
55	Невідповідна транзакція
56	Невідповідний рахунок
57	Транзакція не підтримується
58	Картка обмежена (операція по картці не дозволена)
59	Недостатньо коштів на рахунку
60	Перевищено ліміт на число використань картки
61	Встановлені ліміти банку які не дозволяють проводити транзакцію
63	Ліміти банку
67	Недопустима сума
68	Транзакцію відхилено зовнішнім хостом
69	Неузгоджений запит (дана картка не обслуговується в даному терміналі)
72	Авторизатор недоступний
74	Помилка формату
75	Транзакцію відкинуто зовнішнім хостом за спеціальною умовою
80	Невірний CVV
82	Транзакція не дозволена з такими умовами проведення

Робота з callback

У deeplink ви передаєте 3 посилання:

callbackSuccess
callbackFail
deeplinkCallback

callbackSuccess - необхідний для отримання інформації про успішну оплату на ваш сервер для подальшого використання

callbackFail - необхідний для отримання інформації про не успішний платіж. Важливо, що текст самої помилки переданий не буде, буде передаватися лише код. Коди помилок описані нижче

deeplinkCallback - необхідний якщо потрібно підіймати екран після створення оплати. Наприклад, це може бути екран вашого застосунку.

Буде накладено підпис на callback для безпеки передачі даних. Необхідно звернутися в підтримку для отримання ключа для подальшої розшифровки даних.

Флоу по створенню оплати

Флоу по створенню запиту на повернення

Отримання списку терміналів