Відкрите API

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

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

code

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

iban

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

amount

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

purpose

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

x-client-key

AdRq49C7q4hco9vfqZ89oa0leRUBCzXtP3SZJikWr+0=

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="AdRq49C7q4hco9vfqZ89oa0leRUBCzXtP3SZJikWr+0=" 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=AdRq49C7q4hco9vfqZ89oa0leRUBCzXtP3SZJikWr+0=' \
--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": "AdRq49C7q4hco9vfqZ89oa0leRUBCzXtP3SZJikWr+0=",
  "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