Bill Payments

Pay utility bills, buy airtime, purchase data bundles, and more — all through a unified API backed by the Interswitch Quickteller network.

Supported Categories

Category	Examples
Electricity	Eko Electric, Ikeja Electric, Kano Electric, PHCN
Telecommunications	MTN, Airtel, Glo, 9mobile
Airtime Top-up	All major networks
Data Bundles	All major networks
Cable TV	DStv, GOtv, StarTimes
Internet	Spectranet, Smile, IPNX
Insurance	Various providers
Education	School fees, WAEC, JAMB
Government	Taxes, licenses, permits
Water	State water boards
Waste Management	LAWMA, state agencies

Payment Flow

1. Browse categories          GET /api/v1/bill-payment/categories
2. Select provider            GET /api/v1/bill-payment/categories/:code/providers
3. Get payment items          GET /api/v1/bill-payment/providers/:billerId/items
4. Validate customer          POST /api/v1/bill-payment/validate
5. Make payment               POST /api/v1/bill-payment/pay
6. Check status               GET /api/v1/bill-payment/:id

Step 1: Browse Categories

GET /api/v1/bill-payment/categories

{
  "success": true,
  "data": [
    { "code": "electricity", "name": "Electricity", "description": "Power utility bills" },
    { "code": "airtime", "name": "Airtime", "description": "Mobile airtime top-up" },
    { "code": "data", "name": "Data", "description": "Mobile data bundles" },
    { "code": "cabletv", "name": "Cable TV", "description": "TV subscriptions" }
  ]
}

Step 2: Get Providers

GET /api/v1/bill-payment/categories/electricity/providers

{
  "success": true,
  "data": [
    { "billerId": "biller_001", "name": "Eko Electric (EKEDC)", "code": "ekedc" },
    { "billerId": "biller_002", "name": "Ikeja Electric", "code": "ikedc" }
  ]
}

Step 3: Get Payment Items

GET /api/v1/bill-payment/providers/biller_001/items

Returns available payment plans (e.g., prepaid vs. postpaid, token amounts).

Step 4: Validate Customer

Before paying, validate the customer reference (meter number, phone number, smart card number, etc.):

POST /api/v1/bill-payment/validate

{
  "billerId": "biller_001",
  "customerReference": "04567890123"
}

Response:

{
  "success": true,
  "data": {
    "customerName": "JOHN DOE",
    "customerReference": "04567890123",
    "outstandingBalance": 15000.00
  }
}

Step 5: Make Payment

cURL

curl -X POST https://api.korastratum.com/api/v1/banking/bill-payment/pay \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: fmfb" \
  -H "Content-Type: application/json" \
  -d '{
    "billerId": "biller_001",
    "customerReference": "04567890123",
    "amount": 15000.00,
    "description": "Electricity prepaid"
  }'

Node.js

const res = await fetch(
  "https://api.korastratum.com/api/v1/banking/bill-payment/pay",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "X-Tenant-ID": "fmfb",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      billerId: "biller_001",
      customerReference: "04567890123",
      amount: 15000.0,
      description: "Electricity prepaid",
    }),
  }
);

Python

res = requests.post(
    "https://api.korastratum.com/api/v1/banking/bill-payment/pay",
    headers={"Authorization": f"Bearer {token}", "X-Tenant-ID": "fmfb"},
    json={
        "billerId": "biller_001",
        "customerReference": "04567890123",
        "amount": 15000.00,
        "description": "Electricity prepaid",
    },
)

Response:

{
  "success": true,
  "data": {
    "paymentId": "p1a2b3c4-...",
    "reference": "BP20260227001234",
    "billerReference": "ISW123456",
    "status": "completed",
    "amount": 15000.00,
    "fees": 100.00,
    "totalAmount": 15100.00,
    "customerName": "JOHN DOE",
    "timestamp": "2026-02-27T14:22:00Z"
  }
}

Airtime & Data

For quick airtime and data purchases, use the mobile money endpoints:

Buy Airtime

POST /api/v1/mobile-money/airtime

{
  "phoneNumber": "08012345678",
  "amount": 5000.00,
  "network": "mtn"
}

Buy Data Bundle

POST /api/v1/mobile-money/data

{
  "phoneNumber": "08012345678",
  "bundleId": "mtn_5gb_30days",
  "network": "mtn"
}

List Providers

GET /api/v1/mobile-money/providers

Payment History

GET /api/v1/bill-payment/history

Returns all bill payments with pagination. Filter by date range, category, or status.

GET /api/v1/bill-payment/history?from=2026-01-01&to=2026-02-28&category=electricity

Payment Details

GET /api/v1/bill-payment/:id

Returns full payment details including biller reference, receipt, and status.

Provider Failover

Bill payment processing uses a circuit breaker:

• Primary: Interswitch Quickteller API v5
• Failover: NIBSS (if configured)
• Failover trigger: 2 consecutive failures
• Retry: Up to 5 status polling attempts after submission

Next Steps

• Transfers — Money transfers and beneficiary management.
• Webhooks — Get notified when payments complete.
• Error Codes — Payment-specific error codes.