Інтегруйте вашу програму лояльності з міжнародною системою бонусних транзакцій KvitkaCard
v1.0 • REST API • JSON
Огляд
Базовий URL
https://www.kvitkacard.com/api/v1
Авторизація
Кожен запит повинен містити ваш унікальний API-токен у тілі запиту (поле api_token). Токен видається при реєстрації вашого бізнесу в системі KvitkaCard.
Формат даних
Усі запити та відповіді використовують формат JSON. Встановіть заголовок Content-Type: application/json.
Як працює система
Кожна операція складається з двох етапів. Спочатку — ініціація (перевірка лімітів, конвертація), потім — підтвердження. Бали з рахунку користувача знімаються або зараховуються ТІЛЬКИ після успішної відповіді на запит підтвердження.
Ліміти
Мінімальна сума операції: 1 KvitkaCoin. Максимальна: 1000 KvitkaCoins. Конвертація відбувається автоматично на основі валюти та мультиплікатора вашого бізнесу.
Rate limiting
Максимум 60 запитів за 60 секунд на один API-токен.
Важливо:
НЕ знімайте бали з рахунку користувача до отримання успішної відповіді на withdraw/confirm.
НЕ зараховуйте бали до отримання успішної відповіді на deposit/confirm.
Код транзакції — одноразовий. Після успішного deposit/confirm код більше не можна використати.
При відхиленні депозиту (deposit/reject) код залишається активним — користувач може ввести його в іншому бізнесі.
POST
Крок 1: Ініціація зняття
POST https://www.kvitkacard.com/api/v1/withdraw/init.php
Надсилає суму балів для перевірки. Система конвертує бали в KvitkaCoins та перевіряє ліміти. Операція створюється зі статусом initiated. На цьому етапі бали з рахунку користувача НЕ знімаються.
POST https://www.kvitkacard.com/api/v1/withdraw/confirm.php
Підтверджує операцію. Система переводить її в статус holding та генерує унікальний 16-значний код транзакції. ТІЛЬКИ після отримання успішної відповіді на цей запит ви можете зняти бали з рахунку користувача.
Важливо: НЕ знімайте бали з рахунку користувача до отримання успішної відповіді на withdraw/confirm.
Запит
Параметр
Опис
api_tokenstringОбов'язковий
Ваш унікальний API-токен
operation_idintegerОбов'язковий
ID операції (отримано на кроці 1)
Приклад відповіді
{
"success": true,
"operation_id": 1,
"transaction_code": "4829173650284719",
"amount_kc": 176.32,
"status": "holding",
"message": "Points are now held by KvitkaCard. You may now deduct points from user account."
}
POST
Крок 1: Перевірка коду
POST https://www.kvitkacard.com/api/v1/deposit/init.php
Перевіряє код транзакції та конвертує суму в бали вашої програми лояльності. Поверне кількість балів, яку можна зарахувати. Перевірте свої внутрішні ліміти перед підтвердженням.
Запит
Параметр
Опис
api_tokenstringОбов'язковий
Ваш унікальний API-токен
transaction_codestringОбов'язковий
Код транзакції (16 цифр)
Приклад відповіді
{
"success": true,
"operation_id": 1,
"transaction_code": "4829173650284719",
"amount_kc": 176.32,
"points_amount": 88.16,
"status": "pending_deposit",
"message": "Check your limits. Points amount shown is how many points will be credited."
}
POST
Крок 2: Підтвердження зарахування
POST https://www.kvitkacard.com/api/v1/deposit/confirm.php
Підтверджує зарахування. Операція завершується зі статусом completed. ТІЛЬКИ після отримання успішної відповіді ви можете зарахувати бали на рахунок користувача.
Важливо: НЕ зараховуйте бали до отримання успішної відповіді на deposit/confirm.
Запит
Параметр
Опис
api_tokenstringОбов'язковий
Ваш унікальний API-токен
operation_idintegerОбов'язковий
ID операції (отримано на кроці 1)
transaction_codestringОбов'язковий
Код транзакції (16 цифр)
Приклад відповіді
{
"success": true,
"operation_id": 1,
"transaction_code": "4829173650284719",
"points_amount": 88.16,
"status": "completed",
"message": "Operation completed successfully. You may now credit points to user account."
}
POST
Альтернатива: Відхилення зарахування
POST https://www.kvitkacard.com/api/v1/deposit/reject.php
Якщо ваші внутрішні ліміти не дозволяють прийняти таку суму балів — надішліть запит відхилення. Операція залишиться в статусі holding, а код транзакції залишиться активним — користувач зможе використати його в іншому бізнесі.
Запит
Параметр
Опис
api_tokenstringОбов'язковий
Ваш унікальний API-токен
operation_idintegerОбов'язковий
ID операції (отримано на кроці 1)
transaction_codestringОбов'язковий
Код транзакції (16 цифр)
reasonstringОпціональний
Причина відхилення (для логування)
Коди помилок
У разі помилки API повертає JSON з полями success: false, error_code та message.