Loading IA-Café
Getting your data ready

⚡ Quick Overview

POST /devapi/v1/airtime
🚀

Instant Delivery

Airtime is delivered within seconds

💰

2.2% Discount

Default discount on all purchases

📞

All Networks

MTN, Airtel, Glo, 9mobile

🔄 How It Works

📤
Send Request
💳
Wallet Charged
⚙️
Process Order
Airtime Delivered

📋 Request Parameters

Parameter Type Required Description
request_id string Yes Your unique transaction ID (prevents duplicates)
phone string Yes Phone number to recharge (11-16 digits)
service_id string Yes Network: mtn, airtel, glo, 9mobile
amount number Yes Amount in Naira (₦10 - ₦50,000)
💡
Phone Number Formats
All these formats are accepted and automatically normalized:
08012345678+23480123456782348012345678

📡 Network Prefixes

Network service_id Prefixes Min Amount
MTN mtn 0703, 0706, 0803, 0806, 0810, 0813, 0814, 0816, 0903, 0906, 0913 ₦10
Airtel airtel 0701, 0708, 0802, 0808, 0812, 0902, 0907, 0901, 0912 ₦50
Glo glo 0705, 0805, 0807, 0811, 0815, 0905, 0915 ₦50
9mobile 9mobile 0809, 0817, 0818, 0908, 0909 ₦50

💻 Code Examples

cURL
curl -X POST "https://iacafe.com.ng/devapi/v1/airtime" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "air_mtn_1704067200_abc123",
    "phone": "08012345678",
    "service_id": "mtn",
    "amount": 100
  }'
Node.js (Axios)
const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://iacafe.com.ng/devapi/v1';

async function buyAirtime() {
  try {
    const response = await axios.post(
      `${BASE_URL}/airtime`,
      {
        request_id: `air_mtn_${Date.now()}_${Math.random().toString(36).slice(2)}`,
        phone: '08012345678',
        service_id: 'mtn',
        amount: 100
      },
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Success!', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data);
  }
}

buyAirtime();
Python (Requests)
import requests
import uuid
import time

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://iacafe.com.ng/devapi/v1'

def buy_airtime(phone, network, amount):
    request_id = f"air_{network}_{int(time.time())}_{uuid.uuid4().hex[:8]}"
    
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    payload = {
        'request_id': request_id,
        'phone': phone,
        'service_id': network,
        'amount': amount
    }
    
    response = requests.post(
        f'{BASE_URL}/airtime',
        headers=headers,
        json=payload
    )
    
    return response.json()

# Usage
result = buy_airtime('08012345678', 'mtn', 100)
print(result)
PHP
<?php

$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://iacafe.com.ng/devapi/v1';

function buyAirtime($phone, $network, $amount) {
    global $apiKey, $baseUrl;
    
    $requestId = "air_{$network}_" . time() . "_" . bin2hex(random_bytes(4));
    
    $payload = [
        'request_id' => $requestId,
        'phone' => $phone,
        'service_id' => $network,
        'amount' => $amount
    ];
    
    $ch = curl_init($baseUrl . '/airtime');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($payload),
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json'
        ],
        CURLOPT_RETURNTRANSFER => true
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$result = buyAirtime('08012345678', 'mtn', 100);
print_r($result);

?>

📤 Response Examples

200 OK Success Response

Completed Order
{
  "code": "success",
  "message": "ORDER COMPLETED",
  "data": {
    "product_name": "Airtime",
    "service_name": "MTN",
    "status": "completed-api",
    "order_id": 355960,
    "phone": "08012345678",
    "amount": 100,
    "discount": "2.20",
    "amount_charged": "97.80",
    "initial_balance": "5000.00",
    "final_balance": "4902.20",
    "request_id": "air_mtn_1704067200_abc123"
  }
}

202 Accepted Processing Response

Processing Order
{
  "code": "success",
  "message": "ORDER PROCESSING",
  "data": {
    "product_name": "Airtime",
    "service_name": "MTN",
    "status": "processing-api",
    "order_id": 355960,
    "phone": "08012345678",
    "amount": 100,
    "discount": "2.20",
    "amount_charged": "97.80",
    "request_id": "air_mtn_1704067200_abc123"
  }
}
💡
Processing Status
If you receive a "processing-api" status, the order is being processed. You'll receive a webhook when it completes, or you can check status via the Requery endpoint.

❌ Error Responses

400 Invalid Phone Number

Error Response
{
  "success": false,
  "error": {
    "code": "invalid_field",
    "message": "Invalid phone number"
  }
}

402 Insufficient Funds

Error Response
{
  "success": false,
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient wallet balance"
  }
}

409 Duplicate Request ID

Error Response
{
  "success": false,
  "error": {
    "code": "duplicate_request_id",
    "message": "Request ID already exists"
  }
}

✅ Best Practices

🔑 Unique Request IDs

Always use unique request_id values. Include timestamp and random string to ensure uniqueness. Example: air_mtn_1704067200_x7f9

Validate Before Sending

Check that the phone number prefix matches the service_id before making the request. This prevents rejected transactions.

📡 Use Webhooks

Set up webhooks to receive instant notifications when transactions complete. Don't rely solely on the API response.

🔄 Handle Processing Status

If you get "processing-api" status, don't retry immediately. Wait for webhook or poll the requery endpoint after 30 seconds.