Відкрите API

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

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

code

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

iban

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

amount

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

purpose

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

x-client-key

PPTUELzqxMjeIrLN1iqTPvQlMQoh54C5pup5K4fUFNk=

x-client-name

public

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="PPTUELzqxMjeIrLN1iqTPvQlMQoh54C5pup5K4fUFNk=" 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>

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=PPTUELzqxMjeIrLN1iqTPvQlMQoh54C5pup5K4fUFNk=' \
--data-urlencode 'x-client-name=public'

JSON приклад

Endpoint

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

Method

POST

Content-Type

application/json

Body:

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

Відповідь

Якщо redirect=true — користувач буде перенаправлений на сторінку рахунку (/invoice/:id). Інакше API поверне JSON з даними рахунку.

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

Відповіді з помилками

При помилці (невірний клієнт, помилка валідації або сервера) API повертає JSON з HTTP статусом 4xx або 5xx. Якщо в запиті redirect=true , користувач побачить сторінку помилки замість JSON.

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

400 Bad Request

Помилка валідації (невірний code, iban, amount або purpose).

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

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с).