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

API Documentation

Integrate your loyalty program with KvitkaCard international bonus transaction system

v1.0 • REST API • JSON

Overview

Base URL

https://www.kvitkacard.com/api/v1

Authentication

Every request must include your unique API token in the request body (api_token field). The token is issued when your business is registered in KvitkaCard.

Data format

All requests and responses use JSON format. Set the Content-Type: application/json header.

How the system works

Each operation consists of two steps. First — initiation (limit check, conversion), then — confirmation. Points are deducted from or credited to the user account ONLY after a successful response to the confirmation request.

Limits

Minimum transaction amount: 1 KvitkaCoin. Maximum: 1000 KvitkaCoins. Conversion happens automatically based on your business currency and multiplier.

Rate limiting

Maximum 60 requests per 60 seconds per API token.

Important:
  • Do NOT deduct points from user account until you receive a successful response to withdraw/confirm.
  • Do NOT credit points until you receive a successful response to deposit/confirm.
  • Transaction code is single-use. After a successful deposit/confirm the code cannot be used again.
  • When a deposit is rejected (deposit/reject), the code remains active — the user can enter it at another business.
POST

Step 1: Initiate withdrawal

POST https://www.kvitkacard.com/api/v1/withdraw/init.php
Sends the points amount for verification. The system converts points to KvitkaCoins and checks limits. Operation is created with initiated status. Points are NOT deducted at this stage.

Request

ParameterDescription
api_tokenstringRequiredYour unique API token
amountnumberRequiredNumber of points to transfer
Request example
{
  "api_token": "your_api_token_here",
  "amount": 100
}

Response

FieldDescription
successbooleanRequest status (true/false)
operation_idintegerOperation ID (received in step 1)
amount_kcnumberAmount in KvitkaCoins after conversion
statusstringOperation status
messagestringResult explanation
Response example
{
  "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 example

<?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

Step 2: Confirm withdrawal

POST https://www.kvitkacard.com/api/v1/withdraw/confirm.php
Confirms the operation. System moves it to holding status and generates a unique 16-digit transaction code. ONLY after receiving a successful response to this request should you deduct points from the user account.
Important: Do NOT deduct points from user account until you receive a successful response to withdraw/confirm.

Request

ParameterDescription
api_tokenstringRequiredYour unique API token
operation_idintegerRequiredOperation ID (received in step 1)
Response example
{
  "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

Step 1: Verify code

POST https://www.kvitkacard.com/api/v1/deposit/init.php
Verifies the transaction code and converts the amount to your loyalty program points. Returns the number of points to be credited. Check your internal limits before confirming.

Request

ParameterDescription
api_tokenstringRequiredYour unique API token
transaction_codestringRequiredTransaction code (16 digits)
Response example
{
  "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

Step 2: Confirm deposit

POST https://www.kvitkacard.com/api/v1/deposit/confirm.php
Confirms the deposit. Operation is completed with completed status. ONLY after receiving a successful response should you credit points to the user account.
Important: Do NOT credit points until you receive a successful response to deposit/confirm.

Request

ParameterDescription
api_tokenstringRequiredYour unique API token
operation_idintegerRequiredOperation ID (received in step 1)
transaction_codestringRequiredTransaction code (16 digits)
Response example
{
  "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

Alternative: Reject deposit

POST https://www.kvitkacard.com/api/v1/deposit/reject.php
If your internal limits do not allow accepting this amount — send a rejection request. The operation will remain in holding status, and the transaction code will stay active — the user can use it at another business.

Request

ParameterDescription
api_tokenstringRequiredYour unique API token
operation_idintegerRequiredOperation ID (received in step 1)
transaction_codestringRequiredTransaction code (16 digits)
reasonstringOptionalRejection reason (for logging)

Error codes

On error, the API returns JSON with success: false, error_code and message fields.
CodeHTTPDescription
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