API перевірки IBAN: коректність рахунку і банк отримувача
Оновлено 26.09.2026
Initask API перевіряє український IBAN за стандартом ISO 13616: довжину 29 знаків, контрольне число mod-97 і код банку, а потім знаходить банк отримувача у довіднику НБУ за МФО. Адреса `GET https://dani.initask.com/v1/iban/{iban}`. IBAN з помилкою повертає відповідь з `valid: false` і переліком причин українською.
Для чого
Перевірка реквізитів перед платежем, валідація поля IBAN у формі і імпорт рахунків контрагентів. Помилка в одній цифрі рахунку означає повернений платіж, втрачений день і незадоволеного отримувача. Перевірка контрольного числа ловить таку помилку до відправки.
Параметр і приклад
| Параметр | Де | Обовʼязковий | Опис |
|---|---|---|---|
| iban | у шляху | так | IBAN, пробіли допускаються (у адресі їх кодують як %20) |
``` curl -H "Authorization: Bearer $INITASK_KEY" "https://dani.initask.com/v1/iban/UA213223130000026007233566001" ```
Користувачі часто копіюють IBAN з пробілами, групами по чотири знаки. Шлюз приймає такий запис, лише пробіли в адресі треба закодувати.
Поля відповіді
| Поле | Значення |
|---|---|
| valid | true, якщо IBAN коректний |
| iban | IBAN без пробілів |
| pretty | IBAN групами по 4 знаки |
| mfo | код банку МФО |
| account | номер рахунку в банку |
| errors | перелік помилок українською |
| bank | банк з довідника НБУ або null |
У прикладі IBAN коректний, МФО 322313, номер рахунку 26007233566001, банк АТ «Укрексімбанк» з кодом ЄДРПОУ 00032112. Поле `pretty` зручно показувати людині, поле `iban` зберігати в базі. Так у базі не зʼявляються однакові рахунки, записані по-різному, а людина бачить звичний запис групами.
Відповідь для неправильного IBAN
Помилковий IBAN дає відповідь 200 з `valid: false` і переліком `errors`. Такий підхід свідомий: форма отримує конкретну причину і показує її людині. «Неправильне контрольне число» підказує шукати одрук, «неправильна довжина» підказує, що скопійовано не все.
Помилка 400 приходить лише тоді, коли рядок узагалі не схожий на IBAN:
| Код | Помилка | Коли |
|---|---|---|
| 400 | bad_request | рядок довший за 34 знаки або містить сторонні символи |
Що перевірка ловить, а що ні
Перевірка математична: вона ловить помилку в одній цифрі і майже всі перестановки сусідніх цифр. Стан рахунку знає лише банк, тому закритий рахунок з правильним контрольним числом пройде перевірку як коректний. Для перевірки отримувача поєднуйте IBAN з карткою компанії за ЄДРПОУ: стан компанії показує, чи варто взагалі платити.
Назва банку береться з довідника банків НБУ за кодом МФО, який стоїть у IBAN з 5 по 10 знак. Якщо МФО у довіднику немає, поле `bank` дорівнює null.
Де перевірка IBAN дає найбільше
Найкорисніше місце для перевірки це поле вводу, у момент, коли людина вставила рахунок. Помилку видно одразу, і виправити її може та сама людина, яка знає правильний рахунок. Друге місце це імпорт: коли в систему завантажують таблицю рахунків контрагентів, кожен рядок перевіряється, а помилкові позначаються для ручного розбору. Третє місце це платіжне доручення перед відправкою в банк: остання перевірка, яка рятує від повернення коштів.
Для бухгалтерії, яка щомісяця платить десяткам постачальників, окремо корисна перевірка довідника контрагентів. Один прохід по всіх збережених рахунках показує, де закрався одрук ще під час першого введення, і такі рахунки виправляються до наступного платежу, а не після повернення.
Кеш і ліміти
Відповіді кешуються на 1440 хвилин, бо довідник банків змінюється рідко. Джерело: довідник банків НБУ через kurs.initask.com.
| План | Запитів | Ціна, грн на місяць |
|---|---|---|
| Безкоштовний | 100 на добу | 0 |
| Старт | 10000 на місяць | 990 |
| Про | 100000 на місяць | 2990 |
Ключ передається заголовком `Authorization: Bearer КЛЮЧ` або параметром `key`. Лічильник видно в заголовках `X-RateLimit-*`, після вичерпання приходить 429 з `Retry-After`.
Що робити
- Відкрийте документацію перевірки IBAN і перевірте свій рахунок.
- Змініть одну цифру і подивіться, як виглядає відповідь з `valid: false`.
- У формі показуйте текст з `errors` поруч з полем, щоб людина одразу виправила одрук.
- Показуйте назву банку з поля `bank` як підказку: людина впізнає свій банк і переконується, що рахунок правильний.
- Для валютних платежів додайте курс НБУ на дату, тарифи дивіться на сторінці Ціни і ліміти.
Питання і відповіді
Як перевірити IBAN через API?
Зробіть запит GET https://dani.initask.com/v1/iban/{iban}. Шлюз перевіряє довжину 29 знаків, контрольне число mod-97 і код банку та повертає банк з довідника НБУ за МФО.
Чи перевіряє API, що рахунок відкритий?
Перевірка математична: вона ловить помилку в одній цифрі і майже всі перестановки сусідніх цифр. Стан рахунку знає лише банк.
Що повертає API для IBAN з помилкою?
Відповідь 200 з valid: false і переліком errors українською, щоб форма показала людині конкретну причину.