API ibanlink
Ссылки на оплату на ваш IBAN прямо из CRM, сайта или бота. Один запрос, и клиент получает страницу, с которой платит в своем банке.
Быстрый старт
- Тариф «Старт» или «Бизнес», страница с реквизитами.
- Кабинет → «API и вебхуки» → «Создать ключ».
- Запрос:
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.