Airtime – BudPay

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

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

Sample Response

{
    "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": ""
        }
    ]
}

Try it out

Request Parameters

Header Parameters

Field Name	Description	Required
Authorization	Bearer token with your secret key	Yes
Content-Type	`application/json`	Yes

Response Fields

Field	Type	Description
`success`	Boolean	Indicates if request was successful
`code`	String	Response code
`message`	String	Response message
`data`	Array	Array of airtime provider objects

Provider Object Fields

Field	Type	Description
`provider`	String	Network provider name (AIRTEL, MTN, GLO, 9MOBILE)
`providerLogoUrl`	String	URL path to provider logo image
`minAmount`	String	Minimum airtime purchase amount
`maxAmount`	String	Maximum airtime purchase amount (empty = no limit)

Supported Providers

Provider	Network	Min Amount	Description
MTN	MTN Nigeria	NGN 5	MTN airtime recharge
AIRTEL	Airtel Nigeria	NGN 5	Airtel airtime recharge
GLO	Glo Nigeria	NGN 5	Glo airtime recharge
9MOBILE	9mobile Nigeria	NGN 5	9mobile airtime recharge

Note: All providers have a minimum purchase amount of NGN 5. Maximum amounts are typically unlimited unless specified.

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

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

Try it out

Request Parameters

Header Parameters

Field Name	Description	Required
Authorization	Bearer token with your secret key	Yes
Encryption	`Signature_HMAC-SHA-512` for request encryption	Yes
Content-Type	`application/json`	Yes

Body Parameters

Parameter	Type	Required	Description
`provider`	String	Yes	Network provider name (MTN, AIRTEL, GLO, 9MOBILE)
`number`	String	Yes	Recipient mobile number
`amount`	String	Yes	Airtime amount (minimum NGN 5)
`reference`	String	Yes	Unique transaction reference

Response Fields

Field	Type	Description
`success`	Boolean	Indicates if purchase was successful
`code`	String	Response code
`message`	String	Response message
`data.orderNo`	String	Order number from provider
`data.reference`	String	Your transaction reference
`data.status`	String	Delivery status (Delivered, Pending, Failed)
`data.errorMsg`	String	Error message if any (null on success)

Purchase Status

Status	Description
`Delivered`	Airtime delivered successfully
`Pending`	Purchase being processed
`Failed`	Purchase failed (check errorMsg)

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

Tip: Cache provider list locally to reduce API calls. Provider data doesn't change frequently.

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

Airtime Purchase Workflow

💡

Process Flow: Get providers → Select provider → Enter details → Purchase airtime

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

Security Considerations

⚠️

Security: The Encryption header with HMAC-SHA-512 signature is required for all airtime purchase requests.

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

Overview Data Purchase