> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handle.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Biller Collections Guide & Use Cases

> Real-world integration scenarios, user flows, and lifecycle walkthroughs for merchant collections, RRR generation, and utility vending.

Handle's collection platform enables two primary integration models for apps, fintechs, and merchant platforms.

```mermaid theme={null}
graph TD
    A[Customer Payment Intent] --> B{What are they paying for?}
    B -->|Utilities, Airtime, Data, TV| C[VAS Vending Flow]
    B -->|School Fees, MDA Taxes, Parastatals| D[Biller Discovery & Dynamic RRR Flow]
    B -->|Has 12-digit RRR from Invoice/Portal| E[RRR Lookup & Direct Settlement Flow]

    C --> C1[1. Validate Meter/Phone] --> C2[2. Vend Token / Units]
    D --> D1[1. Select Institution & Product] --> D2[2. Fill Dynamic Custom Fields] --> D3[3. Initiate & Generate RRR] --> D4[4. Process Settlement]
    E --> E1[1. Lookup RRR Details] --> E2[2. Process Settlement]
```

***

## 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

| Capability | Target Industry | Key Endpoints |
| :- | :- | :- |
| **Instant Utility Vending** | Consumer Wallets, SoftPOS | `/vending/validate`, `/vending/transactions` |
| **Biller Catalog Discovery** | SuperApps, Aggregators | `/biller/get-categories`, `/biller/get-billers` |
| **Dynamic Institutional Billing** | EdTech, GovTech, Hospitals | `/biller/{id}/products`, `/biller/initiate` |
| **Invoice / RRR Payment** | Corporate Banking, B2B Pay | `/biller/lookup/{rrr}`, `/biller/process` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.