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.

GET/bills/catalogs

Fetch 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.

Request

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/bills/networks

Get 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).

Request

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
}

GET/bills/data/list

Fetch 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.

Request

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
}

GET/bills/electricity/list

Fetch Electricity Providers

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.

Request

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
}

POST/bills/electricity/vend

Buy Electricity

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").

Request

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
}

POST/bills/data/vend

Buy Data

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).

Request

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
}

POST/bills/airtime/vend

Buy Airtime

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.

Request

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
}

POST/bills/status

Verify Bill 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).

Request

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
}

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.