Merchant API
Автентифікація та запити на перевірку для сайтів і інтернет-магазинів.
Merchant API розміщено під /api/v1/merchant/. Кожен виклик передає API-ключ організації в заголовку X-Api-Key. Ключі створюються в бізнес-кабінеті в розділі API-ключі; ключ показується один раз, при створенні.
Є два режими ключів: ключі va_test_… повертають кожен запит одразу схваленим і ніколи не доходять до реальних покупців; ключі va_live_… — для продакшену.
Перевірка ключа
GET /api/v1/merchant/ping
X-Api-Key: va_live_…
Повертає ok, назву вашої організації, режим ключа mode і публічні посилання links (сайт і сторінки в сторах).
Створення запиту на перевірку
POST /api/v1/merchant/verify-requests
X-Api-Key: va_live_…
Content-Type: application/json
{ "external_reference": "order-10432", "callback_url": "https://shop.example/verifage/callback" }
Обидва поля необов’язкові. Відповідь містить:
| Поле | Значення |
|---|---|
id |
Публічний id запиту, використовується в GET і в колбеку |
public_code |
Короткий код, який покупець може ввести в додатку |
qr_url |
Зображення QR, що відкриває запит у додатку |
app_url |
Універсальне посилання для кнопки на телефоні |
status |
pending, approved, denied або expired |
verified |
true після схвалення, інакше false |
expires_at |
72 години після створення |
Читання запиту
GET /api/v1/merchant/verify-requests/{id}
Опитуйте цей ендпоінт, поки покупець підтверджує, або покладайтесь на колбек. Опитування обмежене; раз на 2–3 секунди цілком достатньо.
Помилки
API використовує стандартні HTTP-коди: 401 для відсутнього чи відкликаного ключа, 404 для запиту іншої організації, 422 для невалідних полів, 429 при перевищенні ліміту. Тіло — JSON із полем message.