Support
Products

Bills Payment

Give your customers airtime, data, electricity, cable TV and more — with instant value and real-time confirmation. The flow is: browse billers → validate customer → pay.

1. Browse categories & billers

GET /v1/bills/categories
GET /v1/bills/billers?category=electricity
Response · 200 OK
{
  "data": [
    {
      "id": "blr_ekedc_prepaid",
      "name": "Eko Electricity (Prepaid)",
      "category": "electricity",
      "country": "NG",
      "amount_type": "flexible",
      "min_amount": 500,
      "max_amount": 500000
    }
  ]
}

Products with fixed prices (e.g. cable TV bouquets, data bundles) expose an items array — fetch it with GET /v1/bills/billers/{id}/items.

2. Validate the customer

POST /v1/bills/validate

Confirms the meter / smartcard / phone number and returns the customer's name where the biller supports it. Always validate before paying.

cURL
curl https://api.finlogic.com/v1/bills/validate \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "biller_id": "blr_ekedc_prepaid", "customer_id": "04123456789" }'
Response · 200 OK
{ "customer_id": "04123456789", "customer_name": "OKAFOR ADAEZE", "valid": true }

3. Pay the bill

POST /v1/bills/pay
cURL
curl https://api.finlogic.com/v1/bills/pay \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: 9c4e7f2d-..." \
  -H "Content-Type: application/json" \
  -d '{
    "biller_id": "blr_ekedc_prepaid",
    "customer_id": "04123456789",
    "amount": 10000,
    "reference": "BILL-88121"
  }'
Response · 201 Created
{
  "id": "bl_6t3p9w2e",
  "status": "processing",
  "biller_id": "blr_ekedc_prepaid",
  "amount": 10000,
  "reference": "BILL-88121",
  "token": null,
  "created_at": "2026-07-10T11:40:18Z"
}

For prepaid electricity, the bill.completed webhook (and GET /v1/bills/{id}) carries the vend token to show the customer.

Airtime example

cURL
curl https://api.finlogic.com/v1/bills/pay \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "biller_id": "blr_mtn_airtime",
    "customer_id": "+2348012345678",
    "amount": 1000,
    "reference": "AIR-30442"
  }'
Reconciliation tip: billers occasionally confirm late. A bill stuck in processing auto-resolves within 15 minutes to completed or failed (with automatic wallet refund) — and fires the matching webhook either way.