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.
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
Parameter
Description
api_tokenstringRequired
Your unique API token
operation_idintegerRequired
Operation 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
Parameter
Description
api_tokenstringRequired
Your unique API token
transaction_codestringRequired
Transaction 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
Parameter
Description
api_tokenstringRequired
Your unique API token
operation_idintegerRequired
Operation ID (received in step 1)
transaction_codestringRequired
Transaction 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
Parameter
Description
api_tokenstringRequired
Your unique API token
operation_idintegerRequired
Operation ID (received in step 1)
transaction_codestringRequired
Transaction code (16 digits)
reasonstringOptional
Rejection reason (for logging)
Error codes
On error, the API returns JSON with success: false, error_code and message fields.