Initiate Payment

Overview

This feature is exclusively operated by Institute Admins — they upload the Excel file that generates payment requests for their students. Key capabilities include:

Bulk payment collection creation via Excel upload
Automatic student record creation and updates
Support for multiple fee types in a single collection
Flexible payment modes (Cash and Payment Gateway)
Automated email notifications to parents/guardians
Due date management with late fee calculations
Payment status tracking (Pending, Partially Paid, Fully Paid)
Excel template generation based on institute's configured fee types

Data Models

This section describes the data models you need to implement this feature, along with step-by-step instructions to create them in SolidX.

New to the Module Builder?

If you're unfamiliar with how modules, models, and fields work in SolidX, we recommend reviewing the Module Builder documentation first. It covers:

Module Management - Creating and configuring modules
Model Management - Creating models and understanding model settings
Field Management - Understanding field types and configuration options

How These Models Connect

Understanding the relationships between your data:

Payment Collection (Batch: "Q1 2024 Fees")
  │
  ├── Contains multiple Payment Collection Items
  │   │
  │   ├── Item 1: Rahul Sharma - Tuition Fees - ₹10,000
  │   │   ├── Links to: Student (Rahul Sharma)
  │   │   ├── Links to: Fee Type (Tuition Fees)
  │   │   └── Has multiple Payment Collection Item Details
  │   │       ├── Detail 1: Paid ₹5,000 on 2024-03-15
  │   │       └── Detail 2: Paid ₹5,000 on 2024-04-10
  │   │
  │   ├── Item 2: Rahul Sharma - Bus Fees - ₹3,000
  │   │   └── Links to: Fee Type (Bus Fees)
  │   │
  │   └── Item 3: Priya Patel - Tuition Fees - ₹10,000
  │       └── Links to: Student (Priya Patel)
  │
  └── All items share same Payment Collection

Student (Rahul Sharma)
  ├── Has multiple Payment Collection Items across different collections
  │   ├── From "Q1 2024 Fees" collection
  │   ├── From "Annual Sports Fees" collection
  │   └── From "Library Fees" collection
  │
  └── Belongs to one Institute

Fee Type (Tuition Fees)
  ├── Used in multiple Payment Collection Items
  │   └── Different students, different collections
  │
  ├── Defines: Part payment allowed?
  └── Defines: Late fee calculation rules

Important Concepts

Automatic Student Management:

When you upload an Excel file, the system checks if each student already exists (by Student ID)
If the student exists: Updates their information with latest data from Excel
If the student is new: Creates a new student record automatically
You don't need to manually create students before uploading payment collections

Status Flow for Payment Gateway Items:

Upload Excel (PG mode) → Status: "Pending"
                              ↓
                     Student pays 50%
                              ↓
                    Status: "Partially Paid"
                              ↓
                     Student pays remaining
                              ↓
                    Status: "Fully Paid"

Status Flow for Cash Items:

Upload Excel (CASH mode) → Status: "Fully Paid"
                                 ↓
                         No further action needed

Late Fee Calculation:

Runs automatically via scheduled job
Only applies to items with status "Pending" or "Partially Paid"
Calculation method comes from Fee Type configuration:
- Percent: (pending amount × late fee %) ÷ 100
- Absolute: Fixed late fee amount
- None: No late fees applied
Updates total amount to be paid automatically

1. Student Model

Individual students enrolled at your institution whose parents/guardians will receive payment collection requests.

Model Configuration

Setting	Value
Singular Name	student
Plural Name	students
Display Name	Student
Description	Model to capture student information
Data Source	default
Data Source Type	postgres
Table Name	fees_portal_student
Enable Audit Tracking	Yes
Enable Soft Delete	No
Draft Publish Workflow	No
Internationalization	No
Is Child Model	No

Fields

#	Name	Display Name	Type	Req?	Key Config
1	`studentName`	Student Name	Short Text	Yes	Audit
2	`studentEmailAddress`	Student Email Address	Short Text	No	Audit
3	`studentMobileNumber`	Student Mobile Number	Short Text	No	Audit
4	`parentName`	Parent/Guardian Name	Short Text	Yes	Audit
5	`parentMobileNumber`	Parent/Guardian Mobile Number	Short Text	Yes	Audit
6	`parentEmailAddress`	Parent/Guardian Email Address	Short Text	Yes	Audit
7	`studentId`	Student Id	Short Text	Yes	Is User Key Audit
8	`institute`	Institute	Relation	Yes	Many-to-One → `institute` (fees-portal) Create Inverse: No Cascade Index Audit
9	`studentLoginId`	Student Login Id	Computed	Yes	Unique Type: string Provider: `AlphaNumExternalIdComputationProvider` Generates unique alphanumeric login ID from student name, length 5 (full config ↓) Trigger: before-insert on `student` (fees-portal) Audit
10	`otp`	OTP	Short Text	No	—
11	`otpExpiresAt`	OTP Expires At	Datetime	No	—
12	`token`	Token	Long Text	No	—

Students are automatically created (or updated) when you upload a payment collection Excel file — matched by Student ID. Students can log in to the portal using their studentLoginId and OTP.

Deferred relation

The payments (One-to-Many → payment) field is not added here because the payment model does not exist yet. It is auto-created when you add the student field on the Payment model in Student Payment Portal (field 7, Create Inverse: Yes).

studentLoginId — Full provider context JSON

{"dynamicFieldPrefix": "studentName", "length": 5}

2. Payment Collection Model

A batch of fee collection requests sent to multiple students at once (e.g., "Q1 2024 Fees", "Annual Sports Fees 2024").

Model Configuration

Setting	Value
Singular Name	paymentCollection
Plural Name	paymentCollections
Display Name	Payment Collection
Description	Model used to capture information about a payment collection. A payment collection is a batch of payments that are collected together.
Data Source	default
Data Source Type	postgres
Table Name	fees_portal_payment_collection
Enable Audit Tracking	Yes
Enable Soft Delete	No
Draft Publish Workflow	No
Internationalization	No
Is Child Model	No

Fields

#	Name	Display Name	Type	Req?	Key Config
1	`name`	Name	Short Text	Yes	Index Is User Key Audit
2	`description`	Description	Long Text	No	—
3	`dueDate`	Due Date	Datetime	Yes	Audit
4	`paymentCollectionId`	Payment Collection ID	Computed	Yes	Unique Index Type: string Provider: `AlphaNumExternalIdComputationProvider` Generates unique alphanumeric ID from collection name, length 5 (full config ↓) Trigger: before-insert on `paymentCollection` (fees-portal) Audit
5	`institute`	Institute	Relation	Yes	Many-to-One → `institute` (fees-portal) Create Inverse: No Cascade Index Audit
6	`paymentFile`	Payment File	Media (Single)	Yes	file max 5120 KB default-filesystem

The paymentCollectionItems relation is added in Step 5 after the paymentCollectionItem model exists. Deleting a Payment Collection cascades to all its Payment Collection Items via that relation.

paymentCollectionId — Full provider context JSON

{"dynamicFieldPrefix": "name", "length": 5}

3. Payment Collection Item Model

An individual payment request for one student for one fee type within a collection (e.g., "Rahul Sharma needs to pay ₹10,000 for Tuition Fees").

Model Configuration

Setting	Value
Singular Name	paymentCollectionItem
Plural Name	paymentCollectionItems
Display Name	Payment Collection Item
Description	Model used to capture information about a payment collection item. A payment collection item is a single payment within a payment collection.
Data Source	default
Data Source Type	postgres
Table Name	fees_portal_payment_collection_item
Enable Audit Tracking	Yes
Enable Soft Delete	No
Draft Publish Workflow	No
Internationalization	No
Is Child Model	No

Fields

#	Name	Display Name	Type	Req?	Key Config
1	`dueDate`	Due Date	Datetime	Yes	Audit
2	`partPaymentAllowed`	Part Payment Allowed	Boolean	Yes	Default: `false` Audit
3	`status`	Status	Short Text	Yes	Default: `Pending` Index Audit
4	`amountPaid`	Amount Paid	Computed	Yes	Type: Decimal Provider: `PaymentCollectionItemAmountProvider` Sums all successful payments for this item (provider context: `{}`) Trigger: after-update on `paymentCollectionItemDetail` Audit
5	`amountPending`	Amount Pending	Computed	Yes	Type: Decimal Provider: `NoopsEntityComputedFieldProviderService` Placeholder — actual value is `amountToBePaid - amountPaid` (provider context: `{}`) Trigger: before-insert on `paymentCollectionItemDetail` Audit
6	`isOverdue`	Is Overdue	Boolean	Yes	Default: `false` Audit
7	`overdueByDays`	Overdue By Days	Integer	No	Audit
8	`lateAmountToBePaid`	Late Amount To Be Paid	Decimal	No	Default: `0` Audit
9	`totalAmountToBePaid`	Total Amount To Be Paid	Computed	No	Type: Decimal Provider: `NoopsEntityComputedFieldProviderService` Placeholder — actual value is `amountToBePaid + lateAmountToBePaid` (provider context: `{}`) Trigger: before-insert on `paymentCollectionItemDetail` Audit
10	`amountToBePaid`	Amount To Be Paid	Decimal	Yes	Audit
11	`mode`	Mode	Short Text	Yes	`CASH` or `PG` (Payment Gateway) Audit
12	`student`	Student	Relation	Yes	Many-to-One → `student` (fees-portal) Create Inverse: No Cascade Index Audit
13	`paymentCollection`	Payment Collection	Relation	Yes	Many-to-One → `paymentCollection` (fees-portal) Inverse field: `paymentCollectionItems` Create Inverse: Yes Cascade Index Audit
14	`institute`	Institute	Relation	Yes	Many-to-One → `institute` (fees-portal) Create Inverse: No Cascade Index Audit
15	`feeType`	Fee Type	Relation	Yes	Many-to-One → `feeType` (fees-portal) Create Inverse: No Cascade Index Audit

Payment Modes: Choose PG when parents will pay online (initial status: Pending); choose CASH when payment has already been collected offline (initial status: Fully Paid). The paymentCollectionItemDetails relation is added in Step 5 after the paymentCollectionItemDetail model exists.

4. Payment Collection Item Detail Model

Individual payment transactions recorded against a payment collection item — tracks each installment or payment attempt.

Model Configuration

Setting	Value
Singular Name	paymentCollectionItemDetail
Plural Name	paymentCollectionItemDetails
Display Name	Payment Collection Item Detail
Description	Model used to capture individual payment transactions for a payment collection item
Data Source	default
Data Source Type	postgres
Table Name	fees_portal_payment_collection_item_detail
Enable Audit Tracking	Yes
Enable Soft Delete	No
Draft Publish Workflow	No
Internationalization	No
Is Child Model	No

Fields

#	Name	Display Name	Type	Req?	Key Config
1	`paymentDate`	Payment Date	Datetime	Yes	Audit
2	`paymentStatus`	Payment Status	Short Text	Yes	Default: `Pending` Audit
3	`amountPaid`	Amount Paid	Decimal	Yes	Audit
4	`institute`	Institute	Relation	Yes	Many-to-One → `institute` (fees-portal) Create Inverse: No Cascade Index Audit
5	`student`	Student	Relation	Yes	Many-to-One → `student` (fees-portal) Create Inverse: No Cascade Index Audit
6	`paymentCollectionItem`	Payment Collection Item	Relation	Yes	Many-to-One → `paymentCollectionItem` (fees-portal) Inverse field: `paymentCollectionItemDetails` Create Inverse: Yes Cascade Index Audit

Deferred relation

The payment (Many-to-One → payment) field is not added here because the payment model does not exist yet. It is auto-created when you add the paymentCollectionItemDetails field on the Payment model in Student Payment Portal (field 9, Create Inverse: Yes).

5. Adding Relation Fields

Now that all four models exist, return to the following models and add the deferred relation fields.

Why add these last?

SolidX requires the co-model to already exist before you can create a relation pointing to it. The two One-to-Many fields below reference models that were not yet created when their parent models were built.

Payment Collection — add field 7:

#	Name	Display Name	Type	Req?	Key Config
7	`paymentCollectionItems`	Payment Collection Items	Relation	—	One-to-Many → `paymentCollectionItem` (fees-portal) Inverse field: `paymentCollection` Create Inverse: Yes Cascade

Payment Collection Item — add field 16:

#	Name	Display Name	Type	Req?	Key Config
16	`paymentCollectionItemDetails`	Payment Collection Item Details	Relation	—	One-to-Many → `paymentCollectionItemDetail` (fees-portal) Inverse field: `paymentCollectionItem` Create Inverse: Yes Cascade

The payments field on Student and the payment field on Payment Collection Item Detail are handled automatically in Student Payment Portal when the payment model is created (via Create Inverse: Yes on fields 7 and 9 respectively).

Quick Reference

For a handy summary of field types and configuration options used in this tutorial, see:

📚 Field Type Reference - Quick-reference table of field types and their key attributes
⚙️ Configuration Notes - Quick tips on relations, cascading, audit tracking, and more

For comprehensive documentation, refer to the Module Builder section.

Generating APIs and UI Components

Once you've created the data models, you'll need to generate the REST APIs and UI components.

Reference Documentation

📋 For detailed step-by-step instructions, see Generating APIs and UI Components

Creating Roles & Permissions

With the models and APIs in place, configure who can access them. Permissions are granted per model and map directly to the controller methods generated in the previous step.

Super Admin

Super Admin is granted all permissions by default. No role configuration needed.

Institute Admin

On the existing Institute Admin role, grant the following additional permissions:

Model	Permissions
Student	`StudentController.create` `StudentController.insertMany` `StudentController.findOne` `StudentController.findMany` `StudentController.update` `StudentController.partialUpdate`
Payment Collection	`PaymentCollectionController.create` `PaymentCollectionController.findOne` `PaymentCollectionController.findMany` `PaymentCollectionController.update` `PaymentCollectionController.partialUpdate`
Payment Collection Item	`PaymentCollectionItemController.findOne` `PaymentCollectionItemController.findMany` `PaymentCollectionItemController.cancelMany`
Payment Collection Item Detail	`PaymentCollectionItemDetailController.findOne` `PaymentCollectionItemDetailController.findMany`

Why these permissions?

Student — Institute Admin needs to view student records and make manual corrections. Students are primarily created via Excel upload (insertMany) but can also be added individually. No delete, as student records should persist for payment history.
Payment Collection — Institute Admin creates and manages collection batches. No insertMany (collections are always created one at a time with a specific Excel file) and no delete (collections are permanent audit records).
Payment Collection Item — Items are generated automatically by the Excel upload; Institute Admin never creates them manually. cancelMany allows bulk-cancelling items when a collection needs to be voided.
Payment Collection Item Detail — Purely a read-only view for Institute Admin; details are recorded by the payment gateway callback process, not manually.

Reference Documentation

📋 For step-by-step instructions on editing a role and assigning permissions in SolidX, see Role Management.

Implementing Custom Business Logic

While SolidX auto-generates basic CRUD operations, the payment collection feature requires custom business logic for Excel processing, student management, and email notifications. This section explains the key customizations needed.

1. Excel Upload Validation

Before processing the uploaded Excel file, validation ensures data quality and prevents errors.

Implementation Location: Payment Collection Service

File: solid-api/src/fees-portal/services/payment-collection.service.ts
Method: feeTypeValidation()

What It Does:

Excel Structure Validation
- Reads the uploaded Excel file using the ExcelService's readExcelFromStreamNonStreaming() method
- Identifies header row and extracts column names
- Known columns: Student Name, Student Id, Parent/Guardian Name/Email/Mobile, Payment Mode
- Fee type columns: Any column not in Known Columns and not containing "Due Date" or Payment Mode is treated as a fee type column
Fee Type Validation
- Extracts unique fee types from Excel headers
- Queries the database for institute's configured Fee Types
- Throws error if any fee type in Excel is not configured
- Error message example: "Fee type 'Lab Fees' is not configured for your institute"
Due Date Validation
- Ensures all due dates are today or in the future
- Rejects past due dates with detailed error messages
- Supports both string format (yyyy-mm-dd) and Excel date types
- Example error: "Row 5: Due date for 'Tuition Fees' cannot be in the past"
Payment Mode Validation
- Only "CASH" or "PG" (Payment Gateway) allowed
- Defaults to "PG" if empty
- Case-insensitive validation
- Example error: "Row 3: Invalid payment mode 'CHECK'. Use 'CASH' or 'PG'"
Email Validation
- Parent/Guardian email must be lowercase
- Email is mandatory
- Basic format validation

Key Code Pattern:

import { ExcelService } from "@solidxai/core";
import { createReadStream } from 'fs';

@Injectable()
export class PaymentCollectionService {
  constructor(
    private readonly excelService: ExcelService,
    // ... other dependencies
  ) {}

  async feeTypeValidation(filePath: string, instituteId: number) {
    // Create a readable stream from the file path
    const fileStream = createReadStream(filePath);

    // Read the entire Excel file using ExcelService
    const { headers, rows } = await this.excelService.readExcelFromStreamNonStreaming(
      fileStream,
      {
        hasHeaderRow: true,
        worksheetIndex: 0
      }
    );

    // Extract fee type columns from headers
    const knownColumns = [
      'Student Name', 'Student Id',
      'Parent/Guardian Name', 'Parent/Guardian Email', 'Parent/Guardian Mobile',
      'Payment Mode'
    ];

    const feeTypeColumns = headers.filter(header =>
      !knownColumns.includes(header) &&
      !header.includes('Due Date')
    );

    const excelFeeTypes = [...new Set(feeTypeColumns)]; // Get unique fee types

    // Validate fee types against database
    const instituteFeeTypes = await this.getFeeTypesForInstitute(instituteId);
    const invalidFeeTypes = excelFeeTypes.filter(
      ft => !instituteFeeTypes.map(f => f.feeType).includes(ft)
    );

    if (invalidFeeTypes.length > 0) {
      throw new Error(`Fee types not configured: ${invalidFeeTypes.join(', ')}`);
    }

    // Validate each row
    const today = new Date();
    today.setHours(0, 0, 0, 0);

    for (let i = 0; i < rows.length; i++) {
      const row = rows[i];
      const rowNumber = i + 2; // +2 because Excel rows start at 1 and row 1 is headers

      // Validate due dates for each fee type
      for (const feeType of excelFeeTypes) {
        const dueDateColumn = `${feeType} Due Date`;
        const amountColumn = `${feeType} Amount`;

        const amount = row[amountColumn];
        const dueDate = row[dueDateColumn];

        // Only validate if amount is provided
        if (amount && parseFloat(amount) > 0) {
          if (!dueDate) {
            throw new Error(
              `Row ${rowNumber}: Due date is required for '${feeType}' when amount is specified`
            );
          }

          const dueDateObj = new Date(dueDate);
          if (dueDateObj < today) {
            throw new Error(
              `Row ${rowNumber}: Due date for '${feeType}' cannot be in the past`
            );
          }
        }
      }

      // Validate payment mode
      const paymentMode = row['Payment Mode']?.toString().toUpperCase() || 'PG';
      if (!['CASH', 'PG'].includes(paymentMode)) {
        throw new Error(
          `Row ${rowNumber}: Invalid payment mode '${row['Payment Mode']}'. Use 'CASH' or 'PG'`
        );
      }

      // Validate required fields
      if (!row['Parent/Guardian Email']) {
        throw new Error(`Row ${rowNumber}: Parent/Guardian Email is required`);
      }
    }

    return { headers, rows };
  }
}

2. Excel Template Generation

To help users format their Excel correctly, SolidX provides template generation.

Implementation Location: Generate Fee Collection Report Service

File: solid-api/src/fees-portal/services/generate-fee-collection-report.service.ts
Endpoint: GET /api/generate-fee-reports?id={instituteId}

What It Does:

Fetches institute's configured fee types from database
Generates Excel with dynamic headers based on fee types
Headers format:
- Fixed columns: Student Name, Student Id, Parent/Guardian Name, Parent/Guardian Email, Parent/Guardian Mobile
- Dynamic columns: For each fee type: {FeeType} Amount, {FeeType} Due Date
- Last column: Payment Mode
Includes sample row with today's date
Returns downloadable Excel file

Template Structure Example:

Student Name	Student Id	Parent/Guardian Name	Parent/Guardian Email	Parent/Guardian Mobile	Tuition Fees Amount	Tuition Fees Due Date	Bus Fees Amount	Bus Fees Due Date	Payment Mode
Rahul Sharma	STU001	Mr. Rajesh Sharma	rajesh@example.com	9123456789	10000	2024-04-30	3000	2024-04-30	PG

3. File Processing with TypeORM Event Subscriber

The core processing logic uses TypeORM's Event Subscriber pattern to automatically process Excel files after upload.

Implementation Location: Media Transaction Subscriber

File: solid-api/src/fees-portal/subscriber/media-transaction.subscriber.ts
Event: afterInsert on Media entity

How It Works:

When a file is uploaded for the Payment Collection model:

TypeORM fires afterInsert event after Media record is saved
Subscriber checks if media belongs to paymentCollection model
If yes, triggers paymentCollectionTransaction() method
Processing happens synchronously within the database transaction

Processing Flow:

Excel Upload
    ↓
Media Entity Insert
    ↓
afterInsert Event Fired
    ↓
Read Excel using ExcelService
    ↓
For Each Row in Excel:
    ↓
    ├── Find or Create Student
    │   ├── Search by Student ID + Institute
    │   ├── If found: Update details
    │   └── If not found: Create new
    ↓
    ├── Create Payment Collection Items
    │   └── For each Fee Type with amount > 0:
    │       ├── Read amount, due date, mode
    │       ├── If mode = CASH:
    │       │   └── Status = "Fully Paid"
    │       └── If mode = PG:
    │           └── Status = "Pending"
    ↓
    └── Send Email Notification
        ├── If all items CASH (Fully Paid):
        │   └── Send payment success email
        └── If any items PG (Pending):
            └── Send due fees email with payment link

Key Code Pattern:

import { ExcelService } from "@solidxai/core";
import { createReadStream } from 'fs';

@EventSubscriber()
export class MediaTransactionSubscriber implements EntitySubscriberInterface<Media> {
  constructor(
    private readonly excelService: ExcelService,
    // ... other dependencies
  ) {}

  async afterInsert(event: InsertEvent<Media>) {
    const media = event.entity;

    if (media.modelName === 'paymentCollection') {
      await this.paymentCollectionTransaction(media, event.manager);
    }
  }

  async paymentCollectionTransaction(media: Media, entityManager: EntityManager) {
    // Get file path from media entity
    const filePath = media.filePath; // Adjust based on your Media entity structure

    // Create a readable stream from the file path
    const fileStream = createReadStream(filePath);

    // Read the entire Excel file using ExcelService
    const { headers, rows } = await this.excelService.readExcelFromStreamNonStreaming(
      fileStream,
      {
        hasHeaderRow: true,
        worksheetIndex: 0
      }
    );

    // Process each row
    for (const row of rows) {
      await this.processRow(row, headers, entityManager);
    }
  }

  async processRow(
    row: Record<string, any>,
    headers: string[],
    entityManager: EntityManager
  ) {
    // Extract student data from row using header keys
    const studentData = {
      studentId: row['Student Id'],
      studentName: row['Student Name'],
      parentName: row['Parent/Guardian Name'],
      parentEmailAddress: row['Parent/Guardian Email']?.toLowerCase(),
      parentMobileNumber: row['Parent/Guardian Mobile'],
      // ... other fields
    };

    // Process student and payment items
    // ... (see next section for details)
  }
}

4. Student Management Logic

Method: processRow() in Media Transaction Subscriber

Student Creation/Update Logic:

async processRow(
  row: Record<string, any>,
  headers: string[],
  entityManager: EntityManager
) {
  // Extract student data from the row object
  // The ExcelService returns rows as objects with header keys
  const studentData = {
    studentId: row['Student Id'],
    studentName: row['Student Name'],
    parentName: row['Parent/Guardian Name'],
    parentEmailAddress: row['Parent/Guardian Email']?.toLowerCase(),
    parentMobileNumber: row['Parent/Guardian Mobile'],
    institute: { id: instituteId }
  };

  // Find existing student
  let student = await entityManager.findOne(Student, {
    where: {
      studentId: studentData.studentId,
      institute: { id: instituteId }
    }
  });

  if (student) {
    // Update existing student
    student.studentName = studentData.studentName;
    student.parentName = studentData.parentName;
    student.parentEmailAddress = studentData.parentEmailAddress;
    student.parentMobileNumber = studentData.parentMobileNumber;
  } else {
    // Create new student
    student = entityManager.create(Student, studentData);
  }

  await entityManager.save(Student, student);

  // Continue processing payment items for this student
  await this.createPaymentItems(row, headers, student, entityManager);
}

Important Notes:

Student uniqueness is determined by: Student ID + Institute
Updates overwrite existing data (name, parent info, contact details)
Student Login ID is generated separately (not from Excel)
Institute is always set from logged-in user's context i.e (pre-populated on the frontend depending on the institute the Institute Admin belongs to)
The ExcelService's readExcelFromStreamNonStreaming() returns rows as objects with column headers as keys, making data access simpler and more readable

5. Payment Collection Item Creation

For Each Fee Type in Excel:

async createPaymentItems(
  row: Record<string, any>,
  headers: string[],
  student: Student,
  entityManager: EntityManager
) {
  // Get fee types for this institute
  const instituteFeeTypes = await entityManager.find(FeeType, {
    where: { institute: { id: instituteId } }
  });

  // Extract fee type columns from headers
  const feeTypeColumns = headers.filter(
    header => !['Student Name', 'Student Id', 'Parent/Guardian Name',
                'Parent/Guardian Email', 'Parent/Guardian Mobile',
                'Payment Mode'].includes(header) &&
                !header.includes('Due Date')
  );

  // Process each fee type
  for (const feeType of instituteFeeTypes) {
    const amountColumnName = `${feeType.feeType} Amount`;
    const dueDateColumnName = `${feeType.feeType} Due Date`;

    // Access data using the column names as object keys
    const amount = row[amountColumnName];
    const dueDate = row[dueDateColumnName];
    const paymentMode = row['Payment Mode'] || 'PG';

    // Skip if no amount
    if (!amount || parseFloat(amount) <= 0) continue;

    // Determine status based on payment mode
    let status, amountPaid, amountPending;

    if (paymentMode.toString().toUpperCase() === 'CASH') {
      status = 'Fully Paid';
      amountPaid = parseFloat(amount);
      amountPending = 0;
    } else {
      status = 'Pending';
      amountPaid = 0;
      amountPending = parseFloat(amount);
    }

    // Create payment collection item
    const item = entityManager.create(PaymentCollectionItem, {
      student: student,
      feeType: feeType,
      paymentCollection: paymentCollection,
      institute: { id: instituteId },
      amountToBePaid: parseFloat(amount),
      dueDate: new Date(dueDate),
      partPaymentAllowed: feeType.partPaymentAllowed,
      status: status,
      amountPaid: amountPaid,
      amountPending: amountPending,
      totalAmountToBePaid: parseFloat(amount),
      mode: paymentMode.toString().toUpperCase()
    });

    await entityManager.save(PaymentCollectionItem, item);
  }
}

Benefits of Using ExcelService:

Clean object-based access to cell values using column headers as keys
Automatic handling of different Excel cell types (numbers, dates, strings)
Built-in support for rich text, formulas, and hyperlinks
No need to manage cell indices or column mappings manually
Consistent data normalization across the application

6. Email Notification Logic

Method: sendEmailNotification() in Media Transaction Subscriber

Decision Logic:

// Fetch all items for this student + payment collection
const items = await entityManager.find(PaymentCollectionItem, {
  where: {
    student: { id: student.id },
    paymentCollection: { id: paymentCollection.id }
  },
  relations: ['feeType', 'institute']
});

// Check if all items are fully paid (CASH mode)
const allFullyPaid = items.every(item => item.status === 'Fully Paid');

if (allFullyPaid) {
  // Send payment success email
  await mailFactory.sendEmailUsingTemplate(
    student.parentEmailAddress, //to
    'fees-portal-payment-success', //template name
    { // templateParams
      student: student,
      paymentDetails: {
        totalAmount: items.reduce((sum, item) => sum + item.amountPaid, 0),
        feeTypes: items.map(item => item.feeType.feeType).join(', '),
        status: 'Fully Paid',
        createdDate: new Date()
      },
      instituteLogo: institute.logo,
    },
    true //shouldQueueEmails
  );
} else {
  // Send due fees email with payment link
  const redirectUrl = `https://${institute.hostedPagePrefix}-${EDU_BASE_DOMAIN}/?id=${student.studentLoginId}`;

  await mailFactory.sendEmailUsingTemplate(
    student.parentEmailAddress, //to
    'new-payment-or-payment-reminder', //template name
    { // templateParams
      student: student,
      dueDetails: {
        totalAmount: items.reduce((sum, item) => sum + item.amountPending, 0),
        feeTypes: items.map(item => item.feeType.feeType).join(', '),
        status: 'Pending',
        redirectUrl: redirectUrl,
        createdDate: new Date()
      },
      instituteLogo: institute.logo,
    },
    true //shouldQueueEmails
  );
}

Email Templates:

Payment Success Email (fees-portal-payment-success.handlebars.html)
- Triggered when: All items have status "Fully Paid" (CASH mode)
- Shows: Confirmation of payment received, total amount, fee types
- No action needed from parent
Due Fees Email (fees-portal-new-payment-or-payment-reminder.handlebars.html)
- Triggered when: Any item has status "Pending" (PG mode)
- Shows: Amount due, fee types, due dates, payment link
- Call to action: "Pay Now" button linking to student portal

Template Location: solid-api/module-metadata/fees-portal/email-templates/

7. Computed Field for Amount Calculations

When payments are made through the payment gateway, amounts need to be recalculated.

Implementation Location: Payment Collection Item Amount Provider

File: solid-api/src/fees-portal/computed-providers/payment-collection-item-amount-provider.ts
Trigger: After Payment Collection Item Detail save

What It Does:

// Triggered when payment detail is saved
async computeFieldValue(entity: PaymentCollectionItemDetail) {
  const item = entity.paymentCollectionItem;

  // Sum all successful payment details
  const totalPaid = await this.sumSuccessfulPayments(item.id);

  // Calculate pending amount
  const totalAmount = item.amountToBePaid + (item.lateAmountToBePaid || 0);
  const pending = totalAmount - totalPaid;

  // Determine status
  let status;
  if (pending <= 0) {
    status = 'Fully Paid';
  } else if (totalPaid > 0) {
    status = 'Partially Paid';
  } else {
    status = 'Pending';
  }

  // Update item
  await this.update(item.id, {
    amountPaid: totalPaid,
    amountPending: pending,
    totalAmountToBePaid: totalAmount,
    status: status
  });
}

8. Scheduled Jobs

The payment collection feature uses two scheduled jobs to automate late fee calculation and email reminders.

Reference Documentation

📋 For detailed information about scheduled jobs configuration, properties, and best practices, see Scheduled Jobs

Job 1: Late Fee Calculator

File: solid-api/src/fees-portal/scheduled-jobs/late-fee-payment-calculator-scheduled-job.service.ts
Class Name: LateFeePaymentCalculatorScheduledJob
Frequency: Hourly (runs every hour, all days of the week)
Purpose: Calculate and apply late fees for overdue payments

Configuration in metadata JSON:

{
  "scheduleName": "Late Fee Calculation",
  "isActive": true,
  "frequency": "Hourly",
  "job": "LateFeePaymentCalculatorScheduledJob",
  "moduleUserKey": "fees-portal"
}

What It Does:

// Find overdue items
const overdueItems = await this.find({
  where: {
    dueDate: LessThan(new Date()),
    status: Not(In(['Cancelled', 'Fully Paid']))
  },
  relations: ['feeType']
});

// Calculate late fees
for (const item of overdueItems) {
  const overdueDays = Math.floor((today - item.dueDate) / (1000 * 60 * 60 * 24));
  const pendingAmount = parseFloat(item.amountPending);

  let lateFee = 0;
  if (item.feeType.latePaymentFeesType === 'Percent') {
    lateFee = (pendingAmount * item.feeType.latePaymentFees) / 100;
  } else if (item.feeType.latePaymentFeesType === 'Absolute') {
    lateFee = item.feeType.latePaymentFees;
  }

  await this.update(item.id, {
    isOverdue: true,
    overdueByDays: overdueDays,
    lateAmountToBePaid: lateFee,
    totalAmountToBePaid: pendingAmount + lateFee
  });
}

Job 2: Fees Due Email Reminder

File: solid-api/src/fees-portal/scheduled-jobs/send-email-schedule-jobs.service.ts
Class Name: SendEmailScheduleJobs
Frequency: Daily (runs once per day, all days of the week)
Purpose: Send payment reminders to parents with pending fees

Configuration in metadata JSON:

{
  "scheduleName": "Fees Due Email",
  "isActive": true,
  "frequency": "Daily",
  "job": "SendEmailScheduleJobs",
  "moduleUserKey": "fees-portal"
}

What It Does:

// Find pending items
const pendingItems = await this.find({
  where: {
    status: In(['Pending', 'Partially Paid'])
  },
  relations: ['student', 'feeType', 'institute']
});

// Group by student
const groupedByStudent = this.groupBy(pendingItems, 'student.id');

// Send reminders
for (const [studentId, items] of Object.entries(groupedByStudent)) {
  const student = items[0].student;
  const institute = items[0].institute;

  await mailFactory.sendEmailUsingTemplate(
    student.parentEmailAddress,
    'new-payment-or-payment-reminder',
    {
      student: student,
      dueDetails: {
        totalAmount: items.reduce((sum, item) => sum + parseFloat(item.amountPending), 0),
        feeTypes: items.map(item => item.feeType.feeType).join(', '),
        redirectUrl: `https://${institute.hostedPagePrefix}-${EDU_BASE_DOMAIN}/?id=${student.studentLoginId}`
      },
      instituteLogo: institute.logo,
    },
    true
  );
}

Implementation Order

Follow this sequence when implementing custom business logic:

Create validation service method (feeTypeValidation)
Implement template generation service
Create event subscriber for Excel processing
Implement student creation/update logic
Implement payment item creation logic
Implement email notification logic
Create computed field provider for amount calculations
Set up scheduled jobs for late fees and reminders
Test end-to-end flow with sample Excel file

Excel Service Integration

All Excel file operations in this feature use the centralized ExcelService for consistency:

Key Methods Used:

readExcelFromStreamNonStreaming(): For validation and processing Excel files
- Returns { headers: string[], rows: Record<string, any>[] }
- Handles complex cell types (rich text, formulas, dates)
- Provides clean object-based access using column headers as keys
createExcelStream(): For generating templates
- Accepts custom headers array
- Creates downloadable Excel files with proper formatting

Benefits:

Consistent data normalization across the application
Automatic handling of Excel-specific data types
Built-in support for streaming large files
Clean, maintainable code without low-level ExcelJS complexity
Reusable service for all import/export operations

Alternative Approach: For very large files that may cause memory issues, consider using readExcelInPagesFromStream() which returns an async generator for processing rows in chunks. However, for typical payment collection files (hundreds to thousands of rows), readExcelFromStreamNonStreaming() provides better performance and simpler code.

Customizing the UI

After generating the code using SolidX, default list and form views are automatically created for each model. However, these default views need customization to provide a streamlined payment collection workflow. This section explains how to customize these views using layout JSON configuration and UI extensions.

To learn how to apply these customizations, see Applying View Customizations.

Payment Collection Form View Customizations

The customized Payment Collection Form View with template download functionality.

1. Simplified Field Layout

The Payment Collection form displays only essential fields in a single-column layout:

Field	Purpose	Visibility
Name	Identify this collection batch	Always visible
Description	Additional context (optional)	Always visible
Due Date	Default due date for all items	Always visible
Institute	Which institute (auto-filled for Institute Admin)	Hidden for new records, visible when editing
Payment File	Excel upload	Disabled when editing existing records

Layout JSON Snippet:

{
  "type": "column",
  "attrs": {
    "name": "group-1",
    "label": "Payment Collection Details",
    "className": "col-12"
  },
  "children": [
    {
      "type": "field",
      "attrs": {
        "name": "name"
      }
    },
    {
      "type": "field",
      "attrs": {
        "name": "description"
      }
    },
    {
      "type": "field",
      "attrs": {
        "name": "dueDate"
      }
    },
    {
      "type": "field",
      "attrs": {
        "name": "institute"
      }
    },
    {
      "type": "field",
      "attrs": {
        "name": "paymentFile"
      }
    }
  ]
}

Benefits:

Simple, focused interface for primary task
No overwhelming options or tabs
Clear workflow: Select Institute → Select Due Date → Upload

2. Form Load Handler for Conditional Field Behavior and Pre-filling

Extension: paymentCollectionOnFormLoadHandler.ts

This unified handler controls field behavior and pre-fills data based on context:

export function paymentCollectionOnFormLoadHandler(formContext) {
  const { formData, userData, userRole, isEditMode } = formContext;

  // Disable fields when editing existing record
  if (isEditMode) {
    formContext.setFieldProperty('name', 'disabled', true);
    formContext.setFieldProperty('institute', 'disabled', true);
    formContext.setFieldProperty('paymentFile', 'disabled', true);
  }

  // Auto-fill institute for Institute Admin users on new records
  if (!isEditMode && userRole === 'Institute Admin' && userData.institute) {
    formContext.setFieldValue('institute', userData.institute.id);
  }
}

Rationale:

Disable name when editing: Payment collection name identifies the batch; changing it after processing would cause confusion
Disable institute when editing: Institute cannot change after items are created
Disable payment file when editing: Excel is processed on upload; re-uploading would create duplicate items
Auto-fill institute: Institute Admins only manage their own institute
Unified handler: Combines layout and data loading logic in a single handler for better maintainability

Benefits:

Single handler for all form initialization logic
Reduces data entry for Institute Admins
Maintains data integrity
Follows current best practices

4. Excel Template Download Button

Add a button directly in the form header using the formButtons configuration. This button will trigger a custom action to download the Excel template.

Step 1: Configure Form Button in Layout JSON

{
  "name": "paymentCollection-form-view",
  "displayName": "Initiate Payments",
  "type": "form",
  "context": "{}",
  "moduleUserKey": "fees-portal",
  "modelUserKey": "paymentCollection",
  "layout": {
    "type": "form",
    "attrs": {
      "name": "form-1",
      "label": "Initiate Payments",
      "className": "grid",
      "showCogWheelFormButton": false,
      "formButtons": [
        {
          "attrs": {
            "className": "p-button p-component p-button-sm",
            "icon": "pi pi-download",
            "label": "Download Sample Excel",
            "action": "GenerateTemplateFormat",
            "customComponentIsSystem": true,
            "actionInContextMenu": false,
            "openInPopup": true
          }
        }
      ]
    },
    "onFormLoad": "paymentCollectionOnFormLoadHandler",
    "children": [
      // ... rest of form layout
    ]
  }
}

This configuration adds a "Download Sample Excel" button in the form header that:

Displays the download icon (pi pi-download)
Triggers the GenerateTemplateFormat action when clicked
Opens in a popup for better user experience
Appears alongside other form action buttons

Step 2: Implement the Custom Action Component

Create the action handler that will be triggered when the button is clicked. SolidX automatically maps the action name from the form button configuration to the corresponding component file.

File: generate-template-format.tsx

import React from 'react';
import { Button } from 'primereact/button';

export function GenerateTemplateFormat({ instituteId }) {
  const handleDownload = async () => {
    const url = `/api/generate-fee-reports?id=${instituteId}`;
    window.open(url, '_blank');
  };

  return (
    <div className="template-download-section">
      <h3>Step 1: Download Excel Template</h3>
      <p>Download the template with your institute's configured fee types</p>
      <Button
        label="Download Template"
        icon="pi pi-download"
        onClick={handleDownload}
        className="p-button-success"
      />
      <hr />
      <h3>Step 2: Upload Completed Excel</h3>
      <p>Fill the template with student and payment details, then upload below</p>
    </div>
  );
}

Benefits:

Seamless integration with form header actions
Guides users through workflow (Download → Fill → Upload)
Template matches institute's fee types dynamically
Reduces formatting errors
Improves user experience with clear step-by-step instructions

Complete Payment Collection Form Layout JSON

Below is the complete form layout JSON for the Payment Collection model, including the formButtons configuration:

Click to expand the complete JSON layout

{
  "type": "form",
  "attrs": {
    "name": "form-1",
    "label": "Payment Collection",
    "className": "grid",
    "showCogWheelFormButton": false,
    "formButtons": [
      {
        "attrs": {
          "className": "p-button p-component p-button-sm",
          "icon": "pi pi-download",
          "label": "Download Sample Excel",
          "action": "GenerateTemplateFormat",
          "customComponentIsSystem": true,
          "actionInContextMenu": false,
          "openInPopup": true
        }
      }
    ]
  },
  "onFormLoad": "paymentCollectionOnFormLoadHandler",
  "children": [
    {
      "type": "sheet",
      "attrs": {
        "name": "sheet-1"
      },
      "children": [
        {
          "type": "row",
          "attrs": {
            "name": "row-1"
          },
          "children": [
            {
              "type": "column",
              "attrs": {
                "name": "group-1",
                "label": "Payment Collection Details",
                "className": "col-12"
              },
              "children": [
                {
                  "type": "field",
                  "attrs": {
                    "name": "name"
                  }
                },
                {
                  "type": "field",
                  "attrs": {
                    "name": "description"
                  }
                },
                {
                  "type": "field",
                  "attrs": {
                    "name": "dueDate"
                  }
                },
                {
                  "type": "field",
                  "attrs": {
                    "name": "institute",
                    "visible": true
                  }
                },
                {
                  "type": "field",
                  "attrs": {
                    "name": "paymentFile"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Payment Collection List View Customizations

1. Key Columns Display

The list view shows essential information for managing collections:

Column	Purpose	Sortable	Filterable
Name	Collection identifier	Yes	Yes
Due Date	When payments are due	Yes	Yes
Institute	Which institute (Super Admin view)	Yes	Yes
Created Date	When collection was created	Yes	Yes
Created By	Who created the collection	No	Yes

2. Role-Based Action Permissions

"configureViewActions": {
  "create": { "roles": ["Admin", "Institute Admin"] },
  "edit": { "roles": ["Admin", "Institute Admin"] },
  "delete": { "roles": ["Admin"] },
  "import": { "roles": [] },
  "export": { "roles": ["Admin", "Institute Admin"] },
  "customizeLayout": { "roles": ["Admin", "Institute Admin"] }
}

Benefits:

Institute Admins can create and edit collections
Only Super Admin can delete collections (data integrity)
Import disabled (use Excel upload instead)
Export enabled for reporting

Payment Collection Item List View Columns

Shows all critical information for tracking payments:

Column	Purpose	Widget/Format
Student	Who owes the fee	Link to student record
Fee Type	What fee is owed	Text
Amount To Be Paid	Base amount	Currency
Amount Paid	Paid so far	Currency (green if > 0)
Amount Pending	Still owed	Currency (red if > 0)
Late Amount	Late fee penalty	Currency (highlighted if > 0)
Total Amount	Base + Late fees	Currency (bold)
Status	Current status	Badge (colored by status)
Due Date	Payment deadline	Date (red if overdue)
Is Overdue	Past due?	Boolean icon
Overdue By Days	Days past due	Number (red if > 0)
Payment Mode	CASH or PG	Badge
Payment Collection	Which batch	Link to collection

Student List View Customizations

1. Key Columns

Column	Purpose
Student Name	Full name
Student ID	Unique identifier
Parent/Guardian Name	Primary contact
Parent/Guardian Email	Email for notifications
Parent/Guardian Mobile	Phone contact
Institute	Which institute

2. Role-Based Column Visibility

Column visibility is controlled by adding a roles key to individual field configurations in the list view layout JSON.

Example: Hiding Institute Column from Institute Admins

View: student-list-view

List View Layout Configuration:

{
  "name": "student-list-view",
  "displayName": "Students",
  "type": "list",
  "moduleUserKey": "fees-portal",
  "modelUserKey": "student",
  "layout": {
    "type": "list",
    "attrs": {
      // ... list configuration
    },
    "children": [
      {
        "type": "field",
        "attrs": {
          "name": "studentName"
        }
      },
      {
        "type": "field",
        "attrs": {
          "name": "institute",
          "roles": ["Admin"]  // ← Add roles key here
        }
      }
      // ... other fields
    ]
  }
}

Key Points:

Add the roles property inside the field's attrs object
The roles array specifies which user roles can see this column
Only users with "Admin" role will see the institute column i.e Super Admin, since Super Admin is implicitly given "Admin" role in the system
Institute Admins (without "Admin" role) will not see this column
If roles is not specified, the column is visible to all users

Benefits:

Super Admin sees institute column (multi-institute view)
Institute Admins don't see institute column (single institute context)
Cleaner, role-appropriate interface for each user type

General Design Principles

The customizations follow these principles:

Task-Oriented Workflow: Form guides users through clear steps (Download → Upload)
Progressive Disclosure: Only show fields relevant to current context
Role-Appropriate Views: Show only what each role needs to see
Error Prevention: Disable fields that shouldn't be changed after processing
Clarity: Clear labels and helper text guide users

These customizations transform the auto-generated UI into an intuitive payment collection workflow that minimizes errors and maximizes efficiency.

Applying Your Customizations

Now that you have the customized layout JSONs ready, follow the steps in Applying View Customizations to apply them via the Layout Builder.

Excel File Format and Requirements

This section provides detailed specifications for the Excel file format required for payment collection upload.

File Format Specifications

Specification	Requirement
File Type	.xlsx (Excel 2007 or later)
Maximum File Size	5 MB
Sheet Name	Any (first sheet is processed)
Header Row	Row 1 must contain column headers
Data Rows	Start from Row 2 onwards
Maximum Rows	No hard limit (practical limit based on processing time)

Required Columns

These columns must be present in your Excel file:

Column Name	Data Type	Required	Format/Validation	Example
Student Name	Text	Yes	Any text	"Rahul Sharma"
Student Id	Text	Yes	Must be unique per institute	"STU2024001"
Parent/Guardian Name	Text	Yes	Any text	"Mr. Rajesh Sharma"
Parent/Guardian Email	Email	Yes	Valid email format, lowercase	"rajesh.sharma@example.com"
Parent/Guardian Mobile	Text	Yes	10-digit number	"9123456789"

Dynamic Fee Type Columns

For each fee type configured in your institute, add TWO columns:

Pattern: {Fee Type Name} Amount and {Fee Type Name} Due Date

Example: If your institute has "Tuition Fees" and "Bus Fees" configured:

Column Name	Data Type	Required	Format	Example
Tuition Fees Amount	Number	No*	Decimal number, no commas	10000 or 10000.50
Tuition Fees Due Date	Date	No*	yyyy-mm-dd or Excel date	"2024-04-30" or Excel date
Bus Fees Amount	Number	No*	Decimal number, no commas	3000
Bus Fees Due Date	Date	No*	yyyy-mm-dd or Excel date	"2024-04-30"

Important Notes:

Fee type names must exactly match those configured in your institute's Fee Type master data
Column names are case-sensitive
If amount is 0 or empty for a fee type, no payment item will be created for that fee type
Due date is required if amount > 0

Payment Mode Column

Column Name	Data Type	Required	Format	Example
Payment Mode	Text	No (defaults to "PG")	"CASH" or "PG" (case-insensitive)	"PG"

Values:

PG (Payment Gateway): Student will receive email with payment link; status will be "Pending"
CASH: Payment already collected offline; status will be "Fully Paid"; student receives confirmation

Sample Excel Structure

Here's how a complete Excel file should look:

Student Name	Student Id	Parent/Guardian Name	Parent/Guardian Email	Parent/Guardian Mobile	Tuition Fees Amount	Tuition Fees Due Date	Bus Fees Amount	Bus Fees Due Date	Lab Fees Amount	Lab Fees Due Date	Payment Mode
Rahul Sharma	STU001	Mr. Rajesh Sharma	rajesh.sharma@example.com	9123456789	10000	2024-04-30	3000	2024-04-30	0		PG
Priya Patel	STU002	Mrs. Meena Patel	meena.patel@example.com	9876543210	10000	2024-04-30			1500	2024-05-15	PG
Amit Kumar	STU003	Mr. Suresh Kumar	suresh.kumar@example.com	9988776655	10000	2024-04-30	3000	2024-04-30	1500	2024-05-15	CASH

Analysis of Sample Data:

Row 2 (Rahul Sharma):

Will create 2 payment items: Tuition Fees (₹10,000) and Bus Fees (₹3,000)
Lab Fees has amount 0, so no item created
Both items will have status "Pending" (PG mode)
Student will receive email with payment link

Row 3 (Priya Patel):

Will create 2 payment items: Tuition Fees (₹10,000) and Lab Fees (₹1,500)
Bus Fees has no amount, so no item created
Lab Fees has different due date (2024-05-15)
Both items status "Pending"
Student will receive email with payment link

Row 4 (Amit Kumar):

Will create 3 payment items: All three fee types
All items will have status "Fully Paid" (CASH mode)
Student will receive payment confirmation email
No payment link needed
Student receives payment confirmation email

Common Validation Errors and Solutions

Error Message	Cause	Solution
"Fee type 'XYZ' is not configured"	Excel contains fee type not in institute's master data	Add fee type to institute configuration first, or remove column from Excel
"Due date cannot be in the past"	Due date is before today	Change due date to today or future date
"Invalid payment mode"	Payment Mode is not "CASH" or "PG"	Use only "CASH" or "PG" (case doesn't matter)
"Parent/Guardian Email is required"	Email column is empty	Fill in email address for all students
"Invalid email format"	Email is malformed	Check email format (must contain @)
"Student Id is required"	Student Id column is empty	Provide unique student ID for each row
"Amount must be greater than 0"	Negative or invalid amount	Enter positive numbers only

Best Practices

Data Entry:

Use the generated template: Download template from the form to ensure correct structure
Check fee type names: Copy fee type names exactly as configured in your institute
Consistent date format: Use yyyy-mm-dd format for dates (e.g., 2024-04-30)
No special formatting: Don't use currency symbols (₹, $), commas, or colors
One row per student: Each student should appear only once in the file
Complete all required fields: Don't leave required columns empty

Before Upload:

Remove extra rows/columns: Delete any template instructions or extra headers
Verify student IDs: Ensure student IDs are unique
Check due dates: Confirm all dates are today or in the future
Validate amounts: All amounts should be positive numbers
Review payment modes: Use only "CASH" or "PG"
Test with small batch: Upload 5-10 students first to verify format

After Upload:

Check processing status: Verify no error messages appear
Review created items: Check Payment Collection Items list
Verify student emails: Confirm parents received notification emails
Spot check amounts: Verify amounts match your Excel

Troubleshooting

Upload fails immediately:

Check file size (must be < 5 MB)
Verify file format (.xlsx only)
Ensure first row contains headers

Upload succeeds but no items created:

Check if amounts are > 0
Verify fee type names match exactly
Review validation error messages

Some students missing:

Check for empty required fields
Verify email format
Check Student ID for duplicates in Excel

Wrong number of items created:

Count non-zero amounts in Excel
Each non-zero amount creates one item
Zero or empty amounts are skipped

Testing Recommendation

Before uploading payment collections for all students:

Create a test Excel with 2-3 students
Use different scenarios: PG mode, CASH mode, multiple fee types
Upload and verify results
Check emails were sent correctly
Once verified, proceed with full batch

Payment Collection Workflow

This section provides a comprehensive step-by-step guide for Institute Admins to create and manage payment collections.

Prerequisites

Before initiating a payment collection, ensure:

Institute is activated (status = "Active")
Fee Types are configured for your institute
Late payment rules are set for each fee type (if applicable)
Payment gateway credentials are configured
Email templates are configured

Phase 1: Prepare Payment Collection Data

Step 1: Gather Student Information

Collect the following information for all students:

Student Name
Student ID (roll number, admission number)
Parent/Guardian Name
Parent/Guardian Email (for notifications)
Parent/Guardian Mobile Number

Step 2: Determine Fee Amounts and Due Dates

For each student and each fee type:

Calculate fee amount (based on your fee structure)
Determine due date (can be same for all or different by fee type)
Decide payment mode:
- PG: Student will pay online through portal
- CASH: Payment already collected offline

Step 3: Prepare Collection Name and Description

Choose a clear, descriptive name for this batch:

Good examples:
- "Q1 2024 Tuition and Bus Fees"
- "Annual Sports Fees 2024"
- "January 2024 Monthly Fees"
Add description (optional):
- "First quarter fees including tuition, lab, and bus charges"
- "Annual sports fees for academic year 2024-25"

Phase 2: Download and Fill Excel Template

Step 4: Login to Fees Portal

Navigate to the Fees Portal admin interface
Login using Institute Admin credentials
You will see only your institute's data

Step 5: Navigate to Payment Collections

Click on "Fees Portal" module in the sidebar
Select "Payment Collections" from the menu
Click on the "Add" button

Step 6: Download Excel Template

In the form, locate the "Download Sample Excel" section at the top
Click "Download Sample Excel" button
Save the Excel file to your computer

The template will contain:

Fixed columns: Student Name, Student Id, Parent/Guardian details
Dynamic columns: For each fee type configured in your institute
Example: If you have "Tuition Fees", "Bus Fees", "Lab Fees" configured:
- Tuition Fees Amount
- Tuition Fees Due Date
- Bus Fees Amount
- Bus Fees Due Date
- Lab Fees Amount
- Lab Fees Due Date
Last column: Payment Mode

Step 7: Fill the Excel Template

Open the downloaded template and fill in the data:

For each student (one row per student):

Enter student details:
- Student Name: Full name
- Student Id: Unique identifier (must be consistent across collections)
- Parent/Guardian Name: Primary contact person
- Parent/Guardian Email: Email where notifications will be sent (lowercase)
- Parent/Guardian Mobile: 10-digit mobile number
Enter fee amounts and due dates:
- For each fee type, enter the amount in the Fee Type Amount column
- Enter the due date in the Fee Type Due Date column (format: yyyy-mm-dd)
- If a student doesn't need to pay a particular fee type, leave the amount as 0 or empty
- Example:
```
Tuition Fees Amount: 10000
Tuition Fees Due Date: 2024-04-30
Bus Fees Amount: 3000
Bus Fees Due Date: 2024-04-30
Lab Fees Amount: 0  (or leave empty - no item will be created)
```
Enter payment mode:
- Use "PG" if student will pay online through payment gateway
- Use "CASH" if payment has already been collected offline
- Leave empty to default to "PG"

Important Notes:

Don't change column names
Don't add or remove columns
Don't use currency symbols (₹, $) or commas in amounts
Use numbers only for amounts (e.g., 10000.50)
Use yyyy-mm-dd format for dates (e.g., 2024-04-30)
Ensure all due dates are today or in the future
Each student should appear only once in the file

Step 8: Save and Validate Excel

Before uploading:

Double-check all required fields are filled
Verify student IDs are unique
Confirm due dates are not in the past
Check email addresses are valid
Verify amounts are positive numbers
Confirm payment modes are "PG" or "CASH"

Phase 3: Upload Payment Collection

Step 9: Fill Form Details

Return to the Payment Collection form in the portal:

Field	What to Enter	Example
Name	Descriptive name for this collection	"Q1 2024 Tuition and Bus Fees"
Description	Additional context (optional)	"First quarter fees for all students"
Due Date	Default due date (can be overridden in Excel)	2024-04-30
Institute	Auto-filled (Institute Admin)	Your institute

Step 10: Upload Excel File

Click "Choose File" in the "Payment File" field
Select your completed Excel file
Verify file name appears

Step 11: Submit Form

Click "Save" button
System will validate the Excel file
If validation fails, error messages will appear:
- Read error messages carefully
- Fix issues in Excel
- Upload again
If validation succeeds, form will be saved

Step 12: Wait for Processing

After successful upload:

System processes Excel file in the background
For each row in Excel:
- Student record is created or updated
- Payment Collection Items are created for each fee type
- Email notifications are queued
Processing time depends on number of students (typically 1-2 minutes for 100 students)

Phase 4: Verify Results

Step 13: Check Payment Collection Items

Navigate to "Payment Collection Items" menu
Filter by your payment collection name
Verify correct number of items created:
- Count = (Number of students) × (Number of fee types with amount > 0 per student)
- Example: 50 students, each paying 3 fee types = 150 items

Step 14: Verify Item Details

For a few sample students, check:

Student name and ID are correct
Fee type is correct
Amount to be paid matches Excel
Due date is correct
Payment mode (CASH or PG) is correct
Status is correct:
- "Fully Paid" for CASH mode
- "Pending" for PG mode

Step 15: Check Email Notifications

Verify emails were sent:

For PG mode items:

Parents should receive "New Payment Request" email
Email contains:
- Student name and details
- Total amount due
- List of fee types
- Payment link to student portal
- Due date

For CASH mode items:

Parents should receive "Payment Confirmation" email
Email contains:
- Student name and details
- Total amount paid
- List of fee types
- Payment confirmation message

Phase 5: Monitor and Manage

Step 16: Track Payment Status

Regularly check Payment Collection Items list:

Filter by "Pending" or "Partially Paid" status
Monitor overdue items (Is Overdue = true)
Check late fees being applied (Late Amount To Be Paid > 0)

Step 17: Handle Common Scenarios

Scenario 1: Student Made Partial Payment

Status will automatically change to "Partially Paid"
Amount Paid and Amount Pending will update
Student can see remaining balance in portal

Scenario 2: Payment is Overdue

Late fee calculator job runs daily
Is Overdue flag set to true
Late Amount To Be Paid calculated based on Fee Type configuration
Total Amount To Be Paid = Base Amount + Late Fee
Student sees updated amount in portal

Phase 6: Ongoing Management

Step 18: Send Payment Reminders

The system automatically sends reminder emails on a schedule (typically weekly):

Targets students with "Pending" or "Partially Paid" status
Email contains:
- Updated amount (including late fees if overdue)
- Days overdue (if applicable)
- Payment link

TODO

You can also manually trigger reminders if needed.

Step 19: Generate Reports

Use the export feature to download payment collection data:

Navigate to Payment Collection Items list
Apply filters (e.g., "Pending", "Overdue")
Click "Export" button
Download Excel file with current data
Use for analysis, reporting, or record-keeping

Step 20: Reconcile Payments

Periodically reconcile payment records:

Check Payment Collection Item Details for transaction history
Verify amounts match payment gateway records
Investigate any discrepancies
Update records if needed

Troubleshooting Reference

Issue	Possible Cause	Solution
Excel upload fails	Invalid file format, size too large, or structural issues	Check file type (.xlsx), size < 5MB, verify headers
No items created	All amounts are 0 or empty	Ensure at least one fee type has amount > 0
Wrong number of items	Zero amounts in Excel	Only non-zero amounts create items
Validation error	Fee type not configured, past due dates, invalid emails	Read error message, fix Excel, re-upload
No email sent	Invalid email address, email service issue	Verify email in Student record, check email logs
Payment link doesn't work	Student Login ID not generated	Check Student record for studentLoginId field
Status not updating	Payment gateway webhook not configured	Contact technical team to verify webhook setup
Late fees not calculated	Scheduled job not running	Contact technical team to verify job configuration

Success Criteria

You've successfully initiated a payment collection when:

Excel template downloads with your fee types
Excel validates without errors
Payment Collection is created
Correct number of Payment Collection Items created
Students appear in system with correct details
Email notifications sent to all parents
Payment links work for PG mode students
CASH mode students show "Fully Paid" status
Payment status updates when students pay online (We will cover this in the next section)

Congratulations! You've successfully initiated a payment collection. Students can now view and pay their fees through the student portal, and you can monitor payment status in real-time.

Overview​

Data Models​

How These Models Connect​

Important Concepts​

1. Student Model​

Model Configuration​

Fields​

2. Payment Collection Model​

Model Configuration​

Fields​

3. Payment Collection Item Model​

Model Configuration​

Fields​

4. Payment Collection Item Detail Model​

Model Configuration​

Fields​

5. Adding Relation Fields​

Generating APIs and UI Components​

Creating Roles & Permissions​

Institute Admin​

Implementing Custom Business Logic​

1. Excel Upload Validation​

2. Excel Template Generation​

3. File Processing with TypeORM Event Subscriber​

4. Student Management Logic​

5. Payment Collection Item Creation​

6. Email Notification Logic​

7. Computed Field for Amount Calculations​

8. Scheduled Jobs​

Customizing the UI​

Payment Collection Form View Customizations​

Complete Payment Collection Form Layout JSON​

Payment Collection List View Customizations​

Payment Collection Item List View Columns​

Student List View Customizations​

General Design Principles​

Excel File Format and Requirements​

File Format Specifications​

Required Columns​

Dynamic Fee Type Columns​

Payment Mode Column​

Sample Excel Structure​

Common Validation Errors and Solutions​

Best Practices​

Troubleshooting​

Payment Collection Workflow​

Prerequisites​

Phase 1: Prepare Payment Collection Data​

Phase 2: Download and Fill Excel Template​

Phase 3: Upload Payment Collection​

Phase 4: Verify Results​

Phase 5: Monitor and Manage​

Phase 6: Ongoing Management​

TODO​

Troubleshooting Reference​

Success Criteria​

Overview

Data Models

How These Models Connect

Important Concepts

1. Student Model

Model Configuration

Fields

2. Payment Collection Model

Model Configuration

Fields

3. Payment Collection Item Model

Model Configuration

Fields

4. Payment Collection Item Detail Model

Model Configuration

Fields

5. Adding Relation Fields

Generating APIs and UI Components

Creating Roles & Permissions

Institute Admin

Implementing Custom Business Logic

1. Excel Upload Validation

2. Excel Template Generation

3. File Processing with TypeORM Event Subscriber

4. Student Management Logic

5. Payment Collection Item Creation

6. Email Notification Logic

7. Computed Field for Amount Calculations

8. Scheduled Jobs

Customizing the UI

Payment Collection Form View Customizations

Complete Payment Collection Form Layout JSON

Payment Collection List View Customizations

Payment Collection Item List View Columns

Student List View Customizations

General Design Principles

Excel File Format and Requirements

File Format Specifications

Required Columns

Dynamic Fee Type Columns

Payment Mode Column

Sample Excel Structure

Common Validation Errors and Solutions

Best Practices

Troubleshooting

Payment Collection Workflow

Prerequisites

Phase 1: Prepare Payment Collection Data

Phase 2: Download and Fill Excel Template

Phase 3: Upload Payment Collection

Phase 4: Verify Results

Phase 5: Monitor and Manage

Phase 6: Ongoing Management

TODO

Troubleshooting Reference

Success Criteria