Billers API

This is the Billers API that provides programmatic access to various resources and services. The API supports the following areas: Bill Payments. All endpoints require authentication using a Bearer token.

The billers model

The billers model contains all the information about your billers entities.

Properties

Name
billers
Type
array
Description
List of billers items
Name
pagination
Type
object
Description
Object containing pagination data

List Billers

Retrieves a list of all available billers supported for payments.

Request

GET

/v1/billers

curl -G https://api.adiba.app/v1/billers \
  -H "Authorization: Bearer {token}"

{
"billers": [
    {
        "billerId": "IKEDC001",
        "billerName": "Ikeja Electric",
        "billerCode": "IKEDC",
        "category": "UTILITIES",
        "logo": "https://cdn.bank.com/billers/ikedc.png",
        "isActive": true,
        "supportedChannels": [
            "BANK_TRANSFER",
            "CARD",
            "WALLET"
        ]
    },
    {
        "billerId": "DSTV001",
        "billerName": "DSTV",
        "billerCode": "DSTV",
        "category": "CABLE_TV",
        "logo": "https://cdn.bank.com/billers/dstv.png",
        "isActive": true,
        "supportedChannels": [
            "BANK_TRANSFER",
            "CARD"
        ]
    }
],
"pagination": {
    "page": 1,
    "size": 10,
    "total": 150,
    "hasNext": true,
    "hasPrevious": false
}
}

List Biller Items

Fetches the specific payment items available for a selected biller.

Required attributes

Name
billerId
Type
string
Description
Unique identifier specified in the URL path

Request

GET

/v1/billers/{billerId}/items

curl -G https://api.adiba.app/v1/billers/{billerId}/items \
  -H "Authorization: Bearer {token}"

{
"billerId": "IKEDC001",
"billerName": "Ikeja Electric",
"items": [
    {
        "itemId": "ITEM_001",
        "itemName": "Prepaid Meter",
        "itemCode": "PREPAID",
        "amount": 0,
        "currency": "NGN",
        "description": "Pay for prepaid meter units",
        "isActive": true
    },
    {
        "itemId": "ITEM_002",
        "itemName": "Postpaid Bill",
        "itemCode": "POSTPAID",
        "amount": 0,
        "currency": "NGN",
        "description": "Pay for postpaid electricity bill",
        "isActive": true
    }
],
"pagination": {
    "page": 1,
    "size": 10,
    "total": 5,
    "hasNext": false,
    "hasPrevious": false
}
}

List Biller Categories

Displays a list of biller categories for filtering and discovery.

Request

GET

/v1/billers/categories

curl -G https://api.adiba.app/v1/billers/categories \
  -H "Authorization: Bearer {token}"

{
"categories": [
    {
        "categoryId": "CAT_001",
        "categoryName": "Utilities",
        "categoryCode": "UTILITIES",
        "description": "Electricity, water, and gas bills",
        "icon": "⚡",
        "billerCount": 25,
        "isActive": true
    },
    {
        "categoryId": "CAT_002",
        "categoryName": "Cable TV",
        "categoryCode": "CABLE_TV",
        "description": "Television subscription services",
        "icon": "📺",
        "billerCount": 8,
        "isActive": true
    },
    {
        "categoryId": "CAT_003",
        "categoryName": "Internet",
        "categoryCode": "INTERNET",
        "description": "Internet service providers",
        "icon": "🌐",
        "billerCount": 12,
        "isActive": true
    }
],
"totalCategories": 15
}

Query Transaction Status By Billing Reference

Checks the real-time status of a transaction using its reference number.

Required attributes

Name
billingRef
Type
string
Description
Billingref parameter specified in the URL path

Request

GET

/v1/billers/query/status/{billingRef}

curl -G https://api.adiba.app/v1/billers/query/status/{billingRef} \
  -H "Authorization: Bearer {token}"

{
"billingRef": "BILL_REF_001_20241201_001",
"transactionId": "TXN_001_20241201_001",
"status": "SUCCESS",
"amount": 5000,
"currency": "NGN",
"billerName": "Ikeja Electric",
"customerName": "John Doe",
"accountNumber": "123456789",
"processedAt": "2024-12-01T10:30:00Z",
"message": "Payment processed successfully",
"receiptUrl": "https://receipts.bank.com/TXN_001_20241201_001.pdf"
}