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.