Click Airtime API Documentation

Search and retrieve transaction history from the Click Airtime V1 API using GET /adp/transactions.

Version 1 API (v1.4) — This API is in maintenance mode. New integrations should use the Version 2 API which provides paginated transaction lists, filtering, and detailed status tracking.

GET /adp/transactions

Retrieve details of an airtime transaction. This endpoint allows you to fetch information related to a specific airtime transaction, providing insights into the transaction's status and other relevant details.

Request

GET https://api.clickairtime.com/adp/transactions
X-Click-Airtime-Email: your@email.com
X-Click-Airtime-Token: your-api-token

Query Parameters

Parameter	Type	Required	Description
`transaction_Id`	string	No	Filter by Click Airtime transaction ID (UUID)
`msisdn`	string	No	Filter by recipient phone number (e.g., `265996139030`)
`extRefId`	string	No	Filter by your external reference ID

At least one query parameter (transaction_Id, msisdn, or extRefId) must be provided. If multiple are specified, results are filtered by all criteria (AND logic). Parameters are passed as GET URL parameters.

Code Examples

Search by Phone Number

curl -X GET "https://api.clickairtime.com/adp/transactions?msisdn=265996139030" \
  -H "X-Click-Airtime-Email: your@email.com" \
  -H "X-Click-Airtime-Token: your-api-token"

const params = new URLSearchParams({ msisdn: '265996139030' });

const response = await fetch(
  `https://api.clickairtime.com/adp/transactions?${params}`,
  {
    headers: {
      'X-Click-Airtime-Email': 'your@email.com',
      'X-Click-Airtime-Token': 'your-api-token',
    },
  }
);

const { data } = await response.json();
data.forEach(txn => {
  console.log(`${txn.transactionId}: ${txn.amount} ${txn.currency} → ${txn.msisdn} [${txn.state}]`);
});

import requests

response = requests.get(
    'https://api.clickairtime.com/adp/transactions',
    params={'msisdn': '265996139030'},
    headers={
        'X-Click-Airtime-Email': 'your@email.com',
        'X-Click-Airtime-Token': 'your-api-token',
    }
)

data = response.json()['data']
for txn in data:
    print(f"{txn['transactionId']}: {txn['amount']} {txn['currency']} → {txn['msisdn']} [{txn['state']}]")

$response = Http::withHeaders([
    'X-Click-Airtime-Email' => 'your@email.com',
    'X-Click-Airtime-Token' => 'your-api-token',
])->get('https://api.clickairtime.com/adp/transactions', [
    'msisdn' => '265996139030',
]);

$data = $response->json()['data'];

foreach ($data as $txn) {
    echo "{$txn['transactionId']}: {$txn['amount']} {$txn['currency']} → {$txn['msisdn']} [{$txn['state']}]\n";
}

HttpResponse<String> response = Unirest
    .get("https://api.clickairtime.com/adp/transactions")
    .queryString("msisdn", "265996139030")
    .header("X-Click-Airtime-Email", "your@email.com")
    .header("X-Click-Airtime-Token", "your-api-token")
    .asString();

JSONObject result = new JSONObject(response.getBody());
JSONArray data = result.getJSONArray("data");

for (int i = 0; i < data.length(); i++) {
    JSONObject txn = data.getJSONObject(i);
    System.out.println(
        txn.getString("transactionId") + ": " +
        txn.getDouble("amount") + " " +
        txn.getString("currency") + " → " +
        txn.getString("msisdn") + " [" +
        txn.getString("state") + "]"
    );
}

Search by External Reference ID

curl -X GET "https://api.clickairtime.com/adp/transactions?extRefId=HWI-199S-100" \
  -H "X-Click-Airtime-Email: your@email.com" \
  -H "X-Click-Airtime-Token: your-api-token"

const response = await fetch(
  'https://api.clickairtime.com/adp/transactions?extRefId=HWI-199S-100',
  {
    headers: {
      'X-Click-Airtime-Email': 'your@email.com',
      'X-Click-Airtime-Token': 'your-api-token',
    },
  }
);

const { data } = await response.json();
console.log('Transaction:', data[0]);

response = requests.get(
    'https://api.clickairtime.com/adp/transactions',
    params={'extRefId': 'HWI-199S-100'},
    headers={
        'X-Click-Airtime-Email': 'your@email.com',
        'X-Click-Airtime-Token': 'your-api-token',
    }
)

data = response.json()['data']
print(f"Transaction: {data[0]}")

Response (200)

{
  "message": "Success",
  "statusCode": 200,
  "data": [
    {
      "transactionId": "f661f75a-c249-4aef-8cf3-abcdef123456",
      "status": true,
      "msisdn": "265996139030",
      "network": "NetOne",
      "country": "Zimbabwe",
      "amount": 100,
      "TopupAmount": 100,
      "effectiveAmount": 100.00,
      "currency": "ZWL",
      "extRefId": "DS2345",
      "accountId": "1dedb34-434ff-555x-ed5434fa",
      "state": "SUCCESS",
      "provider": {
        "transaction_id": "EXT-12345",
        "reference_code": "REF-67890"
      }
    }
  ]
}

Response Fields

Field	Type	Description
`transactionId`	string	Unique Click Airtime transaction identifier (UUID)
`status`	boolean	`true` if the top-up was delivered successfully, `false` otherwise
`msisdn`	string	Recipient phone number
`network`	string	Mobile network operator name
`country`	string	Destination country name
`amount`	number	Amount delivered in destination currency
`TopupAmount`	number	Same as `amount` (backward compatibility alias)
`effectiveAmount`	number	Amount deducted from your account balance (after rate conversion)
`currency`	string	Destination currency code (e.g., `ZWL`, `MWK`)
`extRefId`	string	Your external reference ID
`accountId`	string	Service account UUID used for this transaction
`state`	string	Transaction state: `SUCCESS`, `FAILED`, or `PENDING`
`provider.transaction_id`	string	Provider's transaction ID
`provider.reference_code`	string	Provider's reference code

Transaction Statuses

The transaction response includes two status indicators:

Field	Type	Values	Description
`status`	boolean	`true` / `false`	Legacy field — `true` if airtime was delivered, `false` otherwise
`state`	string	`SUCCESS`, `FAILED`, `PENDING`	Descriptive state of the transaction

Error Responses

HTTP Status	Description
400	Missing required query parameter (`transaction_Id`, `msisdn`, or `extRefId`)
401	Invalid or missing authentication credentials
404	No transactions found matching the criteria

Transactions