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

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

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

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

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

Приклад deeplink для оплати:

Приклад deeplink для повернення:

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

ПолеТипОбов’язковеОпис
idstringтакУнікальний ідентифікатор платежу (до 250 символів), генерується інтегратором.
integratorIdstringтакІдентифікатор інтегратора (генерує mono, надається партнеру).
terminalstringтакid терміналу (MT%).
amountnumberтакСума платежу в копійках (наприклад, 10800 = 108.00 грн).
purposestringтакПризначення платежу. Максимальна довжина – 250 символів.
paymentTypestringніТип операції: purchase (покупка, за замовчуванням) або refund (повернення).
paymentFlowstringніТип оплати: nfc (за замовчуванням).
rrnstringніRRN NFC (обовʼязково для типу операції refund).
callbackSuccessstring (URL)такПосилання для виклику при успішному платежі.
callbackFailstring (URL)такПосилання для виклику при неуспішному платежі.
deeplinkCallbackstring (URL)ніДіплінк для підняття аплікації інтегратора.

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

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

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

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

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

ПолеТипОбов’язковеОпис
bankstringтакАТ Універсал Банк – константа
terminalstringтакid терміналу (MT%)
paymentTypestringтакpurchase – Продаж
refund – Повернення
amountintegerтакСума (в копійках)
ccystringтакКод валюти - UAH
statusstringтакСтатус платежу success або failed
internalPaymentIdstringтакВнутрішній ID транзакції
externalPaymentIdstringтакЗовнішній ID транзакції згенерований інтегратором
maskedPanstringтакМаска картки платника
cardMaskstringтакMastercard, Visa
approvalCodestringтакКод авторизації
rrnstringтакrrn
dataTimestringтакДата і час транзакції
responseCodestringтакКод відповіді
Якщо успіх - 1

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

json
				{
    "bank": "АТ Універсал Банк",
    "terminal": "MT512345",
    "paymentType": "purchase",
    "amount": 10000,
    "ccy": "UAH",
    "status": "success",
    "dataTime": "2025-07-22 10:00:00",
    "internalPaymentId": "cddd581a-5e7c-41bb-b855-b620987de280",
    "externalPaymentId": "92603267-cb5f-4d2c-917e-e4b6c1e41e0c",
    "maskedPan": "44441111******24",
    "cardMask": "visa",
    "approvalCode": "220486",
    "rrn": "000012345678",
    "responseCode": "1"
}

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

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

ПолеТипОбов’язковеОпис
errorMessagestringніКод помилки
responseCodestringтакКод помилки платіжної системи
bankstringтакАТ Універсал Банк – константа
terminalstringтакid терміналу (MT%)
paymentTypestringтакpurchase – Продаж
refund – Повернення
maskedPanstringніМаска картки платника
cardMaskstringніMastercard, Visa
approvalCodestringніКод авторизації
rrnstringніrrn
amountintegerніСума
ccystringніКод валюти
dataTimestringніДата і час транзакції
internalPaymentIdstringтакВнутрішній ID транзакції
externalPaymentIdstringтакЗовнішній ID транзакції згенерований інтегратором

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

json
				{
    "bank": "АТ Універсал Банк",
    "terminal": "MT512345",
    "paymentType": "purchase",
    "amount": 9800,
    "ccy": "UAH",
    "status": "rejected",
    "dataTime": "2025-07-22 10:00:00",
    "internalPaymentId": "cb8b68de-a923-44fd-b786-131584008b2e",
    "externalPaymentId": "fdf73256-5049-4c92-9df5-bb8999163bd7",
    "rrn": "",
    "errorMessage": "801-55:Невірний пін-код"
}

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

Коди 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 для безпеки передачі даних. Необхідно звернутися в підтримку для отримання ключа для подальшої розшифровки даних.

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

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

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