Відкрите API

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

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

code

8 або 10 цифр (ЄДРПОУ або РНОКПП)

iban

формат UA + 27 цифр

amount

сума у гривнях (рядок з двома знаками після коми)

purpose

призначення платежу (рядок)

x-client-key

wGTQ9xhypb8aG8eGDUWepsfMcEVtnjgE0AzmxJ1+o9o=

x-client-name

public

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

Створює рахунок QR IBAN. Без redirect=true повертає JSON; з redirect=true — перенаправляє на сторінку рахунку (/invoice/:id).

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="x-client-key" type="text" value="wGTQ9xhypb8aG8eGDUWepsfMcEVtnjgE0AzmxJ1+o9o=" hidden />
  <input name="x-client-name" type="text" value="public" hidden />
  <input name="redirect" type="text" value="true" 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": "wGTQ9xhypb8aG8eGDUWepsfMcEVtnjgE0AzmxJ1+o9o=",
  "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=wGTQ9xhypb8aG8eGDUWepsfMcEVtnjgE0AzmxJ1+o9o=' \
--data-urlencode 'x-client-name=public'

Відповіді

Якщо redirect=true — HTTP 302 на /invoice/:id. Інакше 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)

Без redirect=true API повертає JSON з переліком помилок валідації (поле errors).

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

400 Bad Request (redirect=true)

З redirect=true замість JSON — HTML-сторінка помилки: перелік відсутніх полів (code, iban, amount, purpose), окреме повідомлення для суми 0, перелік полів з невірними значеннями.

Посилання для відкриття мобільного застосунку для оплати

Ті самі поля, що й для POST /api/invoice. Після POST з мобільного — HTTP 302 на посилання НБУ; телефон зазвичай відкриває застосунок банку з уже заповненими реквізитами.

Endpoint

https://iban.opendatabot.ua/api/bank-link

Method

POST

HTML приклад

<form action="https://iban.opendatabot.ua/api/bank-link" 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="x-client-key" type="text" value="wGTQ9xhypb8aG8eGDUWepsfMcEVtnjgE0AzmxJ1+o9o=" hidden />
  <input name="x-client-name" type="text" value="public" hidden />
  <button class="btn btn-primary">₴ Сплатити в банку</button>
</form>

JSON

Content-Type

application/json

Body:

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

cURL

curl -X POST \
  https://iban.opendatabot.ua/api/bank-link \
  -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=wGTQ9xhypb8aG8eGDUWepsfMcEVtnjgE0AzmxJ1+o9o=' \
--data-urlencode 'x-client-name=public'

Відповіді

HTTP 302 Found — Location: посилання НБУ (bank.gov.ua/qr/…); браузер відкриває застосунок банку.

Помилки

400 Bad Request

Завжди HTML-сторінка помилки (не JSON): перелік відсутніх полів, окреме повідомлення для суми 0, перелік полів з невірними значеннями.

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

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

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: wGTQ9xhypb8aG8eGDUWepsfMcEVtnjgE0AzmxJ1+o9o=' -H 'x-client-name: public'

# створити
curl -X POST 'https://iban.opendatabot.ua/api/iban-settings' \
  -H 'Content-Type: application/json' \
  -H 'x-client-key: wGTQ9xhypb8aG8eGDUWepsfMcEVtnjgE0AzmxJ1+o9o=' -H 'x-client-name: public' \
  -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: wGTQ9xhypb8aG8eGDUWepsfMcEVtnjgE0AzmxJ1+o9o=' -H 'x-client-name: public' \
  -d '{"alias":"Новий підпис"}'

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

Відповіді

HTTP 201 при створенні, 200 для read/update/delete. Список повертає масив у полі ibanSettings. Поля default і logoUrl — лише для читання (логотип задається завантаженням у кабінеті).

{
  "id": "690b796522fd059a2ee9846c",
  "iban": "UA063052990000026008050293936",
  "code": "2882618253",
  "alias": "Основний",
  "default": false,
  "logoUrl": null
}

Помилки

400 Bad Request

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

404 Not Found

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

409 Conflict

Такий рядок у клієнта вже існує (унікальна комбінація clientId + iban + code + alias). Може виникати і при зміні alias.

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."
}

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

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

Об’єкт transaction

дані платежу

Об’єкт invoice

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

Масив 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с).