API Documentation
Complete reference for integrating with our API services
Base URL
https://vucl.in/api/v2
Authentication
All API requests require an API key. Pass it via:
Option 1 — Bearer Token:
Authorization: Bearer YOUR_API_KEY
Option 2 — Header:
X-API-Key: YOUR_API_KEY
Rate Limits
Per Minute
60 requests
Per Day
10,000 requests
Returns HTTP 429 when exceeded. Retry after a few seconds.
Endpoints
GET
/api/v2/balance
Get your current wallet balance.
Response
{
"success": true,
"balance": 1250.50,
"currency": "INR"
}
GET
/api/v2/services
List all available API services with their request schemas.
Response
{
"success": true,
"services": [
{
"id": 1,
"name": "Mobile Recharge",
"slug": "mobile-recharge",
"category": "Recharge",
"internal_code": "RECHARGE_MOBILE",
"request_schema": [
{"name": "mobile", "type": "text", "required": true},
{"name": "amount", "type": "number", "required": true},
{"name": "operator", "type": "text", "required": true}
]
}
]
}
POST
/api/v2/execute
MAIN
Execute an API request through the best available provider.
Request Body
{
"service_code": "RECHARGE_MOBILE",
"params": {
"mobile": "9876543210",
"amount": 199,
"operator": "JIO"
},
"reference": "optional-client-ref-123"
}Fields
| Field | Type | Required | Description |
|---|---|---|---|
| service_code | string | Yes | Internal code from /services |
| params | object | Yes | Service-specific parameters |
| reference | string | No | Your own reference ID |
Response
{
"success": true,
"internal_reference": "TXN-abc123",
"client_reference": "optional-client-ref-123",
"status": "success",
"data": {
"transaction_id": "PROV-xyz789",
"status": "success",
"message": "Recharge successful"
}
}
POST
/api/v2/check-status
Check the status of a previous transaction.
Request Body
{
"internal_reference": "TXN-abc123"
}Response
{
"success": true,
"internal_reference": "TXN-abc123",
"status": "success",
"provider_response": {...}
}
GET
/api/v2/transactions
List your recent transactions (paginated, newest first).
Response
{
"success": true,
"transactions": {
"data": [...],
"current_page": 1,
"last_page": 5,
"total": 120
}
}
GET
/api/v2/stats
Get your account usage statistics.
Response
{
"success": true,
"stats": {
"total_requests": 1250,
"success": 1180,
"failed": 70,
"success_rate": 94.4,
"today_requests": 45
}
}Error Responses
401
Invalid or missing API key
403
Account disabled or IP not authorized
422
Invalid parameters / service not found
429
Rate limit exceeded
500
Provider error — check error message
Example: cURL
# Get balance
curl -X GET https://vucl.in/api/v2/balance \
-H "Authorization: Bearer YOUR_API_KEY"
# Execute a mobile recharge
curl -X POST https://vucl.in/api/v2/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"service_code": "RECHARGE_MOBILE",
"params": {
"mobile": "9876543210",
"amount": 199,
"operator": "JIO"
}
}'
# Check transaction status
curl -X POST https://vucl.in/api/v2/check-status \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"internal_reference": "TXN-abc123"}'Payment Gateway Base URL
https://vucl.in/api/merchant
All requests require HMAC-SHA256 body signing via x-api-key and x-signature headers.
Authentication
Every request must include these headers:
x-api-key:
YOUR_MERCHANT_API_KEYx-signature:
HMAC-SHA256(request_body, YOUR_API_SECRET)content-type:
application/jsonGenerate the signature by computing HMAC-SHA256 of the raw JSON body using your API secret as the key.
Endpoints
POST
/api/merchant/payins
CREATE PAYMENT
Create a payment link for your customer. Returns a checkout URL to redirect them to.
Request Body
{
"order_id": "your_unique_order_id",
"amount": 199
}Fields
| Field | Type | Required | Description |
|---|---|---|---|
| order_id | string | Yes | Your unique order ID (max 100 chars) |
| amount | number | Yes | Payment amount in INR (min 1) |
Response
{
"order_id": "your_unique_order_id",
"checkout_url": "https://gateway.example/pay/...",
"status": "pending"
}
GET
/api/merchant/payins/{order_id}
Check the status of a payment by your order ID.
Response
{
"order_id": "your_unique_order_id",
"amount": 199,
"commission": 29.85,
"net_amount": 169.15,
"status": "paid",
"paid_at": "2026-08-27T10:30:00Z"
}
GET
/api/merchant/balance
Get your merchant wallet balance.
Response
{
"balance": 1250.50,
"total_earned": 5000.00,
"total_settled": 3749.50,
"currency": "INR"
}
GET
/api/merchant/wallet
Get your wallet transaction history (credits and debits).
Response
{
"balance": 1250.50,
"transactions": [
{
"type": "credit",
"amount": 169.15,
"description": "Payment from order ord_123",
"balance_after": 1250.50,
"created_at": "2026-08-27T10:30:00Z"
}
]
}
POST
/api/merchant/withdraw
WITHDRAW
Request a payout from your wallet to a UPI ID.
Request Body
{
"amount": 500,
"upi_id": "yourname@upi"
}Response
{
"settlement_id": 1,
"amount": 500,
"upi_id": "yourname@upi",
"status": "processing"
}Webhook Notifications
We POST to your webhook URL when a payment status changes. Verify the signature to ensure authenticity.
Headers
content-type:
application/jsonx-signature:
HMAC-SHA256(body, your_api_secret)Payload
{
"event": "payin.updated",
"order_id": "your_unique_order_id",
"amount": 199,
"commission": 29.85,
"net_amount": 169.15,
"status": "success",
"utr": "UPI123456789",
"paid_at": "2026-08-27T10:30:00Z"
}Status Values
success
Payment completed
failed
Payment failed
Error Responses
401
Missing or invalid API key / signature
403
Merchant account inactive
409
Order already paid
422
Invalid parameters / insufficient balance
500
Gateway error
Example: cURL
# Create a payment link
curl -X POST https://vucl.in/api/merchant/payins \
-H "x-api-key: YOUR_MERCHANT_API_KEY" \
-H "x-signature: $(echo -n '{"order_id":"ord_123","amount":199}' | openssl dgst -sha256 -hmac 'YOUR_API_SECRET' | awk '{print $2}')" \
-H "Content-Type: application/json" \
-d '{"order_id":"ord_123","amount":199}'
# Check payment status
curl -X GET https://vucl.in/api/merchant/payins/ord_123 \
-H "x-api-key: YOUR_MERCHANT_API_KEY" \
-H "x-signature: $(echo -n '' | openssl dgst -sha256 -hmac 'YOUR_API_SECRET' | awk '{print $2}')" \
-H "Content-Type: application/json"
# Get balance
curl -X GET https://vucl.in/api/merchant/balance \
-H "x-api-key: YOUR_MERCHANT_API_KEY" \
-H "x-signature: $(echo -n '' | openssl dgst -sha256 -hmac 'YOUR_API_SECRET' | awk '{print $2}')" \
-H "Content-Type: application/json"