ibanlink.com.ua

API ibanlink

Ссылки на оплату на ваш IBAN прямо из CRM, сайта или бота. Один запрос, и клиент получает страницу, с которой платит в своем банке.

Быстрый старт

  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), суммы строкой с двумя знаками после запятой.
POST/api/v1/links
ПолеОписание
amountСумма в гривнах, от 1 до 1 000 000. Обязательно.
purposeНазначение платежа, 3–140 символов. Обязательно.
external_idВаш номер заказа. Повторный запрос с тем же номером и данными вернет ту же ссылку (200), с другими данными получите 409.
expires_in_daysСрок действия, 1–365 дней. Без него ссылка бессрочная. По истечении срока клиент увидит «Ссылка больше не действует».
return_urlАдрес вашего сайта (http или https), куда вернуть плательщика. На странице оплаты будет кнопка «Вернуться на ваш-сайт».
page_idСтраница с реквизитами. Если такая страница одна, можно не указывать.
titleНазвание для вас и заголовок на странице оплаты.
GET/api/v1/links?status=active&limit=20&before_id=…&external_id=…

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

GET/api/v1/links/{id}

Ссылка со статистикой, opened_at (клиент впервые открыл), bank_clicked_at (впервые нажал кнопку банка) и paid_at (оплата найдена в выписке вашего банка или отмечена в кабинете; тогда status = paid).

POST/api/v1/links/{id}/disable
POST/api/v1/links/{id}/enable

Выключить и включить. DELETE /api/v1/links/{id} работает так же, как disable: история сохраняется.

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

Страницы и профиль

GET/api/v1/pages

Ваши страницы: id, адрес, работает ли (published: есть реквизиты и страница не снята), заполнены ли реквизиты.

GET/api/v1/me

Тариф, до какой даты действует, лимит и сколько ссылок создано в этом месяце.

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

Задайте 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 грн"}}
Код HTTPcodeЧто произошло
401unauthorized, invalid_keyНет ключа, ключ неверный или отозван.
403plan_required, limit_reached, account_inactiveТариф без API или вебхуков, исчерпан лимит ссылок, аккаунт недоступен.
404not_found, page_not_foundНет такой ссылки или страницы в вашем аккаунте.
409page_not_ready, external_id_conflictСтраница без полных реквизитов или снята администратором; номер заказа уже занят другой ссылкой.
422validation, invalid_amount, invalid_purpose, page_requiredПроверьте поля; в fields указано, какие именно.
429rate_limitedБольше 120 запросов в минуту.

Вопросы по интеграции пишите на info@ibanlink.com.ua.

Зарегистрироваться бесплатно Войти