Skip to main content
Handle’s collection platform enables two primary integration models for apps, fintechs, and merchant platforms.

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:
    1. GET /vending/products?categoryCode=electricity (Load DisCo list & tariffs).
    2. POST /vending/validate (Check meter 0219927013063 → returns “Ade Peters, Garki”).
    3. POST /vending/transactions (Debits user, returns 20-digit token 4512-8921-3342-9901-2311).
    4. 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:
    1. GET /biller/get-biller-by-category/6 (List Educational Institutions).
    2. GET /biller/S0000573002/products (Retrieve UI services and dynamic customFields).
    3. Customer fills matric number UI/2026/1092 and selects department in the app UI.
    4. POST /biller/initiate (Generates RRR 250799679337 and paymentIdentifier).
    5. 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:
    1. GET /biller/lookup/200799091919 (Fetches biller name “CAC”, service “Business Registration”, and amount “₦10,000”).
    2. User reviews and authorizes payment with FaceID / PIN.
    3. POST /biller/process (Settles RRR; government portal marks invoice as PAID immediately).

Integration Summary Matrix