Overview – BudPay

Bills Payment Overview

BudPay's Bills Payment API enables businesses to offer comprehensive utility and service payment solutions. Integrate airtime top-ups, data bundles, cable TV subscriptions, and electricity bill payments into your platform with a unified API.

Available Services

BudPay Bills Payment API supports four major service categories across Nigeria:

1. Airtime Top-Up

Purchase airtime for all major Nigerian mobile networks instantly.

Supported Networks:

MTN Nigeria
Airtel Nigeria
Glo Nigeria
9mobile Nigeria

Key Features:

Minimum purchase: NGN 5
Instant delivery
HMAC-SHA-512 encryption for security
Real-time status updates

View Airtime Documentation →

2. Data Bundles

Purchase mobile data plans for all major Nigerian networks.

Supported Networks:

MTN Nigeria
Airtel Nigeria
Glo Nigeria
9mobile Nigeria
Smile 4G

Key Features:

Multiple plan options per provider
Plan details with data size and validity
Instant activation
HMAC-SHA-512 encryption for security
Order tracking with delivery status

View Data Bundles Documentation →

3. Cable TV Subscriptions

Manage cable TV subscriptions for major Nigerian providers.

Supported Providers:

DSTV (Premium, Compact Plus, Compact, Confam, Yanga, Padi)
GOtv (Supa, Max, Jolli, Jinja, Smallie)
StarTimes (Nova, Basic, Smart, Classic, Super)
Showmax (Entertainment, Sport, Pro)

Key Features:

Account validation before purchase
Multiple package options
Monthly, quarterly, and yearly subscriptions
HMAC-SHA-512 encryption for security
Instant activation

View Cable TV Documentation →

4. Electricity Bills

Purchase electricity tokens for prepaid meters and pay postpaid bills.

Supported Distribution Companies:

IKEDC (Ikeja Electric)
EKEDC (Eko Electric)
IBEDC (Ibadan Electric)
KEDCO (Kano Electric)
PHED (Port Harcourt Electric)
JED (Jos Electric)
KAEDCO (Kaduna Electric)
AEDC (Abuja Electric)

Key Features:

Meter validation with customer name
Prepaid and postpaid support
Token generation for prepaid meters
Energy units (kWh) information
Minimum purchase: NGN 500
HMAC-SHA-512 encryption for security

View Electricity Documentation →

API Workflow

All bills payment services follow a consistent workflow pattern:

Standard Flow

💡

Typical Process: Get providers → Select provider → Get options (if applicable) → Validate (if applicable) → Purchase

Get Providers: Retrieve list of available service providers
Select Provider: User chooses their provider
Get Options: Fetch plans/packages (for data and TV services)
Validate Account: Verify account details (for TV and electricity)
Generate Reference: Create unique transaction reference
Purchase Service: Submit payment request with HMAC encryption
Track Status: Monitor transaction delivery status
Notify Customer: Inform user of successful purchase

Authentication & Security

API Authentication

All bills payment endpoints require authentication using your BudPay secret key:

Authorization: Bearer YOUR_SECRET_KEY

HMAC-SHA-512 Encryption

⚠️

Security Requirement: All purchase/payment endpoints require HMAC-SHA-512 encryption.

Payment endpoints (airtime top-up, data purchase, TV subscription, electricity recharge) require an additional encryption header:

Encryption: Signature_HMAC-SHA-512

Encrypted Endpoints:

POST /api/v2/airtime/topup - Airtime purchase
POST /api/v2/internet/data - Data bundle purchase
POST /api/v2/tv/pay - TV subscription
POST /api/v2/electricity/recharge - Electricity recharge

Non-Encrypted Endpoints:

All GET endpoints (providers, plans, packages)
Validation endpoints

Common Parameters

Request Parameters

Most purchase endpoints share common parameters:

| Parameter | Type | Required | Description | |---|---|---| | provider | String | Yes | Service provider name | | number | String | Yes | Customer account/phone/meter number | | amount | String/Integer | Varies | Purchase amount (airtime, electricity) | | reference | String | Yes | Unique transaction reference |

Response Fields

Standard response structure across all endpoints:

Field	Type	Description
`success`	Boolean	Indicates if request was successful
`code`	String	Response code
`message`	String	Response message
`data`	Object/Array	Response data

Purchase Response

Successful purchase responses include:

Field	Type	Description
`data.orderNo`	String	Provider's order number
`data.reference`	String	Your transaction reference
`data.status`	String	Delivery status (Delivered, Pending, Failed)
`data.errorMsg`	String	Error message if any (null on success)

Transaction Status

Status Types

Status	Description	Action
`Delivered`	Transaction completed successfully	Notify customer of success
`Pending`	Transaction being processed	Poll for status updates
`Failed`	Transaction failed	Refund customer, show error message

Error Handling

Common Error Codes

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": {
        "field_name": ["Error message"]
    }
}

500 Server Error

{
    "success": false,
    "message": "Unable to process request"
}

Best Practices

Pro Tip: Always validate accounts/meters before accepting payment to ensure smooth transactions and better customer experience.

1. Pre-Validation

Validate TV accounts and electricity meters before purchase
Display customer names for confirmation
Verify phone numbers match provider networks (for airtime/data)

2. Amount Validation

Enforce minimum amounts: NGN 5 (airtime), NGN 500 (electricity)
Check wallet balance before initiating transactions
Display amount limits to users

3. Reference Management

Generate unique reference IDs for each transaction
Use unpredictable patterns (timestamps + random strings)
Store references for transaction tracking and support

4. Provider Data

Cache provider lists locally (updated periodically)
Fetch fresh plans/packages before each purchase
Display provider logos for better UX

5. Security Implementation

Never expose secret keys in frontend code
Always use HTTPS for all API requests
Include HMAC signature header for payment endpoints
Sanitize all user inputs before submission

6. Status Monitoring

Implement proper handling for all status types
Set up webhooks for asynchronous status updates
Provide real-time feedback to customers

7. Transaction Records

Store order numbers for customer support
Save tokens (electricity) for customer reference
Maintain transaction history for reconciliation

8. Error Handling

Implement graceful error handling
Display user-friendly error messages
Log errors for debugging and monitoring

Integration Example

Complete Bills Payment Flow

// 1. Check wallet balance
const balance = await checkWalletBalance('NGN');
 
// 2. Get service providers
const providers = await axios.get('https://api.budpay.com/api/v2/airtime', {
    headers: {
        'Authorization': 'Bearer YOUR_SECRET_KEY',
        'Content-Type': 'application/json'
    }
});
 
// 3. Validate account (for TV/Electricity)
const validation = await axios.post(
    'https://api.budpay.com/api/v2/electricity/validate',
    {
        provider: 'IKEDC',
        type: 'prepaid',
        number: '1111111111111'
    },
    {
        headers: {
            'Authorization': 'Bearer YOUR_SECRET_KEY',
            'Content-Type': 'application/json'
        }
    }
);
 
// 4. Generate unique reference
const reference = `BILL_${Date.now()}_${Math.random().toString(36).substring(7)}`;
 
// 5. Make purchase
const purchase = await axios.post(
    'https://api.budpay.com/api/v2/airtime/topup',
    {
        provider: 'MTN',
        number: '07036218209',
        amount: '100',
        reference
    },
    {
        headers: {
            'Authorization': 'Bearer YOUR_SECRET_KEY',
            'Encryption': 'Signature_HMAC-SHA-512',
            'Content-Type': 'application/json'
        }
    }
);
 
// 6. Handle response
if (purchase.data.success && purchase.data.data.status === 'Delivered') {
    console.log('Purchase successful!');
    console.log('Order Number:', purchase.data.data.orderNo);
} else {
    console.log('Purchase failed:', purchase.data.data.errorMsg);
}

Rate Limits & Performance

API Rate Limits

Standard rate limits apply to all bills payment endpoints
Contact support for higher rate limits for high-volume merchants

Performance Tips

Cache provider lists to reduce API calls
Batch similar transactions when possible
Use asynchronous processing for bulk operations
Implement retry logic for failed requests with exponential backoff

Service Availability

24/7 Operations

All bills payment services are available 24/7/365 with high uptime guarantees.

Provider Maintenance

Occasional maintenance windows may affect specific providers. Status updates are provided via:

API response messages
Status page notifications
Email alerts to merchants

Testing

Test Mode

Use test credentials to verify integration before going live:

Test secret keys available in your dashboard
Switch between test and live modes easily
No real charges in test mode

Test Scenarios

Test common scenarios:

Successful purchases
Failed validations
Insufficient wallet balance
Invalid account numbers
Timeout handling

Pricing & Fees

Service Charges

Competitive fees applied per transaction:

Fees vary by service type and provider
Transparent pricing with no hidden charges
Volume discounts available for high-volume merchants

Fee Calculation

Check service fees before transaction:

Fees displayed in API responses
Deducted from wallet balance automatically
Detailed breakdown in transaction history

Support & Resources

Documentation

Related APIs

Wallet Management - Check balance before purchases
Transaction History - View bills payment records
Settlement Management - Track settlements

Get Help

API Support: support@budpay.com
Developer Portal: https://developers.budpay.com (opens in a new tab)
Status Page: https://status.budpay.com (opens in a new tab)

Quick Start Checklist

💡

Follow these steps to integrate bills payment services:

Next Steps

Ready to integrate bills payment? Start with a specific service:

Airtime Top-Up → - Simplest integration, instant delivery
Data Bundles → - Three-step flow with plan selection
Cable TV → - Account validation + subscription
Electricity → - Meter validation + token generation

Or explore related services:

Wallet Balance → - Check available funds
Making Payments → - Bank transfers and payouts
Accept Payments → - Receive payments from customers

Fetch Virtual Account Details Airtime