Airtime Providers

Retrieve a list of available airtime providers and their service details. This endpoint returns supported mobile network operators with minimum and maximum top-up amounts.

Endpoint

GET https://api.budpay.com/api/v2/airtime

Sample Request

Endpoint: GET https://api.budpay.com/api/v2/airtime

cURLJavascriptPythonGo

More

cURL

More

Try it

1curl -X GET 'https://api.budpay.com/api/v2/airtime' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY'

200 OK

{  "success": true,  "code": "00000",  "message": "Fetched successfully",  "data": [    {      "provider": "AIRTEL",      "providerLogoUrl": "assets/images/bills/Airtel-Airtime.jpg",      "minAmount": "5",      "maxAmount": ""    },    {      "provider": "MTN",      "providerLogoUrl": "assets/images/bills/MTN-Airtime.jpg",      "minAmount": "5",      "maxAmount": ""    },    {      "provider": "GLO",      "providerLogoUrl": "assets/images/bills/GLO-Airtime.jpg",      "minAmount": "5",      "maxAmount": ""    },    {      "provider": "9MOBILE",      "providerLogoUrl": "assets/images/bills/9mobile-Airtime.jpg",      "minAmount": "5",      "maxAmount": ""    }  ]}

Powered by

Request Parameters

Header Parameters

Response Fields

Provider Object Fields

Supported Providers

Purchase Airtime

Purchase airtime for a mobile number using any of the supported network providers.

Endpoint

POST https://api.budpay.com/api/v2/airtime/topup

Sample Request

Endpoint: POST https://api.budpay.com/api/v2/airtime/topup

cURLJavascriptPythonGo

More

cURL

More

Try it

1curl -X POST 'https://api.budpay.com/api/v2/airtime/topup' \2  -H 'Encryption: Signature_HMAC-SHA-512' \3  -H 'Content-Type: application/json' \4  -H 'Authorization: Bearer YOUR_SECRET_KEY' \5  -d '{6  "provider": "MTN",7  "number": "07036218209",8  "amount": "100",9  "reference": "2459392959593939"10}'

Powered by

Request Parameters

Header Parameters

Body Parameters

Response Fields

Purchase Status

Error Handling

400 Bad Request

{
    "success": false,
    "message": "Invalid request parameters"
}

401 Unauthorized

{
    "success": false,
    "message": "Authentication failed"
}

422 Validation Error

{
    "success": false,
    "message": "Validation error",
    "errors": {
        "amount": ["Amount must be at least NGN 5"],
        "number": ["Invalid phone number format"]
    }
}

500 Server Error

{
    "success": false,
    "message": "Unable to fetch providers"
}

Best Practices

1. Cache Provider List: Store provider data locally and refresh periodically
2. Validate Amounts: Enforce minimum NGN 5 requirement before purchase
3. Validate Phone Number: Ensure phone number matches the provider's network
4. Unique References: Generate unique reference IDs for each transaction
5. Check Balance: Verify wallet balance before initiating purchase
6. Store Order Numbers: Save order numbers for customer support queries
7. Handle Status: Implement proper handling for pending and failed statuses
8. Display Logos: Use provider logo URLs to enhance user interface

Airtime Purchase Workflow

1. Get Providers: Fetch available airtime providers
2. Select Provider: User selects their network provider
3. Enter Details: User enters phone number and amount
4. Validate Amount: Ensure amount meets minimum requirement (NGN 5)
5. Generate Reference: Create unique transaction reference
6. Purchase Airtime: Submit purchase request
7. Track Status: Monitor delivery status
8. Notify User: Inform user of successful delivery

Security Considerations

• HMAC Signature: Always include the Encryption: Signature_HMAC-SHA-512 header for purchases
• Server-Side Only: Never expose secret keys in frontend code
• HTTPS Only: All requests must use secure HTTPS connections
• Reference IDs: Use unpredictable reference IDs to prevent replay attacks
• Validate Input: Sanitize phone numbers and amounts before submission

Integration Tips

Display Provider Selection

// Fetch providers
const providers = await getAirtimeProviders();
 
// Display in UI
providers.data.forEach(provider => {
    console.log(`${provider.provider}: Min NGN ${provider.minAmount}`);
});

Validate Purchase Amount

function validateAirtimeAmount(provider, amount) {
    const minAmount = parseFloat(provider.minAmount);
    const maxAmount = provider.maxAmount ? parseFloat(provider.maxAmount) : Infinity;
    
    if (amount < minAmount) {
        throw new Error(`Minimum amount is NGN ${minAmount}`);
    }
    
    if (amount > maxAmount) {
        throw new Error(`Maximum amount is NGN ${maxAmount}`);
    }
    
    return true;
}

Complete Purchase Flow

async function purchaseAirtime(provider, number, amount) {
    // Generate unique reference
    const reference = `AIRTIME_${Date.now()}_${Math.random().toString(36).substring(7)}`;
    
    // Purchase airtime
    const response = await axios.post('https://api.budpay.com/api/v2/airtime/topup', {
        provider,
        number,
        amount: amount.toString(),
        reference
    }, {
        headers: {
            'Authorization': 'Bearer YOUR_SECRET_KEY',
            'Encryption': 'Signature_HMAC-SHA-512',
            'Content-Type': 'application/json'
        }
    });
    
    return response.data;
}

Next Steps

• Data Bundles - Purchase mobile data bundles
• Wallet Balance - Check wallet balance before purchases
• Transaction History - View airtime purchase history