KvitkaCard KvitkaCard
Українська English

Документація API

Інтегруйте вашу програму лояльності з міжнародною системою бонусних транзакцій 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. На цьому етапі бали з рахунку користувача НЕ знімаються.

Запит

ПараметрОпис
api_tokenstringОбов'язковийВаш унікальний API-токен
amountnumberОбов'язковийКількість балів для переведення
Приклад запиту
{
  "api_token": "your_api_token_here",
  "amount": 100
}

Відповідь

ПолеОпис
successbooleanСтатус запиту (true/false)
operation_idintegerID операції (отримано на кроці 1)
amount_kcnumberСума в KvitkaCoins після конвертації
statusstringСтатус операції
messagestringПояснення результату
Приклад відповіді
{
  "success": true,
  "operation_id": 1,
  "amount_points": 100,
  "amount_kc": 176.32,
  "status": "initiated",
  "message": "Operation initiated. Send confirm request to proceed. Do NOT deduct points yet."
}

Приклад на PHP

<?php
// Withdraw Init — Step 1
$url = 'https://www.kvitkacard.com/api/v1/withdraw/init.php';

$data = [
    'api_token' => 'your_api_token_here',
    'amount'    => 100
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Save operation_id for Step 2
$operation_id = $response['operation_id'];
?>
POST

Крок 2: Підтвердження зняття

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.
КодHTTPОпис
AUTH_MISSING401API token not provided
AUTH_INVALID401Invalid API token
CLIENT_INACTIVE403Client account is paused or blocked
CLIENT_NO_CURRENCY403Client currency not configured
INVALID_AMOUNT400Amount must be greater than 0
UNDER_LIMIT400Amount below minimum (1 KC)
OVER_LIMIT400Amount above maximum (1000 KC)
INVALID_OPERATION400Invalid operation_id
OPERATION_NOT_FOUND404Operation not found
OPERATION_FORBIDDEN403Operation belongs to another client
INVALID_STATUS409Operation status does not allow this action
CODE_NOT_FOUND404Transaction code not found
SELF_DEPOSIT409Cannot deposit to same business (chargeback)
RATE_LIMIT429Too many requests (max 60/min)
METHOD_NOT_ALLOWED405Only POST method accepted
DB_ERROR500Internal server error