Bill payments overview

Breeze supports three bill products on the same external transactions API as airtime and data:

POST /v1/transactions

Bill products (ELECTRICITY, CABLE, BETTING) are sync — the create response includes the final outcome. Airtime and data on the same route are async — poll status with your client_request_id. Response shapes: Field conventions.

Plan catalogs

Names and amounts (no plan IDs): Catalog — electricity, cable, betting.

Each bill product is identified by a numeric plan_code (catalog plan id). Provider routing fields are resolved server-side — you never send raw service_id or variation_id.

GET /v1/plans/bills/{product}

{product} is electricity, cable, or betting. Optional ?network= filter (e.g. Ikeja Electric, DSTV, BET9JA).

curl "https://api.breezeinnovations.io/v1/plans/bills/cable?network=DSTV" \
  -H "X-Merchant-Key: mk_your_key_id" \
  -H "X-Merchant-Secret: your_issued_secret"

Pass the returned plan id as plan_code on verify and purchase. Product-specific network lists: Electricity, Cable TV, Betting.

Verify customer (optional)

Customer verification also runs automatically before purchase. To validate a meter or smartcard without creating a transaction, use the same merchant credentials as purchase:

POST /v1/transactions/verify

curl -X POST "https://api.breezeinnovations.io/v1/transactions/verify" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Key: mk_your_key_id" \
  -H "X-Merchant-Secret: your_issued_secret" \
  -d '{
    "merchant_code": "YOUR_MERCHANT",
    "customer_msisdn": "10000000001",
    "network": "Ikeja Electric",
    "product": "ELECTRICITY",
    "plan_code": "1001"
  }'

* Send plan_code (recommended) or service_id, not both.

HTTP 200:

{
  "status": "success",
  "code": 200,
  "message": "customer verified",
  "data": {
    "product": "ELECTRICITY",
    "network": "Ikeja Electric",
    "msisdn": "10000000001",
    "customer_name": "Test Customer",
    "customer_address": "Ikeja Electric - Test Address",
    "min_amount": "1000",
    "max_amount": "50000"
  }
}

Electricity verify may also include disco details when the biller returns them: meter_number, arrears, account_type, meter_type, district, business_unit, district_reference, and tariff. Empty values are omitted. min_amount / max_amount are purchase limits (catalog floor when the meter reports 0), not arrears.

No client_request_id on verify. You may skip verify and proceed directly to purchase.

HTTP 400 — the meter, smartcard, or betting ID was rejected, or the request was invalid. This is not an outage. Do not retry as if the API is down. message is the biller’s reason when available:

{
  "status": "error",
  "code": 400,
  "message": "This meter is not correct or is not a valid Ibadan Electric prepaid meter. Please check and try again"
}

HTTP 502 — verify could not be completed. Retry with backoff. message is generic.

Product-specific guides: Electricity, Cable TV, Betting.

Status and history (optional for bills)

Bill purchases return the final outcome on create. To re-fetch or list history:

GET /v1/transactions/status?client_request_id={client_request_id}
GET /v1/transactions?page=1&limit=20

Bill rows use product values ELECTRICITY, CABLE, or BETTING.

Contact your account manager to enable each bill product on your merchant profile.