Version 2 API

The Click Airtime V2 API provides a clean, RESTful interface for sending airtime top-ups to 600+ networks in 140+ countries. Built for enterprise integrations with API key authentication and pre-funded wallets.

Base URL

https://api.clickairtime.com/v2

Authentication

All V2 API requests require an API key, generated from the Enterprise Portal. Include it as a Bearer token:

Authorization: Bearer ce_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Response Format

All responses follow a standardized envelope:

Success

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Success with Pagination

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "request_id": "req_a1b2c3d4e5f6",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 150,
      "total_pages": 8,
      "has_next": true,
      "has_prev": false
    }
  }
}

Error

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your wallet balance is too low for this transaction.",
    "details": {}
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Endpoints

Method	Endpoint	Description
GET	/v2/catalog/lookup	Look up products for a phone number or network
GET	/v2/catalog/countries	List supported countries and networks
GET	/v2/catalog/networks	List networks by country
GET	/v2/catalog/products	List products for a network
POST	/v2/topups	Send an airtime top-up
GET	/v2/topups	List topup history
GET	/v2/topups/:id	Get topup status
GET	/v2/balance	Get all wallet balances
GET	/v2/balance/:wallet_id	Get a specific wallet's balance

Duplicate Prevention

Duplicate transactions are handled automatically. If you submit the same phone number, network, and amount within a short time window, the API returns the existing transaction instead of creating a duplicate.

Webhooks

Pass a callback_url when creating a topup to receive real-time status notifications via HTTP webhooks. See the Webhooks page for details on event types, signature verification, and retry behavior.

Rate Limits

Tier	Limit
Standard	60 requests/minute
Burst	1,000 requests/hour

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1705312260