Electricity – BudPay

Electricity Bills Payment

Purchase electricity tokens for prepaid meters and pay postpaid bills across all Nigerian electricity distribution companies. Retrieve available providers, validate customer meters, and recharge seamlessly.

Get Electricity Providers

Retrieve a list of available electricity distribution companies.

Endpoint

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

Sample Request

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

Sample Response

{
    "success": true,
    "code": "00000",
    "message": "Fetched successfully",
    "data": [
        {
            "provider": "IKEDC",
            "code": "ikeja-electric",
            "providerLogoUrl": "assets/images/bills/Ikeja-Electric-Payment-PHCN.jpg",
            "minAmount": "500"
        },
        {
            "provider": "EKEDC",
            "code": "eko-electric",
            "providerLogoUrl": "assets/images/bills/Eko-Electric-Payment-PHCN.jpg",
            "minAmount": "500"
        },
        {
            "provider": "KEDCO",
            "code": "kano-electric",
            "providerLogoUrl": "assets/images/bills/Kano-Electric.jpg",
            "minAmount": "500"
        },
        {
            "provider": "PHED",
            "code": "portharcourt-electric",
            "providerLogoUrl": "assets/images/bills/Port-Harcourt-Electric.jpg",
            "minAmount": "500"
        },
        {
            "provider": "JED",
            "code": "jos-electric",
            "providerLogoUrl": "assets/images/bills/Jos-Electric-JED.jpg",
            "minAmount": "500"
        },
        {
            "provider": "IBEDC",
            "code": "ibadan-electric",
            "providerLogoUrl": "assets/images/bills/IBEDC-Ibadan-Electricity-Distribution-Company.jpg",
            "minAmount": "500"
        },
        {
            "provider": "KAEDCO",
            "code": "kaduna-electric",
            "providerLogoUrl": "assets/images/bills/Kaduna-Electric-KAEDCO.jpg",
            "minAmount": "500"
        },
        {
            "provider": "AEDC",
            "code": "abuja-electric",
            "providerLogoUrl": "assets/images/bills/Abuja-Electric.jpg",
            "minAmount": "500"
        }
    ]
}

Try it out

Response Fields

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

Provider Object Fields

Field	Type	Description
`provider`	String	Electricity distribution company name
`code`	String	Provider code for transactions
`providerLogoUrl`	String	URL path to provider logo image
`minAmount`	String	Minimum recharge amount (NGN 500)

Validate Meter Number

Validate a customer's meter number and retrieve account details before purchase.

Endpoint

POST https://api.budpay.com/api/v2/electricity/validate

Sample Request

curl https://api.budpay.com/api/v2/electricity/validate \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
    "provider": "IBEDC",
    "type": "prepaid",
    "number": "1111111111111"
}' \
-X POST

Sample Response

{
    "success": true,
    "code": "00000",
    "message": "Fetched successfully",
    "data": {
        "provider": "IBEDC",
        "number": "1111111111111",
        "type": "prepaid",
        "Customer_Name": "OLADIPO OLUWAFEMI"
    }
}

Try it out

Request Parameters

Body Parameters

Parameter	Type	Required	Description
`provider`	String	Yes	Electricity provider name (IKEDC, EKEDC, IBEDC, etc.)
`type`	String	Yes	Meter type: `prepaid` or `postpaid`
`number`	String	Yes	Customer meter number

Response Fields

Field	Type	Description
`success`	Boolean	Indicates if validation was successful
`code`	String	Response code
`message`	String	Response message
`data.provider`	String	Electricity provider
`data.number`	String	Meter number
`data.type`	String	Meter type (prepaid/postpaid)
`data.Customer_Name`	String	Registered customer name

Recharge Electricity

Purchase electricity token for prepaid meters or pay postpaid bills.

Endpoint

POST https://api.budpay.com/api/v2/electricity/recharge

Sample Request

curl https://api.budpay.com/api/v2/electricity/recharge \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Encryption: Signature_HMAC-SHA-512" \
-H "Content-Type: application/json" \
-d '{
    "provider": "IKEDC",
    "number": "1111111111111",
    "type": "prepaid",
    "amount": 1000,
    "reference": "2022051105275457530"
}' \
-X POST

Sample Response

{
    "success": true,
    "code": "00000",
    "message": "SUCCESSFUL",
    "data": {
        "orderNo": "16651456950755436254604761",
        "reference": "20220511052754574330",
        "status": "delivered",
        "errorMsg": "TRANSACTION SUCCESSFUL",
        "purchased_code": "Token : 26362054405982757802",
        "units": "79.9 kWh"
    }
}

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	Electricity provider name (IKEDC, EKEDC, IBEDC, etc.)
`number`	String	Yes	Customer meter number
`type`	String	Yes	Meter type: `prepaid` or `postpaid`
`amount`	Integer	Yes	Recharge amount (minimum NGN 500)
`reference`	String	Yes	Unique transaction reference

Response Fields

Field	Type	Description
`success`	Boolean	Indicates if recharge 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	Recharge status (delivered, pending, failed)
`data.errorMsg`	String	Status message or error details
`data.purchased_code`	String	Electricity token (prepaid only)
`data.units`	String	Energy units purchased in kWh (prepaid only)

Supported Providers

Provider	Code	Coverage Area	Min Amount
IKEDC	ikeja-electric	Ikeja, Lagos	NGN 500
EKEDC	eko-electric	Eko, Lagos	NGN 500
IBEDC	ibadan-electric	Ibadan, Oyo	NGN 500
KEDCO	kano-electric	Kano	NGN 500
PHED	portharcourt-electric	Port Harcourt, Rivers	NGN 500
JED	jos-electric	Jos, Plateau	NGN 500
KAEDCO	kaduna-electric	Kaduna	NGN 500
AEDC	abuja-electric	Abuja, FCT	NGN 500

Note: All providers require a minimum purchase amount of NGN 500.

Meter Types

Type	Description	Token Generation
Prepaid	Pay-as-you-go meters	Token provided in response
Postpaid	Monthly billing meters	No token, credit applied to account

Recharge Status

Status	Description
`delivered`	Token generated and delivered successfully
`pending`	Recharge being processed
`failed`	Recharge 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 500"],
        "number": ["Invalid meter number"]
    }
}

Best Practices

Tip: Always validate meter numbers before accepting payment to ensure the meter exists and customer details are correct.

Validate Meter First: Use validate endpoint to confirm meter details and customer name
Display Customer Name: Show validated customer name for user confirmation
Minimum Amount: Enforce NGN 500 minimum requirement
Store Tokens: Save purchased tokens for customer reference
Meter Type Selection: Allow users to specify prepaid or postpaid
Unique References: Generate unique reference IDs for each transaction
Check Balance: Verify wallet balance before purchase
Token Display: For prepaid, prominently display the purchased token
Units Information: Show energy units (kWh) purchased

Electricity Purchase Workflow

💡

Process Flow: Get providers → Select provider → Validate meter → Purchase token

Get Providers: Fetch available electricity providers
Select Provider: User selects their distribution company
Meter Type: User selects prepaid or postpaid meter type
Enter Meter Number: User enters their meter number
Validate Meter: Verify meter exists and retrieve customer name
Confirm Details: Display customer name for verification
Enter Amount: User enters recharge amount (min NGN 500)
Generate Reference: Create unique transaction reference
Purchase Token: Submit recharge request
Display Token: For prepaid, show token and units purchased
Save Transaction: Store order number and token for reference

Security Considerations

⚠️

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

HMAC Signature: Always include the Encryption: Signature_HMAC-SHA-512 header
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 meter numbers and amounts before submission
Pre-Validation: Always validate meters before accepting payment
Token Security: Transmit tokens securely to customers (SMS, email, secure display)

Integration Tips

Complete Recharge Flow

async function purchaseElectricity(provider, meterNumber, type, amount) {
    // 1. Validate meter first
    const validation = await axios.post(
        'https://api.budpay.com/api/v2/electricity/validate',
        {
            provider,
            type,
            number: meterNumber
        },
        {
            headers: {
                'Authorization': 'Bearer YOUR_SECRET_KEY',
                'Content-Type': 'application/json'
            }
        }
    );
    
    // 2. Show customer name for confirmation
    console.log(`Customer: ${validation.data.data.Customer_Name}`);
    
    // 3. Generate unique reference
    const reference = `ELEC_${Date.now()}_${Math.random().toString(36).substring(7)}`;
    
    // 4. Purchase token
    const response = await axios.post(
        'https://api.budpay.com/api/v2/electricity/recharge',
        {
            provider,
            number: meterNumber,
            type,
            amount,
            reference
        },
        {
            headers: {
                'Authorization': 'Bearer YOUR_SECRET_KEY',
                'Encryption': 'Signature_HMAC-SHA-512',
                'Content-Type': 'application/json'
            }
        }
    );
    
    // 5. Display token for prepaid
    if (type === 'prepaid' && response.data.data.purchased_code) {
        console.log(`Token: ${response.data.data.purchased_code}`);
        console.log(`Units: ${response.data.data.units}`);
    }
    
    return response.data;
}

Next Steps

Airtime - Purchase mobile airtime
Data Bundles - Purchase mobile data bundles
Cable TV - Subscribe to cable TV services
Wallet Balance - Check wallet balance before purchases
Transaction History - View electricity purchase history

TV Subscription Overview