Click Airtime

Transactions

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

ParameterTypeRequiredDescription
transaction_IdstringNoFilter by Click Airtime transaction ID (UUID)
msisdnstringNoFilter by recipient phone number (e.g., 265996139030)
extRefIdstringNoFilter 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": "Top-up successful! Airtime has been successfully topped up",
  "statusCode": 200,
  "code": 1,
  "data": [
    {
      "transactionId": "f661f75a-c249-4aef-8cf3-abcdef123456",
      "status": true,
      "msisdn": "265996139030",
      "network": "NetOne",
      "country": "Zimbabwe",
      "amount": 100,
      "TopupAmount": 100,
      "effectiveAmount": "0.06",
      "currency": "ZWL",
      "extRefId": "DS2345",
      "accountId": "1dedb34-434ff-555x-ed5434fa",
      "state": "SUCCESS",
      "wallet": {
        "currency": "USD",
        "amount": "0.06",
        "fxRate": "1729.0500"
      },
      "provider": {
        "transaction_id": "EXT-12345",
        "reference_code": "REF-67890"
      }
    }
  ]
}

Response Fields

FieldTypeDescription
codenumberTop-level envelope code. For single-record lookups (one item in data[]), this mirrors the record's state (see Envelope code semantics below). For multi-record lookups (e.g. by msisdn), it is always 1 regardless of the items' individual states — read per-record state instead.
data[].transactionIdstringUnique Click Airtime transaction identifier (UUID)
data[].statusbooleantrue if the top-up was delivered successfully, false otherwise
data[].msisdnstringRecipient phone number
data[].networkstringMobile network operator name
data[].countrystringDestination country name
data[].amountnumberAmount delivered in destination currency
data[].TopupAmountnumberSame as amount (backward compatibility alias)
data[].effectiveAmountstring | numberAmount deducted from your wallet (in your wallet's currency, after FX conversion)
data[].currencystringDestination currency code (e.g., ZWL, MWK)
data[].extRefIdstringYour external reference ID
data[].accountIdstringService account UUID used for this transaction
data[].statestringTransaction state. Terminal values: SUCCESS, FAILED, TIMEOUT, UNDERLIVERED. Non-terminal: PENDING, PROCESSING.
data[].wallet.currencystringCurrency your wallet was debited in (e.g. USD)
data[].wallet.amountstring | numberAmount actually debited from your wallet in that currency. Use this for FX reconciliation.
data[].wallet.fxRatestring | numberFX rate applied for the conversion (destination units per wallet unit). null for same-currency top-ups.
data[].provider.transaction_idstringProvider's transaction ID
data[].provider.reference_codestringProvider's reference code

Transaction Statuses

The transaction response carries the transaction state in two complementary forms:

FieldTypeValuesDescription
statusbooleantrue / falseLegacy field — true if airtime was delivered, false otherwise
statestringPENDING, PROCESSING, SUCCESS, FAILED, TIMEOUT, UNDERLIVEREDDescriptive state of the transaction. Treat the last four as terminal.

Envelope code semantics

For single-record lookups the top-level code and message both reflect the transaction's state, so branching on code alone is sufficient for most integrations and message stays consistent with what the transaction is actually doing:

data[0].stateTop-level codeTop-level message
SUCCESS1Top-up successful! Airtime has been successfully topped up
PENDING / PROCESSING10The operation is pending and being processed
FAILED / UNDERLIVERED5The airtime top-up operation has failed
TIMEOUT160Airtime transaction timed out
CANCELED170Transaction was cancelled

For multi-record lookups (e.g. listing by msisdn), the top-level code is always 1 and message is Success because individual states vary across records. Read per-record state in that case.

Polling for a terminal state. When a top-up returns data.state: "PENDING" (top-level code: 232), poll this endpoint by extRefId until state becomes one of SUCCESS, FAILED, TIMEOUT, or UNDERLIVERED. Most transactions resolve within seconds; the absolute outer bound is about 12 minutes, after which the record is guaranteed to be terminal — our reconciliation service queries each provider's status API on your behalf and converges the record automatically.

Error Responses

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