Transaction History
List and filter your topup transaction history with pagination.
Transaction History
Retrieve a paginated list of your topup transactions with optional filtering and sorting.
GET /v2/topupsPermission required: airtime.transactions.read
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
per_page | integer | 20 | Results per page (max 100) |
status | string | — | Filter by status: pending, processing, completed, failed |
phone_number | string | — | Filter by recipient phone number (partial match) |
reference | string | — | Filter by your reference (exact match) |
from | string | — | Start date (ISO 8601) |
to | string | — | End date (ISO 8601) |
sort | string | -created_at | Sort field. Prefix with - for descending. Options: created_at, completed_at, status, total_usd |
Example Request
curl -X GET "https://api.clickairtime.com/v2/topups?status=completed&from=2024-01-01&per_page=10" \
-H "Authorization: Bearer ce_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"const params = new URLSearchParams({
status: 'completed',
from: '2024-01-01',
per_page: '10',
});
const response = await fetch(`https://api.clickairtime.com/v2/topups?${params}`, {
headers: {
'Authorization': 'Bearer ce_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
},
});
const data = await response.json();import requests
response = requests.get(
'https://api.clickairtime.com/v2/topups',
params={
'status': 'completed',
'from': '2024-01-01',
'per_page': 10,
},
headers={
'Authorization': 'Bearer ce_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
}
)
data = response.json()Example Response
{
"success": true,
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"phone_number": "+233541112259",
"network": {
"id": 42,
"name": "MTN Ghana",
"country": "Ghana",
"country_code": "GH"
},
"amount": { "value": 50, "currency": "GHS" },
"cost": { "value": 4.05, "currency": "USD" },
"reference": "invoice-12345",
"created_at": "2024-01-15T10:30:00.000Z",
"completed_at": "2024-01-15T10:30:02.500Z"
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"status": "completed",
"phone_number": "+2348012345678",
"network": {
"id": 51,
"name": "MTN Nigeria",
"country": "Nigeria",
"country_code": "NG"
},
"amount": { "value": 1000, "currency": "NGN" },
"cost": { "value": 1.30, "currency": "USD" },
"reference": "invoice-12346",
"created_at": "2024-01-15T09:15:00.000Z",
"completed_at": "2024-01-15T09:15:03.200Z"
}
],
"meta": {
"request_id": "req_p1q2r3s4t5u6",
"timestamp": "2024-01-15T11:00:00.000Z",
"pagination": {
"page": 1,
"per_page": 10,
"total": 47,
"total_pages": 5,
"has_next": true,
"has_prev": false
}
}
}