KhalasPay API Documentation

Authentication

All API requests must include the following header:

Header	Description
`X-Api-Key`	Your merchant API Key

Example:

// PHP
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: your_api_key',
    'Content-Type: application/json',
    'Accept: application/json',
]);

// Python
import requests
headers = {"X-Api-Key": "your_api_key"}
resp = requests.get(url, headers=headers)

Endpoints

GET /api/v1/products

Get available products and SKUs for the merchant.

Response:

{
    "success": true,
    "data": [
        {
            "product_name": "Baloot",
            "channel": "baloot",
            "category": "baloot",
            "skus": [
                {
                    "sku_code": "baloot-10001",
                    "name": "10001 (500 coins)",
                    "face_value": "5.00",
                    "selling_price": "5.50",
                    "currency": "USD",
                    "coin": 500,
                    "sku_type": "topup"
                }
            ]
        }
    ]
}

POST /api/v1/topup/submit

Submit a topup order. Balance will be frozen, account validated and topup processed synchronously. Returns the final result.

Request Body:

{
    "out_trade_no": "YOUR_UNIQUE_ORDER_ID",
    "product_sku": "TOPUP-50",
    "account_id": "0512345678"
}

Response:

{
    "success": true,
    "message": "Topup successful",
    "data": {
        "order_no": "KP20250101120000xxxx",
        "out_trade_no": "YOUR_UNIQUE_ORDER_ID",
        "product_sku": "baloot-10001",
        "account_id": "0512345678",
        "amount": "5.50",
        "status": "success",
        "completed_at": "2025-01-01T12:00:01+00:00",
        "created_at": "2025-01-01T12:00:00+00:00"
    }
}

Idempotency: If the same out_trade_no is submitted again, the existing order will be returned.

GET /api/v1/topup/query

Query order status. Provide either order_no or out_trade_no.

Query Parameters:

`order_no`	KhalasPay order number
`out_trade_no`	Your merchant order number

Response:

{
    "success": true,
    "data": {
        "order_no": "KP20250101120000xxxx",
        "out_trade_no": "YOUR_UNIQUE_ORDER_ID",
        "status": "success",
        "amount": "52.00",
        "completed_at": "2025-01-01T12:00:30+00:00"
    }
}

GET /api/v1/balance

Query your merchant wallet balance.

Response:

{
    "success": true,
    "data": {
        "balance": "1000.00",
        "frozen_balance": "52.00",
        "available_balance": "948.00"
    }
}

Order Status Flow

pending → validating → validated → processing → success / failed

Status	Description
`pending`	Order created, balance frozen, queued for processing
`validating`	Validating account with upstream
`validated`	Account validated successfully
`processing`	Topup request sent to upstream
`success`	Topup completed, balance deducted
`failed`	Topup failed, frozen balance released

Callback Notification

When an order reaches a final state (success/failed), we send a POST request to your configured callback_url.

Callback Payload:

{
    "order_no": "KP20250101120000xxxx",
    "out_trade_no": "YOUR_UNIQUE_ORDER_ID",
    "status": "success",
    "amount": "52.00",
    "account_id": "0512345678",
    "fail_reason": null,
    "completed_at": "2025-01-01T12:00:30+00:00"
}

You must respond with HTTP 2XX and body being exactly success or ok, or a JSON object like {"success": true} to acknowledge.

Retry schedule: 30s, 2min, 10min, 30min, 2h (max 5 attempts).

Error Codes

HTTP Status	Meaning
200	Success
400	Bad request / validation error
401	Authentication failed (invalid or missing API key)
402	Insufficient balance
403	Merchant suspended or IP not whitelisted
404	Resource not found
422	Account validation failed
429	Rate limit exceeded