Відкрите API

Безкоштовний API для генерації QR IBAN платежів для розробників.

OpenCart 2.3 / 3 / 4

Модуль для прийому платежів на ваш рахунок IBAN. 0% комісії. Автоматичне оновлення статусу замовлення на «оплачено» після отримання платежу.

Github/opencart-iban

WordPress WooCommerce

Github/iban-woo

KeyCRM

Створення посилань на оплату по IBAN прямо із замовлень KeyCRM та автоматичне відстеження статусу оплати через webhook.

Інструкція з підключення

SalesDrive

Генерація QR-коду для оплати по IBAN із замовлень SalesDrive та відстеження статусу оплати за обраним статусом замовлення.

Інструкція з підключення

Для комерційного використання зареєструйтеся та отримайте особистий ключ.

Форма POST запиту

Вбудуйте кнопку оплати на свій сайт: відправте POST‑запит на наш API з реквізитами. Потрібні поля:

code: 8 або 10 цифр (ЄДРПОУ або РНОКПП)
iban: формат UA + 27 цифр
amount: сума у гривнях (рядок з двома знаками після коми)
purpose: призначення платежу (рядок)
responseModeoptional: json (default) | page | bank-link | qr-png
x-client-key: Bh1mvuMz/FG9ogSsvOZNQz79Oc+oU7xXkdOLtDm9ASg=
x-client-name: public

Або використовуйте ibanSettingId

Замість code і iban передайте ibanSettingId — ID налаштувань зі списку у профілі (розділ "Налаштування IBAN").

ibanSettingId: ID налаштування IBAN — замінює і code, і iban.
amount: сума у гривнях (рядок з двома знаками після коми)
purpose: призначення платежу (рядок)
responseModeoptional: json (default) | page | bank-link | qr-png

Створити рахунок

Створює рахунок QR IBAN. Поведінка відповіді визначається параметром responseMode: 'json' (default) | 'page' | 'bank-link' | 'qr-png'.

Endpoint: https://iban.opendatabot.ua/api/invoice
Method: POST

HTML приклад

<form action="https://iban.opendatabot.ua/api/invoice" method="post">
  <input name="code" type="text" value="2882618253" hidden />
  <input name="iban" type="text" value="UA063052990000026008050293936" hidden />
  <input name="amount" type="text" value="128.00" hidden />
  <input name="purpose" type="text" value="Тестова оплата" hidden />
  <input name="responseMode" type="text" value="page" hidden />
  <input name="x-client-key" type="text" value="Bh1mvuMz/FG9ogSsvOZNQz79Oc+oU7xXkdOLtDm9ASg=" hidden />
  <input name="x-client-name" type="text" value="public" hidden />
  <button class="btn btn-primary">₴ Сплатити за IBAN</button>
</form>

JSON

Content-Type: application/json

Body:

{
  "code": "2882618253",
  "iban": "UA063052990000026008050293936",
  "amount": "128.00",
  "purpose": "Тестова оплата",
  "x-client-key": "Bh1mvuMz/FG9ogSsvOZNQz79Oc+oU7xXkdOLtDm9ASg=",
  "x-client-name": "public"
}

cURL

curl -X POST \
  https://iban.opendatabot.ua/api/invoice \
  -H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=2882618253' \
--data-urlencode 'iban=UA063052990000026008050293936' \
--data-urlencode 'amount=128.00' \
--data-urlencode 'purpose=Тестова оплата' \
--data-urlencode 'x-client-key=Bh1mvuMz/FG9ogSsvOZNQz79Oc+oU7xXkdOLtDm9ASg=' \
--data-urlencode 'x-client-name=public'

Відповіді

За замовчуванням (responseMode: json або без параметра) — HTTP 201 і JSON з даними рахунку:

{
  "id": "690b796522fd059a2ee9846b",
  "url": "https://bank.gov.ua/qr/…",
  "qrcode": "data:image/png;base64,....",
  "code": "2882618253",
  "iban": "UA063052990000026008050293936",
  "amount": 128,
  "purpose": "Тестова оплата"
}

Помилки

400 Bad Request (JSON)

При responseMode: json (або без параметра) API повертає JSON з переліком помилок валідації (поле errors).

{
  "message": "Помилка створення посилання",
  "original": "Validation Error",
  "errors": [
    { "field": "code", "code": "invalid_string", "message": "Невірний формат" }
  ]
}

400 Bad Request (responseMode: page або bank-link)

При responseMode: page або bank-link замість JSON — HTML-сторінка помилки: перелік відсутніх полів (code, iban, amount, purpose), окреме повідомлення для суми 0, перелік полів з невірними значеннями.

Налаштування IBAN

Перегляд і керування рахунками IBAN клієнта (авторизація x-client-key / x-client-name). Рядки створюються автоматично при POST /api/invoice; тут їх можна отримати списком, додати, перейменувати alias або видалити.

iban: формат UA + 27 цифр
code: 8 або 10 цифр (ЄДРПОУ або РНОКПП)
aliasoptional: підпис рахунку в профілі
fileIdoptional: ID лого з POST /api/file (логотип рахунку)
x-client-key: YOUR_X_CLIENT_KEY
x-client-name: YOUR_X_CLIENT_NAME

GET: /api/iban-settings — список
GET: /api/iban-settings/:id
POST: /api/iban-settings — створити { iban, code, alias }
PUT: /api/iban-settings/:id — змінити alias
DELETE: /api/iban-settings/:id

JSON

Content-Type: application/json

Body:

{
  "iban": "UA063052990000026008050293936",
  "code": "2882618253",
  "alias": "Основний рахунок"
}

cURL

# список рахунків клієнта
curl 'https://iban.opendatabot.ua/api/iban-settings' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' -H 'x-client-name: YOUR_X_CLIENT_NAME'

# створити
curl -X POST 'https://iban.opendatabot.ua/api/iban-settings' \
  -H 'Content-Type: application/json' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' -H 'x-client-name: YOUR_X_CLIENT_NAME' \
  -d '{"iban":"UA063052990000026008050293936","code":"2882618253","alias":"Основний рахунок"}'

# перейменувати alias
curl -X PUT 'https://iban.opendatabot.ua/api/iban-settings/690b796522fd059a2ee9846c' \
  -H 'Content-Type: application/json' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' -H 'x-client-name: YOUR_X_CLIENT_NAME' \
  -d '{"alias":"Резервний рахунок"}'

# прив’язати логотип (fileId з POST /api/file)
curl -X PUT 'https://iban.opendatabot.ua/api/iban-settings/690b796522fd059a2ee9846c' \
  -H 'Content-Type: application/json' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' -H 'x-client-name: YOUR_X_CLIENT_NAME' \
  -d '{"fileId":"690b796522fd059a2ee9846d"}'

# видалити
curl -X DELETE 'https://iban.opendatabot.ua/api/iban-settings/690b796522fd059a2ee9846c' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' -H 'x-client-name: YOUR_X_CLIENT_NAME'

Відповіді

HTTP 201 при створенні, 200 для read/update/delete. Список повертає масив у полі ibanSettings. Поле default — лише для читання; logoUrl формується з прив’язаного файлу. Логотип задається полем fileId (ID із POST /api/file) при створенні або через PUT; fileId: null — відв’язати.

{
  "id": "690b796522fd059a2ee9846c",
  "iban": "UA063052990000026008050293936",
  "code": "2882618253",
  "alias": "Основний рахунок",
  "default": false,
  "fileId": "690b796522fd059a2ee9846d",
  "logoUrl": "/uploads/cf/40/45/cf40…f666c460.jpg"
}

Помилки

400 Bad Request

Невірний формат iban при створенні, невідомий fileId, або спроба видалити рядок-замовчування / без iban.

404 Not Found

Рядок не належить клієнту або :id невалідний.

Завантаження логотипу

Завантаження логотипу/фото для рахунків IBAN (multipart/form-data, авторизація x-client-key / x-client-name). Зображення до 5 МБ масштабується до 1024×192 px (2× для Retina) і зберігається як WebP. Повертає fileId, який далі прив’язується до рахунку через POST/PUT /api/iban-settings (поле fileId).

file: зображення логотипу — JPEG, PNG, GIF, WebP, HEIC тощо, до 5 МБ; зберігається як WebP у 2× (до 1024×192 px)
x-client-key: YOUR_X_CLIENT_KEY
x-client-name: YOUR_X_CLIENT_NAME

Endpoint: https://iban.opendatabot.ua/api/file
Method: POST

Тіло запиту

Content-Type: multipart/form-data

Поле file — зображення логотипу (до 5 МБ; зберігається як WebP). Див. таблицю полів вище.

cURL

# завантажити логотип/фото (зображення, до 5 МБ) → fileId; зберігається як WebP
curl -X POST 'https://iban.opendatabot.ua/api/file' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' -H 'x-client-name: YOUR_X_CLIENT_NAME' \
  -F 'file=@logo.png'

# далі прив’язати fileId до рахунку
curl -X PUT 'https://iban.opendatabot.ua/api/iban-settings/690b796522fd059a2ee9846c' \
  -H 'Content-Type: application/json' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' -H 'x-client-name: YOUR_X_CLIENT_NAME' \
  -d '{"fileId":"690b796522fd059a2ee9846d"}'

Відповіді

HTTP 201 і JSON з даними файлу. Поле id — це fileId для прив’язки логотипу до рахунку. Службові поля File (hash, used тощо) не повертаються.

{
  "id": "690b796522fd059a2ee9846d",
  "clientId": "690b796522fd059a2ee98460",
  "fileType": "image/webp",
  "fileName": "iban-logo.webp",
  "fileSize": 12044,
  "uploadUrl": "/uploads/cf/40/45/cf40…f666c460.png"
}

Помилки

400 Bad Request

Файл не завантажено, недозволений тип зображення або розмір понад 5 МБ.

Транзакції

Лента оброблених транзакцій клієнта. Кожен елемент — та сама структура, що й у сповіщенні про оплату (Автоклієнт). Клієнт бачить лише власні записи. Авторизація: заголовки x-client-key / x-client-name.

x-client-key: YOUR_X_CLIENT_KEY
x-client-name: YOUR_X_CLIENT_NAME
offsetoptional: ≥ 0, за замовчуванням 0
limitoptional: 1–100, за замовчуванням 20
dateFromoptional: нижня межа за датою операції (включно)
dateTooptional: верхня межа за датою операції (до кінця дня)
statusoptional: pending | paid | refunded; фільтрує за статусом оплати
autoclientConfigIdoptional: фільтр за одним автоклієнтом (ObjectId)
idoptional: курсор: повертає записи, створені ПІСЛЯ цієї транзакції

Endpoint: https://iban.opendatabot.ua/api/transactions
Method: GET

cURL

# всі транзакції (перша сторінка)
curl 'https://iban.opendatabot.ua/api/transactions' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' \
  -H 'x-client-name: YOUR_X_CLIENT_NAME'

# з фільтром дат
curl 'https://iban.opendatabot.ua/api/transactions?dateFrom=2026-01-01&dateTo=2026-06-30&limit=50' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' \
  -H 'x-client-name: YOUR_X_CLIENT_NAME'

# курсор: записи після конкретної транзакції
curl 'https://iban.opendatabot.ua/api/transactions?id=663f1a2b3c4d5e6f7a8b9c0d' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' \
  -H 'x-client-name: YOUR_X_CLIENT_NAME'

Відповіді

HTTP 200 і JSON з полем count (усього рядків за фільтрами) та items (поточна сторінка):

{
  "count": 142,
  "items": [
    {
      "transactionId": "663f1a...",
      "autoclientConfigId": "6a20...",
      "matches": { "purpose": true, "counterpartyCode": false, "amount": true },
      "invoiceNumber": "20260301-00001",
      "transaction": {
        "date": "2026-03-01T12:00:00.000Z",
        "amount": 150,
        "currency": "UAH",
        "purpose": "Оплата по рахунку № 20260301-00001",
        "iban": "UA063052990000026008050293936",
        "edrpou": "12345678",
        "counterpartyName": "ТОВ \"Компанія\"",
        "counterpartyEdrpou": "87654321",
        "counterpartyAcc": "UA111111110000000000000000000",
        "transactionType": "credit",
        "raw": {}
      },
      "invoice": {
        "id": "690b796522fd059a2ee9846b",
        "amount": 150,
        "purpose": "Оплата по рахунку № 20260301-00001",
        "counterpartyCode": "87654321",
        "code": "2882618253",
        "iban": "UA063052990000026008050293936",
        "createdAt": "2026-02-28T09:00:00.000Z"
      },
      "possibleInvoices": []
    }
  ]
}

Помилки

401 Unauthorized

Відсутній або невірний x-client-key / x-client-name.

500 Internal Server Error

Внутрішня помилка сервера.

Рахунки

Лента QR-рахунків клієнта (ті самі записи, що відображаються у вкладці «Рахунки» профілю). Авторизація: x-client-key / x-client-name.

x-client-key: YOUR_X_CLIENT_KEY
x-client-name: YOUR_X_CLIENT_NAME
offsetoptional: ≥ 0, за замовчуванням 0
limitoptional: 1–100, за замовчуванням 20
dateFromoptional: нижня межа за датою створення рахунку (включно)
dateTooptional: верхня межа за датою створення (до кінця дня)
statusoptional: pending | paid | refunded; фільтрує за статусом оплати
autoclientConfigIdoptional: фільтр за одним автоклієнтом (ObjectId)
idoptional: курсор: повертає записи, створені ПІСЛЯ цього рахунку

Endpoint: https://iban.opendatabot.ua/api/invoices
Method: GET

cURL

# всі рахунки клієнта (перша сторінка)
curl 'https://iban.opendatabot.ua/api/invoices' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' \
  -H 'x-client-name: YOUR_X_CLIENT_NAME'

# з фільтром дат і статусом
curl 'https://iban.opendatabot.ua/api/invoices?dateFrom=2026-01-01&dateTo=2026-06-30&status=paid&limit=50' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' \
  -H 'x-client-name: YOUR_X_CLIENT_NAME'

# тільки рахунки одного автоклієнта
curl 'https://iban.opendatabot.ua/api/invoices?autoclientConfigId=6a20...' \
  -H 'x-client-key: YOUR_X_CLIENT_KEY' \
  -H 'x-client-name: YOUR_X_CLIENT_NAME'

Відповіді

HTTP 200 і JSON з полем count (усього рядків за фільтрами) та items (поточна сторінка):

{
  "count": 142,
  "items": [
    {
      "id": "690b796522fd059a2ee9846b",
      "code": "2882618253",
      "iban": "UA063052990000026008050293936",
      "amount": 128.00,
      "purpose": "Тестова оплата",
      "counterpartyCode": "87654321",
      "createdAt": "2026-03-01T09:00:00.000Z",
      "paymentStatus": "paid",
      "transaction": {
        "id": "663f1a...",
        "amount": 150,
        "currency": "UAH",
        "date": "2026-03-01T12:00:00.000Z"
      }
    }
  ]
}

Помилки

401 Unauthorized

Відсутній або невірний x-client-key / x-client-name.

500 Internal Server Error

Внутрішня помилка сервера.

HTTP статуси помилок

Уважно! Помилки валідації (400) описані в розділі кожного endpoint.

401 Unauthorized

Відсутній заголовок або поле x-client-key / x-client-name у тілі запиту.

{
  "message": "Відсутній параметр x-client-key або x-client-name у заголовку або в тілі запиту."
}

402 Payment Required

Доступ обмежено через заборгованість за виставленими рахунками. У відповіді — перелік рахунків із посиланнями на оплату.

{
  "message": "Доступ заблоковано: потрібна оплата",
  "invoices": [
    {
      "purpose": "Тестова оплата",
      "amount": 128,
      "url": "https://iban.opendatabot.ua/invoice/690b796522fd059a2ee9846b"
    }
  ]
}

403 Forbidden

Невірний x-client-key або x-client-name (клієнт не знайдено або ключ не дійсний).

{
  "message": "Доступ заблоковано: неправильний x-client-key або x-client-name",
  "description": "Перевірте ключі у вашому профілі: https://opendatabot.ua/profile#iban"
}

500 Internal Server Error

Внутрішня помилка сервера.

{
  "message": "Помилка створення посилання",
  "original": "Failed to generate QR code."
}

Посилання на сторінку оплати

Після створення рахунку у відповіді приходить поле id. Підставте його у шлях /invoice/:id— отримаєте посилання на готову сторінку оплати з QR-кодом, сумою, призначенням і кнопками банків. Її можна надіслати клієнту напряму:

https://iban.opendatabot.ua/invoice/:id

Поле url у відповіді — це посилання на застосунок банку (deep-link), а /invoice/:id — повноцінна сторінка оплати на нашому сайті.

QR-код зображення

Якщо підставити id з сформованого рахунку, можно отримати пряме посилання на зображення QR-кода:

https://iban.opendatabot.ua/invoice/:id/qrcode.png

Сповіщення про оплату

Підключіть Автоклієнт — і ми будемо автоматично сповіщати ваш сайт, коли клієнт оплатив рахунок. Так статус замовлення оновлюється сам, без перевірки банківської виписки вручну.

URL свого сервера ви вказуєте в налаштуваннях Автоклієнта. На нього приходить POST з JSON — даними платежу та знайденим рахунком (invoice: null, якщо зіставити не вдалося):

{
  "matches": { "purpose": true, "counterpartyCode": false, "amount": true },
  "invoiceNumber": "20260301-00001",
  "transaction": {
    "date": "2026-03-01T12:00:00.000Z",
    "amount": 150,
    "currency": "UAH",
    "purpose": "Оплата по рахунку № 20260301-00001",
    "iban": "UA063052990000026008050293936",
    "edrpou": "12345678",
    "counterpartyName": "ТОВ \"Компанія\"",
    "counterpartyEdrpou": "87654321",
    "counterpartyAcc": "UA111111110000000000000000000",
    "transactionType": "credit",
    "raw": { }
  },
  "invoice": {
    "id": "663f1a...",
    "amount": 150,
    "purpose": "Оплата по рахунку № 20260301-00001",
    "counterpartyCode": "87654321",
    "code": "12345678",
    "iban": "UA063052990000026008050293936",
    "createdAt": "2026-02-28T09:00:00.000Z"
  },
  "possibleInvoices": []
}

Поле invoiceNumber — номер рахунку, витягнутий з призначення платежу (null, якщо не знайдено).

Об’єкт matches

що саме збіглося між платежем і рахунком

Поле	Тип	Опис
`purpose`	boolean	номер рахунку знайдено в призначенні
`counterpartyCode`	boolean	ЄДРПОУ платника збігається з рахунком
`amount`	boolean	сума збігається (±1 грн)

Об’єкт transaction

дані платежу

Поле	Тип	Опис
`date`	string (ISO 8601)	дата і час платежу
`amount`	number	сума
`currency`	string	UAH, USD або EUR
`purpose`	string	призначення платежу
`iban`	string	IBAN вашого рахунку
`edrpou`	string	ваш ЄДРПОУ
`counterpartyName`	string	назва платника
`counterpartyEdrpou`	string	ЄДРПОУ платника
`counterpartyAcc`	string	IBAN платника
`transactionType`	string	credit — зарахування, debit — списання
`raw`	object	оригінальна відповідь банку (як є)

Об’єкт invoice

знайдений рахунок (null — якщо не зіставили)

Поле	Тип	Опис
`id`	string	ідентифікатор рахунку
`amount`	number	сума
`purpose`	string	призначення
`counterpartyCode`	string	ЄДРПОУ платника
`code`	string	ЄДРПОУ отримувача
`iban`	string	IBAN отримувача
`createdAt`	string (ISO 8601)	дата створення

Масив possibleInvoices

Часткові збіги — інші рахунки, що підійшли частково (наприклад, номер збігся, але сума — ні). Кожен елемент масиву має ту саму структуру, що й коренева відповідь: { matches, transaction, invoice }.

Перевірка підпису

У заголовку Signature — підпис тіла HMAC-SHA256 з вашим x-client-key, щоб ви могли переконатися, що запит справді від нас:

const crypto = require('crypto');

function verifySignature(rawBody, signature, clientKey) {
  const expected = crypto.createHmac('sha256', clientKey).update(rawBody).digest('hex');
  return expected === signature;
}

Чекаємо HTTP 2xx протягом 10 секунд. Якщо не відповіли — повторимо ще 2 рази (~2с і ~4с).

Часті запитання

Усе, що потрібно знати про оплату за IBAN від НБУ.

За кожен згенерований рахунок стягується лише 0.42 ₴. Для тестування можна використовувати публічний ключ без реєстрації.

Скопіюйте HTML форму з прикладу вище та додайте на свій сайт. Також можна використовувати cURL або JSON запити до /api/invoice. API повертає QR-код або посилання, які можна розмістити в email, документах або на сайті.

Обов'язкові поля: code і iban — або замість них ibanSettingId (ID налаштування з профілю, підставляє і code, і iban автоматично). Плюс amount і purpose. Для ідентифікації додайте x-client-key та x-client-name.

За замовчуванням (responseMode: json) API повертає JSON з полями: id рахунку, url для оплати через банк, qrcode у форматі data URI, а також дані рахунку. responseMode: page — редирект на сторінку рахунку; bank-link — редирект на посилання НБУ для відкриття застосунку банку; qr-png — PNG-зображення QR напряму.

Після створення рахунку використовуйте пряме посилання /invoice/:id/qrcode.png. Зображення можна вставити в email, PDF або на сайт як звичайний <img> тег.

OpenCart 2.3 / 3 / 4

WordPress WooCommerce

KeyCRM

SalesDrive

Форма POST запиту

Або використовуйте ibanSettingId

Створити рахунок

HTML приклад

JSON

cURL

Відповіді

Помилки

400 Bad Request (JSON)

400 Bad Request (responseMode: page або bank-link)

Налаштування IBAN

JSON

cURL

Відповіді

Помилки

400 Bad Request

404 Not Found

Завантаження логотипу

Тіло запиту

cURL

Відповіді

Помилки

400 Bad Request

Транзакції

cURL

Відповіді

Помилки

401 Unauthorized

500 Internal Server Error

Рахунки

cURL

Відповіді

Помилки

401 Unauthorized

500 Internal Server Error

HTTP статуси помилок

401 Unauthorized

402 Payment Required

403 Forbidden

500 Internal Server Error

Посилання на сторінку оплати

QR-код зображення

Сповіщення про оплату

Об’єкт matches

Об’єкт transaction

Об’єкт invoice

Масив possibleInvoices

Перевірка підпису

Скільки коштує використання API?

Як інтегрувати QR IBAN оплати у свій сайт?

Які поля потрібні для створення рахунку через API?

Що повертає API у відповіді?

Як отримати зображення QR-коду?