Real-World Use Cases & Situations
Scenario 1: Retail Utility Vending in a Banking / Fintech App
Who uses it: Mobile banking apps, agent banking POS, e-wallets.- Situation: A customer opens their banking app to recharge electricity (
0219927013063) or buy data. - Why it’s needed: Prevents customer complaints by verifying the meter owner name before money leaves their account.
- API Flow:
GET /vending/products?categoryCode=electricity(Load DisCo list & tariffs).POST /vending/validate(Check meter0219927013063→ returns “Ade Peters, Garki”).POST /vending/transactions(Debits user, returns 20-digit token4512-8921-3342-9901-2311).GET /vending/query-transaction/{ref}(Requery fallback if network drops).
Scenario 2: Student School Fees & Institutional Collections
Who uses it: Educational portals, student apps, university collection portals.- Situation: A university student needs to pay their ₦45,000 Acceptance Fee or ₦20,000 Graduation Gown fee to University of Ibadan (
S0000573002). - Why it’s needed: Universities require dynamic metadata (matriculation number, department, graduation year) attached to the payment for automatic bursary clearance.
- API Flow:
GET /biller/get-biller-by-category/6(List Educational Institutions).GET /biller/S0000573002/products(Retrieve UI services and dynamiccustomFields).- Customer fills matric number
UI/2026/1092and selects department in the app UI. POST /biller/initiate(Generates RRR250799679337andpaymentIdentifier).POST /biller/process(Settles payment instantly; bursary ledger receives automatic credit).
Scenario 3: Government Taxes & Existing Invoice Settlement
Who uses it: Accounting software, ERPs, merchant portals, tax payment apps.- Situation: A business owner receives a Corporate Affairs Commission (CAC) or FIRS tax assessment invoice with a 12-digit RRR (
200799091919). - Why it’s needed: Users want to pay pre-generated invoices from government portals in one click without re-entering details.
- API Flow:
GET /biller/lookup/200799091919(Fetches biller name “CAC”, service “Business Registration”, and amount “₦10,000”).- User reviews and authorizes payment with FaceID / PIN.
POST /biller/process(Settles RRR; government portal marks invoice asPAIDimmediately).