Orbit Edu Composite Fee Challans, 1Bill Banking Integration & Automated GL Posting

1. Accounting Mission & Banking Clearance Architecture

Educational bursar offices oversee massive monthly billing cycles characterized by complex fee structures, varied sibling discount matrices, multi-tiered transport route surcharges, and fluctuating extracurricular fees. In legacy paper-driven institutions, compiling these varied obligations into separate payment receipts results in severe reconciliation backlogs, uncollected library penalties, and delayed bank clearances.

Modern institutional billing demands a single, unified financial document: the Composite Fee Challan. A composite challan integrates base tuition, computer and science laboratory fees, sports subscriptions, transport charges, and incidental disciplinary or library fines into an atomic financial voucher.

Orbit Edu automates this entire lifecycle, bridging the institutional accounting ledger with the national 1Bill digital payment switch. Guardians can settle educational obligations across physical commercial bank counters, automated teller machines (ATMs), and mobile banking applications without manual cashier intervention.

The operational engine is anchored in apps/api/src/modules/edu/services/fee-challans.service.ts (governing monthly generation cycles via generateMonthlyChallans), apps/api/src/modules/edu/services/fee-challan-pdf.service.ts (rendering 3-part vector A4 Landscape documents via generateChallanPdf and generateBatchChallansPdf), apps/api/src/modules/edu/services/fee-concessions.service.ts (evaluating scholarship discount rules), apps/edu/src/app/admin/fees/page.tsx (the bursar administration console), and the underlying Invoice, InvoiceItem, ClassFeeHead, FeeConcession, and StudentConcession schema entities.

1.1 Operator Authority Matrix

Execution of fee generation and banking reconciliation spans four administrative roles:

1. Bursar Billing Officer (Tier 1 Operator): Configures class fee heads, initiates monthly batch challan compilation, and handles in-person cash desk collections.
2. Accounts Auditor (Tier 2 Specialist): Validates sibling discount and merit scholarship concessions, reconciles bank statement deposits against general ledger balances, and reviews overdue aging reports.
3. Transport & Facilities Liaison (Tier 2 Coordinator): Updates student bus route allocations and meal subscription fees, ensuring accurate line-item passthrough into the fee generation queue.
4. Director of Finance (Tier 3 Executive): Grants final approval for annual fee structure adjustments, authorizes financial hardship fee waivers, and closes monthly fiscal accounting periods.

2. Interactive Bursar Fee Challan Console

The bursar fee management terminal allows operators to generate batch class challans, simulate line-item adjustments, and inspect 1Bill payment streams:

3. 1Bill Consumer ID Generation & Switch Routing

The integration between Orbit Edu and banking switches relies on the 1Link / 1Bill utility payment protocol. The protocol enables any banking application or ATM to dynamically query and clear student invoices.

3.1 Mathematical Consumer Number Specification

As implemented in apps/api/src/modules/edu/services/fee-challan-pdf.service.ts:

ConsumerNumber = BillerPrefix + PadZeroes(ExtractDigits(AdmissionNumber), 6)

Where:

• BillerPrefix = "100829" (the 6-digit institutional identifier allocated by the banking clearing house).
• ExtractDigits(s) removes non-numeric characters from the admission identifier.
• PadZeroes(n, 6) extracts the rightmost 6 digits and zero-pads to the left if shorter.

When a banking app queries the bill payment API with consumer number 100829000001, the backend resolves the active challan record and responds with the standardized 1Bill schema:

{
  "consumerNumber": "100829000001",
  "billerCode": "100829",
  "invoiceNumber": "CHAL-202610-001",
  "studentName": "Muhammad Bilal Aslam",
  "billingMonth": "2026-10",
  "amountWithinDueDate": 23530.00,
  "dueDate": "2026-10-15",
  "amountAfterDueDate": 24030.00,
  "lateFeeAmount": 500.00,
  "status": "UNPAID"
}

4. Operational Runbook: Batch Challan Generation & 3-Part PDF Rendering

The monthly billing workflow consists of three standardized operational stages: Batch Generation, Vector PDF Dispatch, and 1Bill Clearance Ingestion.

Phase 1: Monthly Batch Challan Compilation

1. Initiate Generation Routine:

   • The bursar accesses apps/edu/src/app/admin/fees and selects Batch Generate Monthly Challans (or presses F2 to focus fee batch filters and taps Enter).
   • Select the target billing month (e.g., 2026-10) and the academic class (or select All Enrolled Classes).
   • Set the issue date (05-Oct-2026) and final due date (15-Oct-2026).

2. Automated Line-Item Consolidations:

   • The system calls FeeChallansService.generateMonthlyChallans().
   • For every enrolled student, the service reads the class base fee heads.
   • Evaluates Fee Concessions for sibling and scholarship waivers, adding negative price line items.
   • Queries TransportService.listAllocations() to include active bus route fees.
   • Queries LibraryService.listLoans() to attach unpaid overdue library penalties.

3. Invoice Number & Database Persistence:

   • Creates an immutable invoice record conforming to the bounded schema CHAL-${monthKey}-${sanitizedAdm}:

     InvoiceNumber = "CHAL-" + MonthKey + "-" + SanitizedAdmission
     

     (e.g., CHAL-202610-ADM2024001).
   • Inserts items into the relational persistence kernel under Invoice and InvoiceItem.

Phase 2: Vector 3-Part A4 Landscape PDF Rendering

1. PDF Template Construction:

   • The bursar clicks Download Batch PDF or Print Selected Challans.
   • FeeChallanPdfService generates a vector A4 Landscape document divided into three distinct columns:
     • BANK COPY (Sky Accent, retained by commercial bank cashier).
     • ACCOUNTS OFFICE COPY (Emerald Accent, stamped and returned to school accounts).
     • STUDENT / PARENT COPY (Purple Accent, student official receipt).

2. High-Density Vector Elements:

   • Each copy features the official institutional crest, student biographical header, itemized fee head table, due date settlement totals, late payment surcharge rules, bank authorized signature lines, and high-density 2D QR codes.

3. Guardian Portal & Digital Distribution:

   • Once generated, challan PDFs are instantly published to the Guardian Self-Service Portal.
   • Guardians receive an automated WhatsApp and SMS notification with their 12-digit 1Bill Consumer Number and payment link.

Phase 3: Banking Reconciliation & GL Journal Posting

1. 1Link Settlement File Ingestion:

   • At the conclusion of daily banking clearance (typically T-23:30), the bank switch provides an encrypted settlement file containing transaction logs.
   • The accounts auditor uploads the batch settlement file via the bursar console, or the system receives automated webhook callbacks.

2. Automated Status Advancement:

   • Matches transactions by 1Bill Consumer ID and marks invoice records as paid.
   • Generates double-entry general ledger journal vouchers:

Debit:  Bank Clearing Account (GL 1010)          PKR 23,530.00
Credit: Student Accounts Receivable (GL 1120)    PKR 23,530.00

5. Double-Entry General Ledger Account Mapping

Orbit Edu maintains complete accounting integrity by automatically mapping fee heads to standard Chart of Accounts codes:

6. Failure Modes & Recovery SOP

The following operational contingency protocols resolve edge-case exceptions during fee generation and 1Bill settlements:

7. Cross-Vertical Internal Linkages

The Composite Fee Challan system serves as the institutional billing engine, coordinating directly with other modules in the academic network:

• Registrar 360 Student Dossier & Clearance Gates — Validates zero outstanding tuition balance before authorizing Transfer Certificates.
• Library Barcode Circulation & Overdue Fine Challans — Streams accrued book overdue fines directly into monthly fee challan line items.
• Faculty Monthly Payroll & Currency-in-Words Payslips — Balances institutional fee revenue inflows against faculty operational salary disbursements.
• Universal Double-Entry General Ledger & Chart of Accounts — Synchronizes student accounts receivable with universal balance sheet accounts.
• Customer Khata Debt Ledgers & FIFO Aging — Governs subsidiary credit ledgers and debt aging policies across multi-vertical operations.