Bill Payments
Sell airtime, data, electricity, TV packages, and betting funding from your application. The flow is the same shape for every biller: discover products, validate when required, vend, then reconcile.
Use this flow when you are building a bills marketplace, reseller wallet, checkout add-on, or customer self-service payment screen.
1. Discover the bill category
Call GET /bills/catalogs to list bill categories. Use GET /bills/networks for mobile networks, GET /bills/data/list for data plans, GET /bills/electricity/list for electricity providers, GET /bills/tv/list for TV packages, and GET /bills/betting/list for betting providers.
curl https://api.aellaapp.com/bills/catalogs \
-H "Authorization: Bearer {token}"
2. Validate when the biller requires it
TV and betting require a validation step before vending. Use POST /bills/tv/validate for smart-card validation and POST /bills/betting/validate for betting customer validation.
Skip this step for airtime, data, and electricity unless your own product requires an extra confirmation screen.
3. Vend the bill
Call the matching vend endpoint:
POST /bills/airtime/vendPOST /bills/data/vendPOST /bills/electricity/vendPOST /bills/tv/vendPOST /bills/betting/vend
Always send a unique merchant reference when the endpoint accepts one. Store it beside your order so you can verify status later.
curl https://api.aellaapp.com/bills/airtime/vend \
-X POST \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"network":"mtn","phoneNumber":"08123456789","amount":100,"reference":"merchant-airtime-ref-001"}'
4. Reconcile final status
Bill payments can complete asynchronously. Use POST /bills/status with the merchant reference to query the final status.
Prefer webhooks where available: bill.successful and bill.failed. Keep your handler idempotent because webhook delivery can retry.
5. Exercise failures in sandbox
In sandbox, append _FAIL to a bill reference to force a failed vend and test your bill.failed handling before going live.