Перевірка IBAN на JavaScript: fetch, valid і помилки для форми
Оновлено 26.09.2026
Поле IBAN у формі оплати, повернення коштів чи реєстрації партнера має ловити помилки до того, як людина натисне «Надіслати». Перевірка довжини регулярним виразом тут не рятує: IBAN з однією переплутаною цифрою має правильну довжину і формат. Initask API перевіряє контрольне число mod-97 за стандартом ISO 13616, код банку і знаходить банк отримувача в довіднику НБУ. На JavaScript це один запит `fetch` до `https://dani.initask.com/v1/iban/{iban}`.
Приклад
```javascript const r = await fetch("https://dani.initask.com/v1/iban/UA213223130000026007233566001", { headers: { Authorization: `Bearer ${process.env.INITASK_KEY}` }, }); const { ok, data, error } = await r.json(); console.log(r.headers.get("X-RateLimit-Remaining"), data); ```
Код розрахований на сервер: ключ читається зі змінної середовища і в браузер не потрапляє. Форма надсилає IBAN вашому серверу, сервер питає Initask API і повертає формі результат.
Як читати відповідь
Головне поле `valid`. Якщо воно `true`, IBAN коректний, і в `data` також приходять:
- сам IBAN без пробілів, для збереження в базі;
- той самий IBAN групами по 4 знаки, для показу людині;
- код банку МФО і номер рахунку в банку;
- дані банку з назвою, повною назвою, МФО, кодом ЄДРПОУ і станом.
Якщо `valid` дорівнює `false`, відповідь однаково приходить з кодом 200, а причини лежать у переліку `errors` українською. Для форми це зручно: текст помилки можна показати людині під полем без перекладу і без власних формулювань. Програмна помилка з кодом 400 приходить лише тоді, коли рядок довший за 34 знаки або містить сторонні символи.
Помилка в одній цифрі
Перевірка контрольного числа ловить помилку в одній цифрі і майже всі перестановки сусідніх цифр. Саме такі помилки люди роблять, коли переписують IBAN з документа чи диктують його телефоном. Стан рахунку перевірка не показує: чи відкритий рахунок і кому він належить, знає лише банк.
Назва банку як підтвердження для людини
Після успішної перевірки покажіть поруч з полем назву банку отримувача. Людина, яка вводить власні реквізити, одразу бачить, чи збігається банк з її карткою. Людина, яка вводить реквізити партнера, може звірити банк з документом. Така дрібниця ловить помилки, які контрольне число пропускає: наприклад, коли скопійовано коректний, але чужий IBAN з іншого листа. Назва береться з довідника банків НБУ за кодом МФО, що стоїть у IBAN з 5 по 10 знак.
Якщо банк у довіднику не знайдено, поле банку порожнє. IBAN при цьому коректний, але людину варто попросити ще раз звірити реквізити.
Пробіли і формат введення
Люди вставляють IBAN як завгодно: з пробілами, групами по 4 знаки, з малими літерами. Пробіли API допускає, у адресі запиту їх кодують як %20. Простіше прибрати пробіли на своєму сервері перед запитом, а людині після успішної перевірки показати значення з поля `pretty`: так вона бачить звичний формат і може звірити його з документом.
Ліміти і 429
Кожна відповідь містить заголовки лімітів: сам ліміт, залишок і момент скидання. Коли ліміт вичерпано, приходить код 429 і заголовок `Retry-After`. Для форми оплати розумно в такому разі не блокувати людину: прийняти IBAN, позначити його як неперевірений і перевірити пізніше фоновою задачею.
| План | Запитів | Ціна, грн на місяць |
|---|---|---|
| Безкоштовний | 100 на добу | 0 |
| Старт | 10000 на місяць | 990 |
| Про | 100000 на місяць | 2990 |
Кешування
Результат перевірки IBAN не змінюється, шлюз тримає його в кеші 1440 хвилин. На своєму сервері варто кешувати так само: якщо людина кілька разів надсилає форму з тим самим IBAN, перевірка потрібна одна. Не перевіряйте IBAN на кожне натискання клавіші: запит має сенс, коли введено всі 29 знаків.
Що робити
- Перенесіть перевірку IBAN на сервер і повертайте формі ознаку коректності, IBAN групами і перелік помилок.
- Показуйте людині помилки з `errors` дослівно під полем.
- Надсилайте запит лише після введення всіх 29 знаків і кешуйте результат.
- Для платежів юрособам підтягуйте реквізити з картки компанії за ЄДРПОУ, для валютних сум курс з API курсу НБУ.
- Опис полів у документації перевірки IBAN, тарифи на сторінці Ціни і ліміти.
Питання і відповіді
Як перевірити IBAN у JavaScript?
Запит fetch до https://dani.initask.com/v1/iban/{iban} з ключем у заголовку Authorization повертає поле valid, IBAN групами по 4 знаки, МФО, рахунок і банк з довідника НБУ.
Чому API повертає 200 для неправильного IBAN?
Щоб форма могла показати людині конкретну причину: у відповіді valid: false і перелік errors українською.
Чи можна перевіряти IBAN прямо з браузера?
Краще з сервера: так ключ API не потрапляє в код сторінки, а результат можна кешувати.