# TELSPAY Education System Upgrade v2026.9.5.1

Build date: 2026-09-08
Upgrade basis: TELSPAY Education v2026.9.5 plus the Student Login Access security module.
Target: cPanel / MariaDB / PHP 7.4-compatible application style. Education additions do not require Composer.

## Release scope

v2026.9.5 expands TELSPAY Education into a controlled Education Finance and Student Wallet platform while retaining the staged school onboarding, Free Starter subscription, School Portal, Member Education module, QR document verification, non-blocking Email/SMS outbox and Africa's Talking integration from v2026.9.4.

Major additions include:

- Education Control Center demographics and local Chart.js analysis.
- Full school profile, KYB/document/media review, correction requests and document control.
- School Portal user/role/status management by SACCO Admin.
- Paid School Growth AI marketing entitlement with private provider configuration.
- Member Education Invest account and school-fees payment flow.
- Public student-payment-number school-fees checkout.
- Configurable SACCO school-fee commission.
- Configurable school-fees-loan eligibility using Savings, Shares and Education Invest balances. Shares are eligibility-only and are never a school-fees payment source.
- QR-verifiable, dependency-free School Fees PDF receipts.
- Subscription collection through Flutterwave Mobile Money/Card, Bank Transfer or Cash evidence.
- SACCO manual subscription grant/upgrade/downgrade/extend/suspend/revoke/reactivate controls.
- Student Wallet Portal linked to an approved school/student.
- Same-school student wallet transfers, education-store purchases, wallet top-ups and controlled Mobile Money withdrawals.
- SACCO-controlled student loan products, school review, SACCO approval, wallet disbursement and wallet repayment.
- Global Education transaction-reference search.
- Uganda district/city selectors.

### Student Login Access v2026.9.5.1

- SACCO Admin can search Student Wallet accounts and resend Student Portal login access by Email, SMS, or both.
- TELSPAY sends the wallet/login number and a single-use password setup/reset link; it never sends the existing password or 4-digit transaction PIN.
- New links revoke older unused links for the same wallet.
- Reset links expire after a configurable period (30 minutes by default) and are protected by the private Education token pepper.
- Resend requests are rate-limited (5 minutes by default), permission-controlled and recorded in Education/Student Wallet security audit trails.
- The notification worker cancels/redacts expired or revoked Student Login messages and redacts the one-time URL from the outbox after successful delivery.
- Students set their own replacement password from `student.telspay.com/reset_password.php`.

## Required deployment roots

Deploy the corresponding project folders to these canonical production hosts unless your private `local.php` deliberately overrides them:

- Public Education: `https://education.telspay.com`
- School Portal: `https://school.telspay.com`
- Student Portal: `https://student.telspay.com`
- Member App: `https://invest.telspay.com`
- SACCO Admin: `https://nfasacco.telspay.com/updatings/views`
- Private services: `/home/CPANEL_USER/telspay_secure/education/`

Do not place `local.php`, database passwords, Flutterwave secrets, SMTP passwords, Africa's Talking API keys, AI API keys, encryption keys, KYB evidence or private student content under a public web root.

## Database migration order

Back up the production database before importing any migration. For a new Education installation, import the Education migrations in version order already supplied by the full release, ending with:

1. `database/TELSPAY_EDUCATION_FINANCE_AI_V2026_9_5.sql`
2. `database/TELSPAY_EDUCATION_STUDENT_LOGIN_ACCESS_V2026_9_5_1.sql`

For an existing correctly migrated **v2026.9.5** installation, import only:

`database/TELSPAY_EDUCATION_STUDENT_LOGIN_ACCESS_V2026_9_5_1.sql`

The v2026.9.5.1 migration is additive. It creates the single-use Student Login Access token registry and the dedicated Admin permission; it does not replace Student Wallet balances, passwords, transaction PINs, loans, member savings, shares or transaction history.

## Private configuration

Copy:

`telspay_secure/education/local.example.php`

to:

`/home/CPANEL_USER/telspay_secure/education/local.php`

and configure the production values there. Do not overwrite an existing production `local.php` during an upgrade.

Configure at minimum:

- database connection;
- document HMAC/encryption/token secrets;
- canonical URLs;
- Flutterwave private config path;
- SMTP / PHPMailer settings if email is enabled;
- Africa's Talking username/API key and delivery token if SMS is enabled;
- School Growth AI API configuration if the paid AI feature is enabled;
- SACCO notification email/phone;
- private document, subscription-evidence and student-content storage directories.
- Student Login Access policy values if you want to override the secure defaults:
  - `student_login_reset_minutes` (default 30);
  - `student_login_resend_cooldown_seconds` (default 300).

The private `token_pepper` must contain a strong independent random secret (at least 32 characters) before Student Login Access links can be issued.

The v2026.9.5 School Fees PDF receipt renderer is dependency-free and does not require Dompdf, Composer, `mbstring`, GD or Imagick. `dompdf_autoload_path` remains only for backward compatibility with older Education document paths.

## School onboarding and document control

School onboarding remains staged:

1. Public school registration creates `ACCOUNT_PENDING / INACTIVE`.
2. SACCO Admin approves the account or rejects it.
3. The school administrator completes school profile/KYB information.
4. Required evidence is stored privately and reviewed by SACCO Admin.
5. A rejected/revoked required document keeps KYB incomplete.
6. Final activation requires the configured required evidence and verified settlement account.
7. If no paid subscription is already active, the perpetual Free Starter package can be granted.

SACCO Admin can request corrections, review school media/documents, lock/suspend portal users, change school roles and audit school state changes.

## Subscription collection and manual controls

School subscription methods:

- Flutterwave hosted checkout: Mobile Money and/or Card.
- Bank Transfer: external reference plus private uploaded evidence required.
- Cash: external/reference evidence required.

Bank/Cash evidence remains `PENDING_MANUAL_APPROVAL` and must not activate access by itself. An authorized SACCO Admin reviews the evidence and can approve, reject or revoke it. Manual package grant/upgrade/downgrade/extend/suspend/revoke/reactivate actions require an Admin reason and are written to the subscription audit records. Maker/checker restrictions are retained where the workflow requires independent approval.

## Member Education Invest and School Fees

The Education Invest account is a separate Education ledger.

Allowed school-fee payment sources:

- Member SACCO Savings;
- Member Education Invest;
- verified Mobile Money.

**Shares must never be debited for school fees.** Shares may only contribute to configured school-fees-loan eligibility.

Savings -> Education Invest transfers require the existing member transaction PIN controls. Education Invest Mobile Money top-up is intended for the Member App flow and must be provider-verified before value is posted.

A student school-fees payment number identifies the exact registered school/student context. When the student is linked to the authenticated member, Savings/Invest payment is allowed subject to policy and balance checks. Otherwise public payment is restricted to verified Mobile Money.

Successful school-fee transactions issue a QR-verifiable PDF receipt and preserve records against the school, student and member/payer context. Email/SMS notifications use the non-blocking notification outbox.

## Student Wallet Portal

Student Wallet is a separate ledger tied to one student and one school. It is not Member Savings, Shares or Education Invest.

Security/business rules include:

- four-digit transaction PIN;
- PIN attempt lockout;
- wallet lifecycle states controlled by SACCO Admin;
- same-school-only student-to-student transfers;
- no overdraft;
- provider-verified wallet top-ups;
- controlled Notes / Study Tours / Requirements purchases;
- Mobile Money withdrawal request with SACCO-configurable charge;
- SACCO approval and provider reconciliation before a withdrawal is final;
- student loans disabled by default until SACCO Admin enables/configures the facility;
- SACCO-created student loan products;
- optional school review and required SACCO credit decision;
- approved loan proceeds enter the Student Wallet only;
- loan repayments debit the Student Wallet and cannot exceed the outstanding balance;
- student loan/repayment visibility is restricted to SACCO and the associated school administration.

## School Growth AI

School Growth AI is a paid subscription entitlement. Provider credentials remain private. The Education service is constrained to school-marketing assistance and should not invent Ministry/UNEB approval, accreditation, rankings, results, fees, scholarships, facilities or other factual claims. Generated copy must be reviewed by an authorized school user before publication.

## Notifications

Education business transactions commit independently from provider delivery. Email/SMS events are queued to the outbox and an opportunistic dispatch may be attempted after a successful change. SMTP/Africa's Talking failure must not roll back a school, payment, wallet, loan or subscription transaction.

Run the notification worker from cPanel cron using the PHP binary assigned to the application. Also retain the subscription maintenance cron from the prior release.

## Production verification after upload

Offline validation cannot certify live provider credentials or server configuration. Before production cutover, test on the actual cPanel/staging environment:

1. Import the v2026.9.5 migration and verify all tables/columns/permissions.
2. Run `php -l` with the exact cPanel PHP 7.4 binary on changed/new Education files.
3. Create/approve a school and complete KYB/document correction workflow.
4. Test Free Starter and a paid subscription.
5. Complete one Flutterwave subscription transaction.
6. Upload Bank Transfer/Cash evidence and verify SACCO approve/reject/revoke behavior.
7. Test SMTP and Africa's Talking delivery/outbox retries.
8. Configure/test the AI provider only if the paid AI package is enabled.
9. Create a member Education Invest account; test Savings transfer and verified Mobile Money top-up.
10. Complete a Savings/Invest school-fee payment and public Mobile Money school-fee payment.
11. Verify the generated School Fees PDF/QR receipt.
12. Create/activate a Student Wallet; test top-up, same-school transfer and store purchase.
13. Test withdrawal approval/provider reconciliation using controlled test credentials.
14. Create a Student Loan product; test school review, SACCO approval, wallet disbursement and repayment.
15. Test suspension/locking/ban states and transaction-PIN lockout.
16. Verify private evidence/content URLs cannot be fetched directly.
17. Verify Admin global transaction search, charts, pagination and role/status modals.
18. Confirm PHP-FPM/OPcache is refreshed after replacing PHP files.

Do not treat a provider callback parameter alone as proof of payment. Value is granted only after server-side verification or an explicitly authorized manual evidence workflow.