API ibanlink

Швидкий старт

1. Тариф «Старт» чи «Бізнес», сторінка з реквізитами.
2. Кабінет → «API і вебхуки» → «Створити ключ».
3. Запит:

curl -X POST https://ibanlink.com.ua/api/v1/links \
  -H "Authorization: Bearer il_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 1250, "purpose": "Оплата замовлення 125", "external_id": "125", "expires_in_days": 7}'

Відповідь 201:

{
  "id": 481, "url": "https://ibanlink.com.ua/p/Xk3pQ9aB2c", "status": "active",
  "amount": "1250.00", "currency": "UAH", "purpose": "Оплата замовлення 125", "external_id": "125",
  "created_at": "2026-10-11T12:00:00+00:00", "expires_at": "2026-10-18T12:00:00+00:00",
  "opened_at": null, "bank_clicked_at": null, "paid_at": null, "paid_amount": null,
  "nbu_url": "https://qr.bank.gov.ua/QkNE...", "qr_svg_url": "https://ibanlink.com.ua/p/Xk3pQ9aB2c/qr.svg"
}

Надішліть клієнту url. На телефоні він обере банк і підтвердить переказ, на компʼютері відсканує QR. Гроші йдуть напряму на ваш рахунок; ibanlink платіж не бачить і коштів не торкається.

Ключ і ліміти

• Заголовок Authorization: Bearer <ключ>. Ключ показуємо один раз; відкликати можна в кабінеті.
• До 120 запитів за хвилину на ключ, далі 429.
• Нові посилання рахуються в місячний ліміт тарифу (разом зі створеними в кабінеті).
• Усі часи у форматі ISO 8601 (UTC), суми рядком із двома знаками після коми.

Посилання

Поле	Опис
amount	Сума в гривнях, від 1 до 1 000 000. Обовʼязково.
purpose	Призначення платежу, 3–140 знаків. Обовʼязково.
external_id	Ваш номер замовлення. Повторний запит із тим самим номером і даними поверне те саме посилання (200), з іншими даними отримаєте 409.
expires_in_days	Строк дії, 1–365 днів. Без нього посилання безстрокове. Після строку клієнт побачить «Посилання більше не діє».
return_url	Адреса вашого сайту (http або https), куди повернути платника. На сторінці оплати буде кнопка «Повернутися на ваш-сайт».
page_id	Сторінка з реквізитами. Якщо така сторінка одна, можна не вказувати.
title	Назва для вас і заголовок на сторінці оплати.

Список, новіші спершу. status: all, active, paid, disabled, expired. Для наступної сторінки передайте before_id з поля next_before_id. paid_from (ISO 8601, наприклад 2026-10-12T09:00:00Z): лише оплачені з цього часу, зручно для регулярної перевірки оплат. У кожному посиланні є stats: перегляди, відвідувачі, переходи в банк, покази QR.

Посилання зі статистикою, opened_at (клієнт уперше відкрив) bank_clicked_at (уперше натиснув кнопку банку) і paid_at (оплату знайдено у виписці вашого банку чи позначено в кабінеті; тоді status = paid).

Вимкнути й увімкнути. DELETE /api/v1/links/{id} діє так само, як disable: історія лишається.

qr_svg_url: QR для друку чи вашого сайту. nbu_url: пряме платіжне посилання НБУ без нашої сторінки.

Сторінки й профіль

Ваші сторінки: id, адреса, чи працює (published: є реквізити й сторінку не знято), чи заповнені реквізити.

Тариф, до коли діє, ліміт і скільки посилань створено цього місяця.

Вебхуки «Бізнес»

Задайте https-адресу в кабінеті або через PUT /api/v1/webhook з {"url": "https://…", "events": ["link.opened", "link.bank_clicked", "link.paid"]}. Секрет підпису повертаємо один раз, при створенні. Новий секрет: POST /api/v1/webhook/rotate-secret, перевірка: POST /api/v1/webhook/test.

Подія	Коли
link.opened	Клієнт уперше відкрив посилання (прев'ю месенджерів не рахуються).
link.bank_clicked	Клієнт уперше натиснув кнопку свого банку: перейшов оплачувати.
link.paid	Оплату знайдено у виписці підключеного банку (кабінет → «Банк») або позначено вручну. У data.payment: сума, час, confirmed (auto чи manual) та імʼя платника з виписки.

POST https://ваша-адреса
X-Ibanlink-Event: link.bank_clicked
X-Ibanlink-Signature: t=1791302400,v1=5f0c…

{"id": "evt_77", "event": "link.bank_clicked", "created_at": "…", "data": {"link": { …як у відповіді API… }}}

Відповідайте кодом 2xx за 10 секунд. Інакше повторимо через 1, 5, 30 хв, 2 й 6 год. Переадресації не виконуємо. Адреса має вести на публічний сервер.

Перевірка підпису: HMAC-SHA256 від рядка "<t>.<тіло запиту як є>" вашим секретом має дорівнювати v1; відкидайте запити, де t старше 5 хвилин.

# Python
import hmac, hashlib, time
def valid(secret, header, body: bytes):
    parts = dict(p.split("=", 1) for p in header.split(","))
    mac = hmac.new(secret.encode(), parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300

// Node.js
const crypto = require('crypto');
function valid(secret, header, rawBody) {
  const p = Object.fromEntries(header.split(',').map(x => x.split('=')));
  const mac = crypto.createHmac('sha256', secret).update(p.t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(p.v1)) && Math.abs(Date.now() / 1000 - p.t) < 300;
}

// PHP
function valid($secret, $header, $rawBody) {
  parse_str(str_replace(',', '&', $header), $p);
  $mac = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
  return hash_equals($mac, $p['v1']) && abs(time() - (int)$p['t']) < 300;
}

Помилки

{"error": {"code": "invalid_amount", "message": "Сума має бути щонайменше 1 грн"}}

Код HTTP	code	Що сталося
401	unauthorized, invalid_key	Немає ключа, ключ хибний чи відкликаний.
403	plan_required, limit_reached, account_inactive	Тариф без API чи вебхуків, вичерпано ліміт посилань, акаунт недоступний.
404	not_found, page_not_found	Немає такого посилання чи сторінки у вашому акаунті.
409	page_not_ready, external_id_conflict	Сторінка без повних реквізитів або знята адміністратором; номер замовлення вже зайнятий іншим посиланням.
422	validation, invalid_amount, invalid_purpose, page_required	Перевірте поля; у fields указано, які саме.
429	rate_limited	Понад 120 запитів за хвилину.

Питання щодо інтеграції пишіть на info@ibanlink.com.ua.