Bills

Use the Bills API to offer bill payments through your application—electricity (prepaid and postpaid), data bundles, airtime, and more. Fetch catalogs, networks, and product lists, then initiate vends and check transaction status using the transaction reference.

All requests use Bearer Token authentication with your secret key. Base URL: https://api.aellaapp.com.

Endpoints

GET/bills/catalogsFetch Catalogs
GET/bills/networksGet Networks
GET/bills/data/listFetch Data List
GET/bills/electricity/listFetch Electricity Providers
POST/bills/electricity/vendBuy Electricity
POST/bills/data/vendBuy Data
POST/bills/airtime/vendBuy Airtime
POST/bills/statusVerify Bill Status
GET/bills/betting/listFetch Betting Providers
POST/bills/betting/validateValidate Betting
POST/bills/betting/vendBuy Betting
GET/bills/tv/listFetch TV Packages
POST/bills/tv/validateValidate TV
POST/bills/tv/vendBuy TV

Fetch Catalogs GET/bills/catalogs

This endpoint retrieves a list of bill catalogs (categories) available for vending. Use it to discover which bill types you can offer (e.g. electricity, data, airtime).

No request body or query parameters are required.

Response

Returns success, message, data (array of catalog/category objects), and status.

GET/bills/catalogs

curl https://api.aellaapp.com/bills/catalogs \
  -H "Authorization: Bearer {token}"

Response (200 OK)

{
  "success": true,
  "message": "Catalogs retrieved successfully",
  "data": [],
  "status": 200
}

Get Networks GET/bills/networks

This endpoint retrieves a list of supported networks (e.g. MTN, Airtel). Use the returned network identifiers when calling Buy Airtime or Buy Data.

No request body or query parameters are required.

Response

Returns success, message, data (array of network objects), and status. Each item typically includes a network code or name (e.g. mtn, airtel).

GET/bills/networks

curl https://api.aellaapp.com/bills/networks \
  -H "Authorization: Bearer {token}"

Response (200 OK)

{
  "success": true,
  "message": "Networks retrieved successfully",
  "data": [
    { "code": "mtn", "name": "MTN" },
    { "code": "airtel", "name": "Airtel" }
  ],
  "status": 200
}

Fetch Data List GET/bills/data/list

This endpoint retrieves a list of data bundle products available for vending. Use it to get productCode and related fields before calling Buy Data.

No request body or query parameters are required.

Response

Returns success, message, data (array of data products), and status. Each item typically includes productCode, network info, and possibly name or amount.

GET/bills/data/list

curl https://api.aellaapp.com/bills/data/list \
  -H "Authorization: Bearer {token}"

Response (200 OK)

{
  "success": true,
  "message": "Data products retrieved successfully",
  "data": [
    { "productCode": "800_39", "network": "mtn", "name": "800MB 30 days" }
  ],
  "status": 200
}

Fetch Electricity Providers GET/bills/electricity/list

This endpoint retrieves a list of electricity bills (providers and products) available for vending. Use it to get productCode, name, and prepaid for each product before calling Buy Electricity.

No request body or query parameters are required.

Response

Returns success, message, data (array of objects), and status. Each item in data has:

productCode (string): Code to use when vending (e.g. eko_electric_postpaid).
prepaid (boolean): Whether the product is prepaid.
name (string): Display name of the electricity product.

GET/bills/electricity/list

curl https://api.aellaapp.com/bills/electricity/list \
  -H "Authorization: Bearer {token}"

Response (200 OK)

{
  "success": true,
  "message": "Eletricity providers retrieved successfully!",
  "data": [
    {
      "productCode": "aba_electric_postpaid",
      "prepaid": false,
      "name": "aba electric postpaid"
    },
    {
      "productCode": "eko_electric_postpaid",
      "prepaid": false,
      "name": "eko electric postpaid"
    },
    {
      "productCode": "eko_electric_prepaid",
      "prepaid": true,
      "name": "eko electric prepaid"
    },
    {
      "productCode": "ikeja_electric_prepaid",
      "prepaid": true,
      "name": "ikeja electric prepaid"
    }
  ],
  "status": 200
}

Buy Electricity POST/bills/electricity/vend

This endpoint allows you to vend electricity—either prepaid or postpaid—for a given meter. The meter identifier is typically obtained from a prior validation/lookup step.

Request Body

Name
amount
Type
number
Description
The amount to pay (in Naira).
Name
productCode
Type
string
Description
The product code for the electricity plan (e.g. eko_electric_postpaid).
Name
meter
Type
string
Description
The meter identifier (e.g. meter number or ID from validation).
Name
reference
Type
string
Description
A unique reference for this transaction. Must not be empty.
Name
prepaid
Type
boolean
Description
true for prepaid, false for postpaid.
Name
name
Type
string
Description
Display name for the product (e.g. "eko electric postpaid").
Name
phoneNumber
Type
string
Description
Customer phone number (e.g. "08123456789").

POST/bills/electricity/vend

curl https://api.aellaapp.com/bills/electricity/vend \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "productCode": "eko_electric_postpaid",
    "meter": "c1a143f5-8740-44ed-a5f8-fb34a72e7881",
    "reference": "4bc656cb-d755-4efd-bd3b-bc7c67756770",
    "prepaid": true,
    "name": "eko electric postpaid",
    "phoneNumber": "08123456789"
  }'

Response (201 Created)

{
  "success": true,
  "message": "Transaction in progress. We will inform you of your transaction status shortly.",
  "data": {
    "status": "Pending",
    "transactionReference": "10cb88d7-149c-46c6-b1a5-dc3e3ae5973d"
  },
  "status": 200
}

Buy Data POST/bills/data/vend

This endpoint allows you to purchase data bundles for a phone number on a given network (e.g. MTN).

Request Body

Name
productCode
Type
string
Description
The data bundle product code (e.g. 800_39).
Name
phoneNumber
Type
string
Description
The recipient phone number (e.g. "08123456789").
Name
network
Type
string
Description
The network provider (e.g. "mtn").
Name
reference
Type
string
Description
A unique reference for this transaction.
Name
amount
Type
number
Description
The amount to pay (in Naira).

POST/bills/data/vend

curl https://api.aellaapp.com/bills/data/vend \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "800_39",
    "phoneNumber": "08123456789",
    "network": "mtn",
    "reference": "04670dd9-1284-4a7a-8110-1b36e022bbf7",
    "amount": 800
  }'

Response (201 Created)

{
  "success": true,
  "message": "Transaction in progress. We will inform you of your transaction status shortly.",
  "data": {
    "status": "Pending",
    "transactionReference": "d7dd80b8-7caf-4c3d-b140-14e651118ea4"
  },
  "status": 200
}

Buy Airtime POST/bills/airtime/vend

This endpoint allows you to purchase airtime for a specified network. The airtime is credited to the given phone number.

Request Body

Name
network
Type
string
Description
The network provider (e.g. "mtn").
Name
phoneNumber
Type
string
Description
The phone number to which the airtime will be credited (e.g. "08162838817"). Must be valid for the specified network.
Name
amount
Type
number
Description
The amount of airtime to purchase (in Naira).

Ensure the phone number is valid for the specified network and the amount is within the provider's allowed limits.

POST/bills/airtime/vend

curl https://api.aellaapp.com/bills/airtime/vend \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mtn",
    "phoneNumber": "08162838817",
    "amount": 500
  }'

Response (201 Created)

{
  "success": true,
  "message": "Transaction received. You will be notified once it has been confirmed.",
  "data": {
    "status": "Success",
    "transactionReference": "1772107491291-421AA9-BIL-037-D25AF08"
  },
  "status": 200
}

Verify Bill Status POST/bills/status

This endpoint allows you to check the status of a bill payment using the transaction reference returned when you initiated the vend (electricity, data, or airtime).

Query Parameters

Name
reference
Type
string
Description
The transaction reference from the initial vend response (e.g. from data.transactionReference).

POST/bills/status

curl "https://api.aellaapp.com/bills/status?reference=1772210036358-421AA9-BIL-037-1303572" \
  -H "Authorization: Bearer {token}" \
  -X POST

Response (201 Created)

{
  "success": true,
  "message": "Transaction status",
  "data": {
    "status": "Success",
    "billCategory": "TopUp",
    "service": "mtn",
    "transactionReference": "1772210036358-421AA9-BIL-037-1303572"
  },
  "status": 200
}

Fetch Betting Providers GET/bills/betting/list

Returns the list of betting providers available for funding.

GET/bills/betting/list

curl https://api.aellaapp.com/bills/betting/list \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Request successful",
  "data": [
    {
      "productCode": "BET9JA",
      "name": "Bet9ja"
    }
  ],
  "status": 200
}

Validate Betting POST/bills/betting/validate

Validates a betting customer id against a provider before funding. Always validate before calling Buy Betting.

Request Body

Name
productCode
Type
string
Description
Provider product code from Fetch Betting Providers.
Name
customerId
Type
string
Description
Customer identifier at the betting provider.

POST/bills/betting/validate

curl https://api.aellaapp.com/bills/betting/validate \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"productCode":"BET9JA","customerId":"4401404"}' \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "customerId": "4401404",
    "customerName": "JOHN DOE"
  },
  "status": 200
}

Buy Betting POST/bills/betting/vend

Funds a betting account after a successful Validate Betting call.

Request Body

Name
productCode
Type
string
Description
Provider product code from Fetch Betting Providers.
Name
customerId
Type
string
Description
Validated betting customer id.
Name
amount
Type
number
Description
Amount in Naira.
Name
reference
Type
string
Description
Optional merchant reference. Append _FAIL in sandbox to simulate failure.

POST/bills/betting/vend

curl https://api.aellaapp.com/bills/betting/vend \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"productCode":"BET9JA","customerId":"4401404","amount":100,"reference":"merchant-betting-ref-001"}' \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "reference": "merchant-betting-ref-001",
    "status": "success"
  },
  "status": 200
}

Fetch TV Packages GET/bills/tv/list

Returns TV packages for a provider. provider must be dstv or gotv.

Query Parameters

Name
provider
Type
string
Description
TV provider. One of dstv or gotv.

GET/bills/tv/list

curl https://api.aellaapp.com/bills/tv/list?provider=dstv \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Request successful",
  "data": [
    {
      "productCode": "FAMILY",
      "name": "DStv Family"
    }
  ],
  "status": 200
}

Validate TV POST/bills/tv/validate

Validates a smart card number against a TV provider before purchase. Always validate before calling Buy TV.

Request Body

Name
provider
Type
string
Description
TV provider. One of dstv or gotv.
Name
smartCard
Type
string
Description
Customer smart card number.

POST/bills/tv/validate

curl https://api.aellaapp.com/bills/tv/validate \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"provider":"dstv","smartCard":"7023454583"}' \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "smartCard": "7023454583",
    "customerName": "JOHN DOE"
  },
  "status": 200
}

Buy TV POST/bills/tv/vend

Purchases a TV package after a successful Validate TV call.

Request Body

Name
provider
Type
string
Description
TV provider. One of dstv or gotv.
Name
smartCard
Type
string
Description
Validated smart card number.
Name
productCode
Type
string
Description
Package code from Fetch TV Packages.
Name
reference
Type
string
Description
Optional merchant reference. Append _FAIL in sandbox to simulate failure.

POST/bills/tv/vend

curl https://api.aellaapp.com/bills/tv/vend \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"provider":"dstv","smartCard":"7023454583","productCode":"FAMILY","reference":"merchant-tv-ref-001"}' \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "reference": "merchant-tv-ref-001",
    "status": "success"
  },
  "status": 200
}

Notes

Use Fetch Electricity Providers to get productCode and name before calling Buy Electricity.
For Buy Electricity and Buy Data, the reference in the request body must be a unique, non-empty value so you can track and verify the transaction.
After a successful vend, use the returned data.transactionReference with the Verify Bill Status endpoint to confirm the transaction outcome.
Transactions may complete asynchronously; poll Verify Bill Status or rely on webhooks (if configured) for final status.
Betting and TV require a successful validate call before vend.
In sandbox, append _FAIL to a bill reference to force a failed vend and exercise the bill.failed webhook before going live.