ArbiPayment REST API
API дозволяє вашій CRM, інтернет-магазину чи боту автоматично створювати платіжні посилання за IBAN: обираєте збережені реквізити, вказуєте суму та призначення — отримуєте посилання на сторінку оплати з QR-кодом НБУ.
Посилання, створені через API, зʼявляються у вашому кабінеті в розділі «Мої посилання» з позначкою API — ними можна керувати так само, як і створеними вручну.
https://arbipayment.online/api/v1JSON, UTF-8RFC 3339, UTCUAHЯк почати
- Зареєструйтесь і додайте реквізити у розділі «Мої реквізити» (або через POST /requisites).
- У кабінеті відкрийте API Токен і створіть токен.
- Викличте POST /links та віддайте клієнту поле
urlз відповіді.
Автентифікація
Кожен запит має містити токен у заголовку Authorization за схемою Bearer:
Authorization: Bearer ap_live_9f3c1a…
Як альтернативу можна передати заголовок X-API-Token: ap_live_9f3c1a…. Токен у query-рядку не приймається.
Без токена або з недійсним токеном API повертає 401 Unauthorized.
Відповіді та помилки
Успішні відповіді повертають обʼєкт ресурсу. Списки — обʼєкт з полями data (масив) і meta (пагінація):
{
"data": [ … ],
"meta": { "page": 1, "per_page": 20, "total": 57, "total_pages": 3 }
}
Помилки мають єдиний формат. Поле field присутнє, якщо помилка стосується конкретного поля запиту:
{
"error": {
"code": "validation_error",
"message": "Вкажіть призначення платежу",
"field": "purpose"
}
}
| HTTP | code | Коли |
|---|---|---|
| 200 | — | Успішний запит |
| 201 | — | Ресурс створено; заголовок Location містить його адресу |
| 204 | — | Ресурс видалено, тіло відповіді порожнє |
| 400 | invalid_json | Тіло не є JSON-обʼєктом |
| 400 | validation_error | Передано невідоме поле (див. field) |
| 401 | unauthorized | Токен відсутній, недійсний або відкликаний |
| 404 | not_found | Ресурс не існує або належить іншому користувачу |
| 405 | method_not_allowed | Метод не підтримується; див. заголовок Allow |
| 415 | unsupported_media_type | Content-Type не application/json |
| 422 | validation_error | Значення поля некоректне |
| 429 | rate_limited | Перевищено ліміт запитів; див. Retry-After |
| 500 | internal_error | Помилка на нашому боці — повторіть запит пізніше |
Ліміти
- 120 запитів на хвилину на один токен; при перевищенні —
429із заголовкомRetry-After: 60. - До 10 токенів на акаунт.
- Розмір тіла запиту — до 64 КБ.
- Пагінація:
per_pageвід 1 до 100 (за замовчуванням 20).
GET /me
Перевірка токена: повертає власника і назву токена.
curl https://arbipayment.online/api/v1/me \
-H "Authorization: Bearer $TOKEN"
{
"user": { "id": 7, "name": "Олена", "email": "olena@example.com" },
"token": { "id": 3, "name": "Інтернет-магазин", "prefix": "ap_live_9f3c1a", "created_at": "2026-11-04T09:12:00Z" }
}
GET /requisites
Список реквізитів отримувача. id звідси передається як requisite_id при створенні посилання.
Query-параметри
| Параметр | Тип | Опис |
|---|---|---|
status | string | active або inactive. Без параметра — усі |
q | string | Пошук за назвою, ЄДРПОУ/РНОКПП, IBAN, банком |
page, per_page | integer | Пагінація |
curl "https://arbipayment.online/api/v1/requisites?status=active" \
-H "Authorization: Bearer $TOKEN"
{
"data": [
{
"id": 12,
"name": "Кавʼярня «Зерно»",
"public_name": "Кавʼярня «Зерно»",
"legal_name": "ФОП Коваленко Олена Петрівна",
"tax_id": "3153821259",
"iban": "UA263534890000026008111113966",
"bank_name": "АТ КБ «ПриватБанк»",
"active": true,
"created_at": "2026-10-01T08:00:00Z",
"updated_at": "2026-10-01T08:00:00Z"
}
],
"meta": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }
}
GET /requisites/{id}
Один запис реквізитів. Якщо реквізити не існують або належать іншому користувачу — 404.
POST /requisites
Створює реквізити отримувача. Відповідь — 201 Created з обʼєктом реквізитів.
| Поле | Тип | Опис | |
|---|---|---|---|
legal_name | string | обовʼязкове | Юридична назва ФОП / ТОВ — потрапляє в QR-код НБУ |
tax_id | string | обовʼязкове | ЄДРПОУ (8 цифр) або РНОКПП (10 цифр) |
iban | string | обовʼязкове | UA + 27 цифр; пробіли ігноруються |
public_name | string | Публічна назва для кабінету |
POST /links
Створює платіжне посилання за обраними реквізитами. Відповідь — 201 Created з обʼєктом посилання; поле url надсилайте клієнту.
| Поле | Тип | Опис | |
|---|---|---|---|
requisite_id | integer | обовʼязкове | ID активних реквізитів з GET /requisites |
purpose | string | обовʼязкове | Призначення платежу, до 140 символів |
amount | number | null | Сума в гривнях: від 0.01 до 999999, до 2 знаків після крапки. Не передано або null — суму вводить платник | |
buyer_note | string | Нотатка, яку побачить платник, до 70 символів | |
private_note | string | Внутрішня нотатка (платник не бачить), до 512 символів. Зручно для номера замовлення | |
expires_at | string | Термін дії, RFC 3339: 2026-12-31T23:59:00+02:00 | |
expires_in | integer | Альтернатива expires_at: термін дії в секундах від зараз (60 … 31536000) |
curl -X POST https://arbipayment.online/api/v1/links \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"requisite_id": 12,
"amount": 1500.50,
"purpose": "Оплата замовлення №1024",
"buyer_note": "Дякуємо за покупку!",
"private_note": "order_id=1024",
"expires_in": 86400
}'
Відповідь 201 Created, Location: /api/v1/links/345
{
"id": 345,
"public_id": "019a4f2e-7c1d-7b8e-9a10-3f2c4d5e6f70",
"url": "https://arbipayment.online/qr/019a4f2e-7c1d-7b8e-9a10-3f2c4d5e6f70",
"nbu_qr_url": "https://qr.bank.gov.ua/QkNECjAwMgox…",
"status": "active",
"amount": 1500.5,
"amount_type": "fixed",
"currency": "UAH",
"purpose": "Оплата замовлення №1024",
"buyer_note": "Дякуємо за покупку!",
"private_note": "order_id=1024",
"expires_at": "2026-11-05T09:12:00Z",
"favorite": false,
"source": "api",
"requisite": {
"id": 12,
"name": "Кавʼярня «Зерно»",
"public_name": "Кавʼярня «Зерно»",
"legal_name": "ФОП Коваленко Олена Петрівна",
"tax_id": "3153821259",
"iban": "UA263534890000026008111113966",
"bank_name": "АТ КБ «ПриватБанк»"
},
"created_at": "2026-11-04T09:12:00Z",
"updated_at": "2026-11-04T09:12:00Z"
}
Приклад помилки валідації — 422:
{ "error": { "code": "validation_error", "message": "Реквізити деактивовані — активуйте їх у кабінеті", "field": "requisite_id" } }
GET /links
Список посилань, від нових до старих. Включає і створені в кабінеті, і через API.
| Параметр | Тип | Опис |
|---|---|---|
source | string | api або web |
q | string | Пошук за призначенням, нотатками, IBAN, ЄДРПОУ, public_id |
iban | string | Точний IBAN отримувача |
tax_id | string | Точний ЄДРПОУ / РНОКПП |
favorite | boolean | true — лише обрані |
created_from, created_to | date | Діапазон дати створення, YYYY-MM-DD включно |
page, per_page | integer | Пагінація |
curl "https://arbipayment.online/api/v1/links?source=api&q=order_id%3D1024" \
-H "Authorization: Bearer $TOKEN"
GET /links/{id}
Одне посилання за id. Поле status показує, чи діє посилання (active) або термін вийшов (expired).
PATCH /links/{id}
Часткове оновлення: передавайте лише поля, які змінюються (ті самі, що в POST /links). Щоб прибрати значення, передайте null:
"amount": null— суму вводитиме платник;"expires_at": null— посилання стане безстроковим;"buyer_note": null/"private_note": null— видалити нотатку.
URL посилання (public_id) при оновленні не змінюється. Якщо термін дії посилання вже минув, разом зі змінами передайте новий expires_at або null.
curl -X PATCH https://arbipayment.online/api/v1/links/345 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "amount": 1750, "expires_at": null }'
DELETE /links/{id}
Видаляє посилання; сторінка оплати перестає відкриватися. Відповідь — 204 No Content.
curl -X DELETE https://arbipayment.online/api/v1/links/345 \
-H "Authorization: Bearer $TOKEN"
Обʼєкт посилання
| Поле | Тип | Опис |
|---|---|---|
id | integer | Ідентифікатор для запитів API |
public_id | string | UUID у публічному URL |
url | string | Сторінка оплати для клієнта |
nbu_qr_url | string | Посилання стандарту НБУ (QR формату 002) — можна закодувати у власний QR-код |
status | string | active | expired |
amount | number | null | Фіксована сума або null |
amount_type | string | fixed — сума задана; payer — вводить платник |
currency | string | Завжди UAH |
purpose | string | Призначення платежу |
buyer_note, private_note | string | null | Нотатки |
expires_at | string | null | Термін дії (UTC) |
favorite | boolean | Позначено як обране в кабінеті |
source | string | api | web — звідки створено |
requisite | object | Реквізити отримувача |
created_at, updated_at | string | RFC 3339, UTC |
Приклади коду
<?php
$ch = curl_init('https://arbipayment.online/api/v1/links');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('ARBIPAY_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'requisite_id' => 12,
'amount' => 1500.50,
'purpose' => 'Оплата замовлення №1024',
'private_note' => 'order_id=1024',
], JSON_UNESCAPED_UNICODE),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status === 201) {
header('Location: ' . $body['url']); // відправити клієнта на оплату
} else {
error_log($body['error']['message'] ?? 'API error');
}
const res = await fetch('https://arbipayment.online/api/v1/links', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ARBIPAY_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
requisite_id: 12,
amount: 1500.5,
purpose: 'Оплата замовлення №1024',
expires_in: 3600,
}),
});
const body = await res.json();
if (!res.ok) throw new Error(body.error.message);
console.log(body.url); // посилання на оплату
import os
import requests
resp = requests.post(
"https://arbipayment.online/api/v1/links",
headers={"Authorization": f"Bearer {os.environ['ARBIPAY_TOKEN']}"},
json={
"requisite_id": 12,
"amount": 1500.50,
"purpose": "Оплата замовлення №1024",
},
timeout=10,
)
data = resp.json()
if resp.status_code != 201:
raise RuntimeError(data["error"]["message"])
print(data["url"]) # посилання на оплату