GOVERNMENT

GOVERNMENT SERVICES

The Government Services module is Leaseora's role-based, multi-tenant infrastructure for public housing, government estates, land administration, citizen applications, allocation, government revenue and tax compliance. It is designed around specialised agency workflows rather than the ordinary private-landlord property-management process.

Leaseora Jul 30, 2026 54 min read 18 views

LEASEORA

GOVERNMENT SERVICES

End-to-End User and Technical Operations Guide

Agencies • Programs • Estates • Units • Eligibility • Applications • Allocation • Offer Letters • Invoices • Remita/TSA • Wallet • Handover • Title Cases • Tax Office • Analytics

For government housing agencies, ministries, land administration bodies, public estate teams, finance and revenue teams, tax officials, citizen-support teams and authorised real estate delivery partners

Version 1.0 | July 2026

Purpose of this guide

This guide explains how to configure and operate Leaseora Government Services from agency creation through program publication, estate and unit setup, citizen eligibility, application review, scoring, allocation, offer acceptance, payment plans, invoice collection, revenue reconciliation, title cases, asset management, tax-office oversight and mobile access. It also provides a technical reference for the supplied routes, models, controllers, services, middleware, payment flows, emails and AI-assisted functions.

1 Purpose, Scope and Terminology

Item	Description
Primary audience	Government Admins and Officials, housing-program teams, estate and unit officers, verification teams, allocation committees, finance/TSA teams, land-title officers, tax officials and Super Admins.
Citizen audience	Any authenticated and fully verified Leaseora user who browses public programs, checks eligibility, applies, accepts or declines an offer, pays invoices and follows allocation status.
Real estate company use	Real estate companies may use this guide when operating as authorised delivery partners or support teams within an agency-governed workflow. Access remains subject to the Government role and agency permissions.
Core scope	Agency setup; bank and gateway configuration; programs; estates; units; applications; verification; scoring; allocation; offer letters; invoices; payments; receipts; handover; title cases; assets; revenue; tax office and mobile access.
Technical scope	Middleware, models, controllers, allocation engine, NigeriaGovernmentAdapter, payment services, webhooks, email classes and mobile endpoints supplied in the scenario.
Terminology	This guide uses Citizen for the applicant or beneficiary. Backend class names use GovProgram, GovApplication, GovAllocation and other supplied technical names.

Important module boundary

Government Services uses dedicated GovAgency, GovProgram, GovEstate, GovUnit, GovApplication, GovAllocation, GovInvoice and GovReceipt records. Do not substitute the ordinary Properties, Listings or Lease workflow where a government program requires statutory eligibility, allocation, TSA reconciliation or title administration.

What one connected public-housing record should contain

· Agency - the ministry, authority, department, commission or government body responsible for the program.

· Program - the public housing, mortgage, rent-to-own, allocation or land initiative.

· Estate and Unit - the physical housing stock offered through the program.

· Citizen Application - identity, NIN, eligibility data, documents and verification history.

· Score and Allocation - the criteria result, allocation method, matched unit and offer history.

· Invoice, Payment and Receipt - the amount due, payment method, settlement evidence and government receipt.

· Handover and Title - possession, handover documents, title case and land-administration evidence.

· Audit and Analytics - status history, actor, date, revenue, reconciliation, risk and performance.

2 Roles and Responsibilities

Role	Main responsibilities	Key controls
Super Admin / Admin	Create and activate agencies; monitor all government records; manage agency payouts and global exceptions.	Cannot replace statutory agency approval. High-risk overrides require evidence and audit.
Government Admin / Official	Configure agency, programs, estates, units, applications, allocations, revenue and support.	government_isolation restricts access to the user's agency.
Program Officer	Create program terms, application windows, fees and requirements.	Uses approved program policy and dates; AI auto-fill requires human review.
Verification Officer	Review NIN, documents and application evidence.	Must record verification result and notes; cannot silently alter citizen data.
Allocation Committee / Officer	Score, batch-process or manually allocate available units.	Method, score, unit lock and decision history must be preserved.
Estate / Unit Officer	Maintain estate status, unit inventory, publication, reservation and work orders.	One physical unit must have one unique unit record and controlled status.
Finance / Revenue Officer	Issue invoices, verify payments, reconcile Remita/TSA, manage agency wallet and reports.	Browser callback or uploaded proof is not settlement until verified.
Land / Title Officer	Process title cases, encumbrances, legal search and certificate issuance.	Uses applicable FCTA rules and retains evidence.
Tax Office User	Review landlord tax records, compliance, flags, reconciliation and AI analytics.	Access is limited to authorised tax functions and protected taxpayer data.
Citizen / Applicant	Browse, check eligibility, apply, upload documents, accept/decline, pay and track status.	Must provide accurate identity and use approved payment channels.
Citizen Support Officer	Respond to government inquiries and explain status.	Cannot approve applications, allocations, payments or title outcomes.

3 Complete Module Journey

Figure 1. Government Services end-to-end journey

Phase	Business outcome	Main records / systems
1. Agency setup	A government body is created, activated and isolated from other agencies.	GovAgency, GovAuthController, government_isolation.
2. Portal configuration	Agency profile, bank accounts and payment gateways are configured.	GovSettings, GovAgencyBankAccount, GovAgencyPaymentGateway.
3. Program and stock	Programs, estates and units are published with dates, fees and terms.	GovProgram, GovEstate, GovUnit.
4. Citizen discovery	Citizens browse country-scoped programs, estates and available units.	CitizenPortalController, CurrencyExchangeService.
5. Application	Citizen checks eligibility, submits NIN/data/documents and receives confirmation.	GovApplication, NigeriaGovernmentAdapter, mail.
6. Review and scoring	Agency verifies documents, applies AI/government criteria and decides.	AllocationEngine, AIEligibilityScoring.
7. Allocation and offer	Available units are allocated by merit, FIFO, ballot or manual method.	GovAllocation, row locking, offer emails.
8. Payment and handover	Citizen pays invoice/deposit/installments and completes handover.	GovInvoice, GovReceipt, GovRevenueController.
9. Revenue and compliance	Agency reconciles TSA, manages wallet/payouts; Tax Office monitors compliance.	GovReconciliation, GovAgencyWallet, Tax Office.

4 Access Control, Route Tiers and Data Isolation

User tier	Route prefix	Middleware / access rule
Government Admin / Official	/government/admin/...	auth, government, government_isolation.
Citizen	/government/citizen/...	auth, profile.complete, fully_verified.
Super Admin Government	/superadmin/...	auth, role:Super Admin\|Admin.
Tax Office User	/government/tax-office/...	auth plus tax-office authorisation in the live build.
Public or unauthenticated browser	/government, /government/programs, /government/estates, /government/units	The supplied description says public browsing is available, while one route note states auth. Confirm the live middleware before publishing public instructions.
Mobile citizen	/api/mobile/government/...	Public browse endpoints and Sanctum-authenticated citizen endpoints as supplied.

Agency isolation is non-negotiable

Every agency-admin query should be scoped to the authenticated agency. A Government Admin must not be able to view or change another agency's programs, applications, allocations, invoices, receipts, bank accounts or citizen documents.

Access validation checklist

☐ Government role is present and agency account is active.

☐ Authenticated user belongs to the correct GovAgency.

☐ Government isolation is applied to list, show, update, export and AJAX endpoints.

☐ Citizen profile is complete and fully verified before protected actions.

☐ Super Admin actions are separated from agency decisions.

☐ Tax Office permissions are limited to tax/compliance responsibilities.

☐ Mobile APIs enforce the same ownership and country scoping as web routes.

5 Implementation Prerequisites and Agency Onboarding

Business and policy information to prepare

☐ Legal agency name, code, type, jurisdiction and parent agency where applicable.

☐ Country/currency, contact details, website and official address.

☐ Approved government program policy, application dates and fees.

☐ Agency-specific eligibility and statutory identity requirements.

☐ Estate register, unit inventory, price, publication and status reconciliation.

☐ Allocation method policy: merit, FIFO, ballot, manual, priority or special.

☐ Offer validity, deposit, interest, installment, grace and late-payment terms.

☐ Remita/TSA and other gateway credentials, callback URLs and bank accounts.

☐ Invoice numbering, receipt, waiver, refund and reconciliation rules.

☐ Title-case fees, processing timelines, encumbrance categories and signatories.

☐ Staff list, departments, roles, approval thresholds and escalation paths.

☐ Data retention, citizen consent, document protection and audit requirements.

Recommended implementation sequence

1. Create and activate a pilot agency in a non-production environment.

2. Configure country, currency, bank account and test payment gateways.

3. Create one pilot program with a small estate and controlled unit inventory.

4. Run a citizen eligibility and application test with non-production identities.

5. Verify documents, score the application and test all allocation methods.

6. Issue an offer, accept it, generate a deposit and installment plan.

7. Test wallet, gateway and bank-transfer payment scenarios.

8. Reconcile test receipts against gateway/TSA records.

9. Complete handover, revoke/decline/expire test cases and unit release.

10. Test title case, inquiry chat, Tax Office and mobile endpoints.

11. Review audit logs, permissions, exports and exception handling before go-live.

Use individual accounts

Every officer should use an individual account. Shared credentials weaken audit history and make it difficult to identify who verified an application, changed a score, allocated a unit, waived an invoice or issued a certificate.

6 Phase 1 - Create and Activate a Government Agency

STEP
1

Create an Agency from Super Admin

Primary user: Super Admin / Admin

Use SuperAdminGovAgencyController@store to create the official agency record before programs or estates are published.

Field	Purpose	Control / example
name	Full official name.	Federal Housing Authority.
code	Unique short code used in references.	FHA, FMBN, FCTA or FMHUD.
type	Government-body classification.	ministry, department, authority, commission or agency.
parent_id	Optional parent body.	Use for a sub-agency or department.
country_code	Country scoping.	NG or another approved ISO code.
jurisdiction	State, region or legal authority.	FCT, Federal, Lagos State, etc.
contact_email / phone	Official communication.	Use monitored government contacts.
address / website	Public agency information.	Verify before publication.
is_active	Controls operational access.	Keep inactive until approval and configuration pass.
metadata	Additional structured agency data.	Store only approved, documented keys.

The Super Admin dashboard can show total, active, pending and deleted agency counts. A soft-delete should be blocked where active programs exist, according to the supplied oversight rules.

STEP
2

Use Public Agency Self-Registration

Primary user: Government Organisation Applicant

GovAgencyRegistrationController@showRegisterForm and @register allow an agency to submit its own registration. The record remains inactive until approved.

· Use an official organisation email and verifiable contact details.

· Enter the exact legal agency identity and jurisdiction.

· Do not publish programs while the agency is inactive.

· Super Admin verifies and activates the agency before Government Admin access is treated as live.

Activation control

Agency registration is not the same as approval. The platform should prevent an inactive or unverified agency from publishing public programs, collecting money or accessing other agencies' data.

7 Phase 2 - Configure the Government Portal

STEP
3

Log in to the Government Portal

Primary user: Government Admin / Official

Use GovAuthController@create and @store. Successful Government-role verification redirects the user to /government/admin/dashboard.

☐ Confirm agency name and code shown on the dashboard.

☐ Confirm jurisdiction, country and operating currency.

☐ Review system alerts and incomplete setup warnings.

☐ Do not continue if the dashboard shows another agency's records.

STEP
4

Configure Agency Settings

Primary user: Government Admin

Open /government/admin/settings and maintain agency profile, notification preferences and system settings through GovSettingsController@index and @update.

Setting area	Recommended content	Business control
Agency profile	Name, code, contacts, address, website, jurisdiction.	Changes to legal identity require authorised approval.
Country and currency	Agency country and operating currency.	Controls visibility, display and payment processing.
Notifications	Application, allocation, invoice, reconciliation and inquiry alerts.	Use monitored recipients and escalation groups.
System settings	Application, allocation, handover and document defaults.	Document every non-default value.

STEP
5

Add and Maintain Agency Bank Accounts

Primary user: Finance / Revenue Officer

Use GovAgencyBankAccountController to add accounts, set one primary and toggle active status.

Action	Route / result	Control
Add account	POST /settings/bank-accounts.	Use account owned or authorised by the agency.
Set primary	POST /settings/bank-accounts/{id}/set-primary.	Only one intended primary receiving/payout account.
Toggle active	POST /settings/bank-accounts/{id}/toggle-active.	Deactivate obsolete or compromised accounts immediately.

STEP
6

Configure Payment Gateways

Primary user: Finance / System Administrator

Use GovAgencyPaymentGatewayController to configure, enable, disable and test gateway status. Remita/TSA is the primary Nigerian government path in the supplied design; Paystack is secondary, with Stripe and Flutterwave also supported in citizen payment flows.

Action	Route	Required validation
Configure	POST /settings/payment-gateways/{gateway}/configure.	Credentials encrypted; correct environment and callback URLs.
Enable	POST /settings/payment-gateways/{gatewayConfig}/enable.	Only after a successful test.
Disable	POST /settings/payment-gateways/{gatewayConfig}/disable.	Stop new transactions without deleting history.
Check status	GET /settings/payment-gateways/{gateway}/status.	Confirm API connectivity, credentials and environment.

Never expose credentials

Gateway API keys, Remita/TSA credentials and signing secrets must not appear in screenshots, exports, logs, support messages or client-side code.

8 Phase 3 - Create and Manage Government Programs

STEP
7

Create a Housing, Mortgage or Land Program

Primary user: Program Officer

Open /government/admin/programs/create and save through GovProgramController@store.

Program field	Purpose	Operational control
name / code	Program identity and unique reference.	Use approved public name and stable code.
type	housing, mortgage, rent_to_own, allocation or land.	Select the workflow that matches policy.
agency_id	Owning agency.	Must be the authenticated agency.
description	Public explanation, benefits and process.	Use plain language and verified claims.
application_fee	Application processing fee.	Confirm legal authority and currency.
start / end date	Application window.	End must follow start; test timezone.
is_accepting_applications	Controls submission availability.	Close immediately when policy requires.
is_featured	Homepage visibility.	Use only for approved campaigns.
country_code	Country scoping.	Match agency jurisdiction.
metadata	Currency, payment plan, deposit, installments, frequency, interest, penalty, discount and grace days.	Treat metadata as binding configuration; review with finance/legal teams.

STEP
8

Use AI Auto-Fill and Program Lifecycle Actions

Primary user: Program Officer / Approver

POST /government/admin/programs/ai-autofill is throttled to five requests per minute and can draft program details from a name or description. Staff must review the output before saving or publishing.

Action	Route / behaviour
Activate	POST /programs/{program}/activate - makes the program operational according to status rules.
Deactivate	POST /programs/{program}/deactivate - removes it from active use without deleting history.
Close	POST /programs/{program}/close - stops new applications.
Upload images	POST /programs/{program}/images - add authorised program media.
Statistics	GET /programs/{program}/statistics - view program performance.
Eligibility preview	POST /programs/{program}/check-eligibility - test criteria before public launch.

AI does not create policy

AI auto-fill may draft a description or suggested values. It must not invent eligibility law, fees, interest rates, allocation priority or statutory identity requirements. Authorised officials remain responsible for the published program.

9 Phase 4 - Create Estates and Units

Figure 2. Core government record relationships

STEP
9

Create and Maintain an Estate

Primary user: Estate / Asset Officer

Use GovEstateController@store to create the estate and link it to the correct agency and program.

Estate field	Purpose	Good practice
name	Public estate or scheme name.	Use the approved project identity.
address / city / state	Physical location.	Validate jurisdiction and spelling.
country_code	Country visibility and currency context.	Match agency/program scope.
agency_id / program_id	Ownership and program link.	Do not cross-link another agency.
status	planning, active, operational, completed or decommissioned.	Update only through approved lifecycle.
latitude / longitude	Map position.	Use verified coordinates.
total_units	Planned inventory.	Reconcile to actual unit records.

· Update estate status through POST /estates/{estate}/status.

· Bulk-create units through POST /estates/{estate}/units/bulk.

· Upload authorised images through POST /estates/{estate}/images.

· Create work orders through POST /estates/{estate}/work-orders.

· Use GET /estates/{estate}/statistics for stock and activity review.

STEP
10

Create, Publish and Control Units

Primary user: Estate / Unit Officer

Use GovUnitController@store for each apartment, house, bungalow, duplex or flat.

Unit field	Purpose	Control
unit_number	Unique identifier within the estate.	Prevent duplicates.
unit_type	apartment, house, bungalow, duplex or flat.	Use the configured taxonomy.
bedrooms / bathrooms	Layout.	Use verified specifications.
floor_area_sqm	Approved floor area.	Use measured square metres.
price	Program price.	Match approved schedule and currency.
status	available, reserved, allocated or occupied.	Status determines allocation availability.
is_published	Citizen-visible toggle.	Publish only complete, available records.

Unit action	Result
Publish / Unpublish	Controls citizen visibility.
Reserve / Release	Temporarily blocks or returns a unit to availability.
Duplicate	Copies a similar unit; unique values must be replaced.
Bulk Publish	Publishes selected verified units.
Create Work Order	Links operational maintenance to the unit.

One physical unit, one record

Duplicate unit numbers or stale statuses can cause double allocation and payment disputes. Reconcile the physical inventory before every allocation batch.

10 Phase 5 - Citizen Discovers Programs, Estates and Units

STEP
11

Open the Government Portal Landing Page

Primary user: Citizen / Applicant

CitizenPortalController@index resolves the user country code, normalises ISO-2/ISO-3 values, loads country-scoped featured programs and estates, counts available units and shows the citizen's application statistics.

Portal card / statistic	Meaning
Active Programs	Country-scoped government programs currently available.
Total Estates	Government estates visible in the user's country.
Available Units	Published units with status = available.
My Applications	Applications created by the authenticated citizen.
Converted application fee	CurrencyExchangeService displays the fee in the citizen's currency where conversion is available.

STEP
12

Browse Programs and Understand Agency Requirements

Primary user: Citizen / Applicant

Use /government/programs with agency, program type, accepting-applications and free-text filters. Results are paginated at 12 per page.

Agency	Injected requirement summary
FMBN	NHF contribution 2.5%; LTV 90%; supplied rates: NHF 6%, Non-NHF 9%, Rent-to-Own 6.5%; tenure 5-30 years; income requirements.
FHA	Age 21-55; BVN required; scoring weights: income 25%, employment 20%, family 15%, housing 15%, NHF years 15%, credit 10%.
FCTA	Title types C-of-O, R-of-O and Deed of Assignment; ground-rent schedules; encumbrance checks.
FMHUD	Age 18-60; NIN required; minimum income NGN 30,000 per month; priority categories.

STEP
13

Browse Estates and Available Units

Primary user: Citizen / Applicant

Use /government/estates and /government/units. Estate filters include agency, state, city and search. Unit filters include estate, type, bedrooms and price range. Only available, published units are shown.

Converted price is informational

The official program or unit currency remains the contractual currency unless the agency formally fixes a converted amount. Exchange rates can change between browsing and payment.

11 Phase 6 - Check Eligibility Before Applying

STEP
14

Run the Citizen Eligibility Check

Primary user: Citizen / Applicant

POST /government/citizen/check-eligibility submits program, income, employment, family, housing, NHF and credit information to GovApplicationController@checkEligibility.

Criterion	Maximum	Supplied scoring logic
Income stability	25	At least NGN 200k = 25; 100k = 20; 50k = 15; otherwise 10.
Employment type	20	Federal civil servant = 20; State = 18; Private = 15; Self-employed = 12.
Family size	15	At least 5 = 15; at least 3 = 12; otherwise 8.
Housing status	15	Homeless = 15; Renting = 12; Living with family = 10.
NHF contribution years	15	At least 10 = 15; at least 5 = 12; at least 2 = 8.
Credit history	10	At least 700 = 10; at least 600 = 8; at least 500 = 5.

The supplied maximum is 100 and the stated minimum threshold to apply is 50. The response contains eligible, score, max_score, agency-specific requirements and recommendations.

Eligibility check is not allocation

A passing preview does not guarantee application approval, unit availability, allocation, financing or title. The citizen must still submit a complete application and pass agency review.

Human and legal review

Income, employment, family and housing criteria may be regulated and sensitive. The agency must confirm lawful use, transparency, appeals and non-discrimination requirements before production.

12 Phase 7 - Citizen Submits an Application

STEP
15

Open the Citizen Dashboard and Application Form

Primary user: Citizen / Applicant

The dashboard shows recent applications, allocations, pending offers and totals. The create action loads the chosen program, active units and agency-specific document requirements, and blocks a duplicate active application for the same program.

☐ Confirm the correct program and optional preferred unit.

☐ Read the official eligibility and document requirements.

☐ Confirm the application window is open.

☐ Check whether an existing active application already exists.

☐ Prepare clear, current documents before starting.

STEP
16

Submit the Government Application

Primary user: Citizen / Applicant

POST /government/citizen/applications saves the application within a database transaction and stores uploaded files under government/applications/{Y/m}/.

Required input	Rule / purpose
program_id	Required; identifies the government program.
applicant_nin	Required; exactly 11 digits in the supplied Nigerian flow.
applicant_phone	Required contact number.
monthly_income	Required numeric value in application_data.
employment_type	Required eligibility field.
family_size	Required integer.
current_housing_status	Required eligibility field.
documents	Optional file array in the supplied validation; agency-specific requirements may make particular files operationally mandatory.

Generated field	Example / meaning
application_number	{AGENCY_CODE}-{YEAR}-{NNNNNN}, for example FHA-2026-000001.
status	submitted on initial save.
application_data	JSON containing the citizen's eligibility form values.
documents	JSON array of uploaded paths.
submission_date	Exact submission timestamp.

GovApplicationSubmittedMail confirms submission. NigeriaGovernmentAdapter::validateApplication then checks NIN format, agency age range, income minimum for mortgage/rent-to-own and NHF number for FMBN. Validation errors move the application to incomplete and are recorded in verification_notes.

Document upload control

Government applications can contain identity, income and financial records. Restrict file types and size, scan uploads, encrypt storage where supported, and never place direct storage paths in public responses.

13 Phase 8 - Verify, Review and Score Applications

Figure 3. Application review and allocation status flow

STEP
17

Review and Filter Applications

Primary user: Verification / Program Officer

GET /government/admin/applications lists agency-scoped applications. Filter by program, status, date range or application number/applicant name/email. Results are paginated at 20 per page.

STEP
18

Verify Documents and Update Status

Primary user: Verification Officer

POST /government/admin/applications/{application}/verify records verification_status, verification_notes and verified_documents. Verified applications move to under_review; failed verification moves to incomplete.

Status	Operational meaning
submitted	Application received and awaiting agency action.
under_verification	Identity and documents are being checked.
under_review	Verification passed and substantive review is underway.
scored	Eligibility score calculated and ready for allocation.
approved	Approved according to the supplied status workflow; an application-fee invoice is generated.
rejected	Not approved; reason should be recorded.
waitlisted	Eligible but not immediately allocated.
allocated	A GovAllocation has been created.
withdrawn	Citizen withdrew the application.
incomplete	Nigerian validation or document verification failed.

GovApplicationStatusMail notifies the citizen whenever the status changes and receives the previous status for context.

STEP
19

Score One Application or a Batch

Primary user: Allocation / Verification Team

POST /applications/{application}/score calls AllocationEngine@calculateScore. POST /applications/batch-score scores all submitted and under_review applications for a program.

Scoring layer	Supplied contribution
AI base score	AIEligibilityScoring::calculateAdvancedScore - maximum 1,000 points.
Civil servant bonus	+100.
First-time owner bonus	+50.
NHF contributor bonus	+50.
Nigeria criteria score	NigeriaGovernmentAdapter::calculateEligibilityScore - maximum 100.
Stored output	application.eligibility_score; status becomes scored.

Confirm the scoring formula

The supplied scenario combines an AI base score of up to 1,000, bonuses and a separate 100-point Nigerian score, but does not define the final normalisation formula. Confirm the live implementation and publish an understandable scoring policy before allocation.

14 Phase 9 - Allocate Units

STEP
20

Run Automated Allocation

Primary user: Allocation Committee / Government Admin

POST /government/admin/allocations/process sends program_id, method and optional batch_size to GovAllocationController@processAllocations and AllocationEngine@processAllocations.

Method	Ordering rule	Use case / control
merit	eligibility_score descending.	Use where published policy allocates highest scores first.
fifo	submission_date ascending.	Use where complete applications are handled first-in, first-out.
ballot	random order.	Use only with approved, transparent ballot governance.

1. Count available units for the selected program.

2. Load applications with status = scored.

3. Order by the selected allocation method.

4. Limit candidates to the available-unit count or approved batch size.

5. For each candidate, open a database transaction and lock an available unit row.

6. Create GovAllocation with offer_issued status and 30-day expiry.

7. Set unit status to allocated and application status to allocated.

8. Record batch_id such as BATCH-{Ymd}.

Row locking prevents double allocation

The allocation engine must select available units using a database row lock and re-check status inside the transaction. A pre-loaded count alone is not sufficient when multiple officers or jobs allocate concurrently.

STEP
21

Create a Manual Allocation

Primary user: Authorised Allocation Officer

POST /government/admin/allocations manually matches a specific application_id and unit_id. The unit must be available and the application must not already have an allocation.

Generated allocation field	Meaning
allocation_number	ALLOC-{YEAR}-{NNNNNN} or the program-code format.
status	offer_issued.
allocation_date	Creation date.
expiry_date	Default 30 days from allocation.
allocation_type	standard, priority, special or direct.
batch_id	MANUAL-{Ymd} for the supplied manual flow.

15 Phase 10 - Issue and Respond to Allocation Offers

Figure 4. Allocation offer, payment plan and handover flow

STEP
22

Issue, Resend or Expire an Offer Letter

Primary user: Government Admin / Allocation Officer

POST /allocations/{allocation}/issue-offer sets the letter number, issue date, expiry date and offer_issued status, then sends GovAllocationOfferMail. The admin can resend, expire, accept or reject on behalf of the citizen through the supplied routes.

☐ Confirm the citizen, application, program, estate and unit.

☐ Confirm the offer validity period and any deposit deadline.

☐ Review price, payment plan, interest and handover conditions.

☐ Generate the formal offer letter and record its number.

☐ Send to the verified citizen email and retain delivery evidence.

STEP
23

Citizen Accepts the Offer and Creates a Payment Plan

Primary user: Citizen / Applicant

POST /government/citizen/allocations/{allocation}/accept validates ownership, issued offer and expiry, then reads payment-plan metadata from the program.

Calculated item	Supplied logic
Unit price	unit.price.
Deposit percent	metadata.custom_plan_deposit_percent or 10%.
Deposit amount	unit price x deposit percent / 100.
Loan amount	unit price - deposit amount.
Monthly rate	annual interest rate / 100 / 12.
Installment amount	Amortisation formula using loan amount, monthly rate and installment count.
Schedule	Up to 360 JSON items with installment number, amount, due date and pending status.
Allocation status	payment_pending when deposit > 0; otherwise offer_accepted.

The allocation.payment_plan JSON stores type, label, frequency, installments, installment_amount, loan_amount, deposit_amount, deposit_percent, interest_rate, total_amount, currency and the installment item list. A deposit GovInvoice is generated where required. GovAllocationAcceptedCitizenMail confirms acceptance to the citizen.

Amortisation requires verification

Confirm rounding, zero-interest handling, first due date, last installment adjustment, maximum term, late penalties, early-repayment discount and legal disclosures against the live code and program policy.

STEP
24

Citizen Declines the Offer

Primary user: Citizen / Applicant

POST /government/citizen/allocations/{allocation}/decline records offer_rejected, rejection date and reason, releases the unit to available and sends citizen and agency emails.

Unit release control

Do not release the unit before the decline, expiry or revocation transaction completes. Preserve the allocation and offer history; do not delete it.

16 Phase 11 - Invoices, Payments and Receipts

Figure 5. Government invoice and payment flow

STEP
25

View and Understand Government Invoices

Primary user: Citizen / Finance Officer

GET /government/citizen/invoices lists GovInvoice records for the authenticated payer. Invoices can be created for application fees, allocation fees, installment payments, title-case fees and annual ground rent.

Invoice type	When created
application_fee	When the supplied approval workflow creates the application processing fee invoice.
allocation_fee	When an allocation-level fee is issued.
installment_payment	When the citizen selects a payment-plan installment.
title_case_fee	When a title case requires a processing fee.
annual_ground_rent	For FCTA annual land charges.

STEP
26

Pay an Invoice through a Gateway

Primary user: Citizen / Payer

POST /government/citizen/invoices/{invoice}/initiate-payment creates or finds a GovPaymentAttempt with GOV-{UNIQID}, calls PaymentGatewayFactory and redirects to Remita, Paystack, Flutterwave or Stripe. The callback verifies payment before the invoice is marked paid and a receipt is created.

· Select an enabled agency gateway.

· Confirm invoice number, amount and currency.

· Complete payment on the provider page.

· Return to Leaseora and wait for server-side verification.

· Download the GovReceipt only after confirmed payment.

STEP
27

Pay an Invoice from the Citizen Wallet

Primary user: Citizen / Payer

POST /government/citizen/invoices/{invoice}/pay-with-wallet loads the wallet in the invoice currency, applies FeeCalculationService for government_agency_payment, deducts invoice plus fee, creates a receipt, marks the invoice paid and credits the agency wallet in one transaction.

STEP
28

Pay by Bank Transfer and Upload Proof

Primary user: Citizen / Payer, then Finance Officer

POST /government/citizen/invoices/{invoice}/bank-transfer stores proof. The admin approves through /government/admin/revenue/bank-transfers/{proof}/approve or rejects through the corresponding reject route.

Proof is not settlement

A screenshot, teller or upload does not prove cleared funds. Finance must match account, amount, currency, reference and value date before approval.

STEP
29

Create and Pay a Specific Installment

Primary user: Citizen / Payer

POST /government/citizen/allocations/{allocation}/pay-installment finds the selected installment in payment_plan.items, prevents a duplicate invoice for the same installment number, creates the GovInvoice and redirects to payment.

Payment control	Required behaviour
Idempotency	Repeated callbacks or clicks must not create duplicate receipts, wallet credits or paid invoices.
Ownership	Only the payer or authorised officer may view or pay the invoice.
Amount and currency	Use the stored invoice values, not client-supplied replacements.
Receipt timing	Generate only after verified settlement or authorised waiver.
Allocation posting	Deposit/installment status must update the correct allocation and schedule item.
Audit	Record gateway reference, bank proof, wallet transaction, officer and timestamp.

17 Phase 12 - Post-Acceptance Allocation and Handover

STEP
30

Schedule and Complete Handover

Primary user: Government Admin / Estate Officer

Use the supplied allocation actions to schedule handover, mark the unit ready, upload handover documents and complete possession.

Action	Status / record effect
Schedule Handover	Sets handover_date and moves to the scheduled stage where configured.
Mark Ready for Handover	Confirms the unit and documents are ready.
Upload Handover Document	Stores possession/handover evidence.
Complete	Sets status = handover_completed and sends GovAllocationCompletedMail.

☐ Confirm required payment or deposit is settled.

☐ Confirm unit identity and physical readiness.

☐ Record inspection, keys, meter readings and defects where applicable.

☐ Upload signed handover evidence.

☐ Confirm citizen and agency copies are accessible.

☐ Update unit occupancy/status according to the live implementation.

STEP
31

Manage Revocation, Waiver and Manual Payment Actions

Primary user: Authorised Government Admin / Finance

The admin can revoke an allocation, record a payment, waive an invoice with reason, update a due date or issue another allocation invoice.

Action	Control
Revoke	Record authority and reason; release the unit only after the transaction completes; notify citizen.
Record Payment	Use only after independently verified settlement.
Waive Payment	Require written authority, reason and audit; do not issue a paid receipt.
Update Due Date	Retain previous due date and approval reason.
Issue Invoice	Confirm type, amount, currency, payer and due date.

Manual changes affect public money

Waivers, manual payments, due-date changes and revocations can affect revenue and citizen rights. Restrict them to authorised roles and require an audit reason.

18 Phase 13 - Revenue, Reconciliation and Agency Wallet

Figure 6. Agency revenue, TSA reconciliation and payout

STEP
32

Use the Agency Revenue Dashboard

Primary user: Finance / Revenue Officer

GET /government/admin/revenue shows all-time revenue, revenue this month, pending invoice count and pending amount. AJAX endpoints provide live statistics and a 12-month trend.

Metric	Source / question answered
Total revenue	SUM(GovReceipt.amount) - how much verified revenue has been receipted?
Revenue this month	Current-month GovReceipt total.
Pending invoice count	How many issued obligations remain unsettled?
Pending invoice amount	What value remains outstanding?
Monthly trend	How is verified revenue changing over 12 months?

STEP
33

Perform Remita/TSA Reconciliation

Primary user: Finance / Reconciliation Officer

POST /government/admin/revenue/reconciliations compares Remita/TSA credited amounts with Leaseora GovReceipt records and creates GovReconciliation records.

Status	Meaning	Required action
matched	TSA amount equals system amount.	Close with references retained.
variance_detected	Amount differs.	Investigate gateway, receipt, timing, duplicate or missing transaction.
pending_review	Unmatched transaction.	Assign to an officer and resolve.

TSA variances from the last seven days are surfaced as a system alert through the supplied dashboard logic.

STEP
34

Manage the Agency Wallet and Payouts

Primary user: Finance / Agency Admin, Super Admin for payout approval

The agency wallet receives eligible citizen-payment credits. It provides balance, transactions, payout requests and cancellation. Super Admin GovAgencyPayoutController manages agency withdrawal requests.

Wallet operation	Route / behaviour
View balance	GET /wallet/balance.
Request withdrawal	POST /wallet/withdraw.
Cancel payout	POST /wallet/payouts/{payout}/cancel.
Transactions	GET /wallet/transactions.
Payouts	GET /wallet/payouts.
Credit webhook	POST /api/government/webhooks/credit - gateway success.
Payout webhook	POST /api/government/webhooks/payout - transfer result.

Reconciliation source of truth

Match the GovInvoice, payment attempt, gateway or TSA reference, GovReceipt, agency-wallet entry and payout. A dashboard total alone is not a complete reconciliation.

19 Phase 14 - Manage FCTA Title Cases

Figure 7. FCTA title case and encumbrance workflow

STEP
35

Citizen Files a Title Case

Primary user: Citizen / Landholder

POST /government/citizen/title-cases creates a request for legal search, survey verification, certificate issuance, transfer or rectification according to the supplied FCTA flow.

Service	Supplied fee
Legal Search	NGN 50,000.
Survey Plan Verification	NGN 30,000.
Certificate Issuance	NGN 100,000.
Title Transfer	NGN 150,000.
Title Rectification	NGN 75,000.

The supplied processing durations are 14 days for legal search and 30 days for certificate issuance. Confirm current statutory fees and timelines before publication.

STEP
36

Verify, Check Encumbrances and Issue a Certificate

Primary user: Land / Title Officer

The admin can update status, verify, run encumbrance checks, assign an officer and issue the certificate.

Encumbrance check	Purpose
Existing mortgages	Identify registered lender interests.
Court orders	Identify restrictions or litigation.
Government acquisition notices	Identify compulsory acquisition or public interest restrictions.
Boundary disputes	Identify survey or neighbouring-title conflicts.
Unpaid ground rent	Identify outstanding statutory charges.

GET /government/land-admin-rules returns JSON of FCTA land-use zones, ground-rent schedules, title types and processing timelines.

Title data requires legal authority

Leaseora supports workflow and evidence management. It does not itself create legal title unless the authorised government process and signatory requirements are satisfied.

20 Phase 15 - Maintain the Government Asset Registry

STEP
37

Register Government-Owned Assets

Primary user: Government Asset / Estate Officer

GovAssetController is a resource controller for /government/admin/assets. Use it to track government land parcels, buildings and infrastructure linked to programs, estates or allocations.

Asset-data area	Recommended content
Identity	Asset name, code, type and official reference.
Ownership / custody	Agency, department and responsible officer.
Location	Address, state, country, coordinates and survey reference.
Program linkage	Related program, estate, unit or allocation.
Status	Operational, planned, under development, disposed or other approved state.
Documents	Title, survey, valuation, inspection and maintenance evidence.
Financial data	Approved value, revenue or cost fields where configured.
Audit	Creation, modification, assignment and disposal history.

Asset registry is not a substitute for title registration

Use the asset registry as the operational record. Preserve the underlying statutory title and land-administration documents in the appropriate legal workflow.

21 Phase 16 - Respond to Citizen Inquiries

STEP
38

Use the Government Inquiry Inbox

Primary user: Citizen Support / Government Admin

GovernmentInquiryInboxController provides a real-time inbox for questions about programs, applications and allocations.

Action	Route / behaviour
View all	GET /government/admin/support/inquiries.
Unread count	GET /support/inquiries/unread-count.
Open inquiry	GET /support/inquiries/{roomId}.
Reply	POST /support/inquiries/{roomId}/reply.
Resolve	PATCH /support/inquiries/{roomId}/resolve.
Reopen	PATCH /support/inquiries/{roomId}/reopen.

· Confirm the citizen and record context before replying.

· Do not disclose another applicant's data.

· Explain status; do not promise approval or allocation.

· Escalate legal, payment, identity or fraud questions to the correct officer.

· Resolve only when the question is answered and no action remains.

22 Phase 17 - Tax Office Sub-Portal

STEP
39

Review Landlord Tax and Compliance Records

Primary user: Tax Office User

Use /government/tax-office to access dashboards, tax records, exports, landlord compliance, tax history, properties, flags, reconciliation and analytics.

Feature	Route / management question
Dashboard	/tax-office/dashboard - current workload and risk.
Tax records	/tax-records and /tax-records/{id} - individual records.
Export	/tax-records/export - authorised reporting.
Landlord compliance	/landlords and /landlords/{id}/compliance.
Tax history	/landlords/{id}/tax-history.
Properties	/properties - property-level tax context.
Compliance flags	/compliance-flags - unresolved risks.
Reconciliation	/reconciliation - compare tax/payment records.
Revenue analytics	/analytics/revenue.
Compliance analytics	/analytics/compliance.

STEP
40

Use Tax Office AI Analytics

Primary user: Tax Analyst / Authorised Official

TaxAIAnalyticsController supports an AI dashboard, risk assessment, revenue forecast, anomaly detection, chatbot and AI reports.

AI feature	Route	Required human review
Analytics dashboard	/tax-office/ai/analytics-dashboard.	Check source completeness and reporting period.
Risk assessment	/tax-office/ai/risk-assessment.	Do not treat risk as final liability or guilt.
Revenue forecast	/tax-office/ai/revenue-forecast.	Compare with approved budget and economic assumptions.
Anomaly detection	/tax-office/ai/anomaly-detection.	Investigate before enforcement.
AI chatbot	/tax-office/ai/chatbot.	Do not expose taxpayer data in uncontrolled prompts.
AI reports	/tax-office/ai/reports.	Authorised officer signs off formal reports.

AI is decision support

AI can identify patterns and prepare summaries. It must not issue a tax assessment, reject an application, allocate a unit, find fraud or determine title without the authorised human and legal process.

23 Phase 18 - Super Admin Oversight

STEP
41

Manage Agencies and Global Government Statistics

Primary user: Super Admin / Admin

Use /superadmin/gov-agencies to list, create, view, update, activate, deactivate and soft-delete agencies. Deletion is blocked where active programs exist in the supplied design.

Global metric	Source / oversight use
Total / active agencies	GovAgency counts.
Active programs	GovProgram where status = active.
Estates / units	GovEstate and GovUnit counts.
Pending applications	GovApplication in submitted or under_review.
Total revenue	SUM GovReceipt.amount.
TSA variances	GovReconciliation where variance_detected.

STEP
42

Review System Alerts, AI Recommendations and Agency Payouts

Primary user: Super Admin / Government Platform Operations

The dashboard creates rule-based recommendations from real thresholds and GovAgencyPayoutController manages withdrawal requests.

Supplied condition	Recommendation
pending_applications > 20	Allocate more resources to the Verification Team.
pending_invoices_amount > 1,000,000	Initiate automated payment reminders.
units_available < 10	Accelerate new unit publishing.
Otherwise	System operating optimally.

Thresholds are operational prompts

These recommendations are simple supplied thresholds, not statutory decisions. Super Admin should confirm agency capacity, data freshness and local policy before acting.

24 Phase 19 - Mobile Citizen Services and Webhooks

STEP
43

Use the Government Mobile API

Primary user: Citizen / Mobile App

GovernmentMobileController mirrors public browsing and authenticated citizen functions under /api/mobile/government.

Endpoint	Access	Purpose
GET /programs	Public	Browse programs.
GET /programs/{program}	Public	Program detail.
GET /estates	Public	Browse estates.
GET /estates/{estate}	Public	Estate detail.
GET /units	Public	Browse available units.
GET /units/{unit}	Public	Unit detail.
GET /citizen/dashboard	Sanctum	Citizen dashboard.
GET /citizen/applications	Sanctum	My applications.
POST /citizen/applications	Sanctum	Submit application.
GET /citizen/allocations	Sanctum	My allocations.
POST /citizen/check-eligibility	Sanctum	Eligibility check.

The supplied mobile controller also includes payment orchestration, invoice generation and allocation acceptance mirroring GovRevenueController. The CSRF-exempt credit and payout webhooks remain server endpoints and must validate provider signatures.

Mobile parity does not reduce controls

Ownership, profile verification, country scoping, payment verification, duplicate prevention and agency isolation must be identical across web and mobile APIs.

25 Status Lifecycles and Record Relationships

Record	Key statuses supplied	Operational meaning
GovAgency	active/inactive; status may also be present.	Controls agency access and publication.
GovProgram	active/deactivated/closed; application flags.	Controls visibility and submissions.
GovEstate	planning, active, operational, completed, decommissioned.	Estate development/operating state.
GovUnit	available, reserved, allocated, occupied.	Allocation availability and possession.
GovApplication	submitted, under_verification, under_review, scored, approved, rejected, waitlisted, allocated, withdrawn, incomplete.	Citizen application lifecycle.
GovAllocation	offer_issued, payment_pending, offer_accepted, offer_rejected, offer_expired, handover_scheduled, ready_for_handover, handover_completed, revoked.	Offer, payment and possession lifecycle.
GovInvoice	draft, issued, sent, pending, paid, overdue, cancelled, waived.	Government payment obligation.
GovReconciliation	matched, variance_detected, pending_review.	TSA/system comparison.

Confirm exact enum values

The guide preserves the status names supplied. Validate the live database enums, transition guards and notification behaviour before staff training.

26 Notification and Email Matrix

Notification / mail	Recipient	Trigger / purpose
GovApplicationSubmittedMail	Citizen	Application saved.
GovApplicationStatusMail	Citizen	Application status changed.
GovAllocationOfferMail	Citizen	Formal allocation offer issued or resent.
GovAllocationAcceptedMail	Agency Admin	Citizen accepted the allocation.
GovAllocationAcceptedCitizenMail	Citizen	Acceptance confirmation.
GovAllocationDeclinedCitizenMail	Citizen	Citizen copy of decline.
GovAllocationDeclinedMail	Agency Admin	Citizen declined the allocation.
GovAllocationRevokedMail	Citizen	Allocation revoked.
GovAllocationCompletedMail	Citizen	Handover completed.
Invoice reminder	Citizen	GovRevenueController sends payment reminder.
Bank-proof rejection / approval notification	Citizen	Admin verifies bank transfer.
System alert	Government Admin / Super Admin	High pending applications, revenue, low stock or TSA variance.

Notification is not the legal record

Email or in-app delivery supports communication. The authoritative status, offer, invoice, receipt, allocation and title records remain in the database and stored documents.

27 Staff Permissions and Segregation of Duties

Role	Typical access	Control point
Agency Administrator	Agency setup, staff, programs and dashboard.	Does not independently reconcile money or issue title without authority.
Program Officer	Program terms, dates, fees, images and statistics.	No unilateral allocation or waiver.
Verification Officer	Application identity, documents and notes.	Cannot edit scores or allocate units without separate permission.
Allocation Officer	Score review, process allocation, offers and status.	Cannot change unit price/payment settlement.
Estate / Unit Officer	Estates, units, publication, reservation and work orders.	Cannot approve citizen applications.
Finance Officer	Invoices, payment verification, receipts, reconciliation and wallet.	Cannot alter eligibility or allocation policy.
Land / Title Officer	Title cases, encumbrances and certificate workflow.	Uses approved legal authority and signatory.
Tax Analyst	Tax records, compliance, flags, reconciliation and analytics.	No access to unrelated government applications.
Citizen Support	Inquiry responses and guidance.	Cannot approve, reject, allocate, waive or verify settlement.
Super Admin	Platform configuration, agency management and payouts.	Agency statutory decisions remain with authorised government officials.

Minimum security practices

· Individual accounts and multi-factor authentication where available.

· Least-privilege permissions and agency isolation.

· Immediate access removal when employment or assignment ends.

· Encryption for credentials and sensitive citizen documents.

· Audit reasons for status, score, allocation, waiver, revocation and reconciliation changes.

· Restricted exports containing NIN, income, tax, title or payment data.

· Webhook signature validation, idempotency and replay protection.

· Periodic permission, bank-account and gateway review.

28 Dashboards, Reports and Management Review

Dashboard / report	Management question answered
Agency dashboard	Is the agency configured, active and operating within its jurisdiction?
Program statistics	How many applications, approvals, allocations and available units exist?
Estate / unit statistics	What stock is planned, published, reserved, allocated or occupied?
Application pipeline	What is submitted, incomplete, under review, scored, approved or waitlisted?
Allocation batch	Which method, score, unit and batch produced each offer?
Revenue dashboard	What is receipted, pending, overdue and collected this month?
TSA reconciliation	Which transactions match and which have variance?
Agency wallet / payouts	What balance and withdrawal obligations exist?
Title cases	What is pending verification, encumbered or ready for certificate?
Tax Office analytics	Which landlords, properties or records require compliance review?
Super Admin overview	Which agencies, programs, applications, revenue or variances need attention?

Recommended review cadence

Frequency	Review
Daily	New applications, verification backlog, expiring offers, pending bank proofs, failed gateway attempts, urgent inquiries and TSA variances.
Weekly	Program windows, available units, scored applications, allocation batches, overdue invoices, title cases and staff workload.
Monthly	Revenue, reconciliation, wallet/payouts, allocation outcomes, handovers, application demographics and unit inventory.
Quarterly	Program policy, scoring fairness, access permissions, gateway/bank configuration, title timelines and tax-compliance trends.
Before allocation batch	Available units, eligible/scored list, method approval, conflict checks and database backup.
Before handover	Payment, receipt, unit readiness, documents, inspection, identity and appointment.

29 Worked Examples

Example 1 - FMHUD Featured Housing Program

Stage	What happens
Agency	FMHUD agency is active, country NG and currency NGN.
Program	A featured housing program is created with application window and NGN fee.
Stock	Estate and published available units are linked.
Citizen	A verified citizen checks eligibility, enters 11-digit NIN and submits documents.
Review	Agency verifies and scores; citizen meets threshold.
Allocation	Merit process creates an offer for an available unit.
Acceptance	Citizen accepts, deposit invoice is generated.
Payment	Citizen pays through Remita; callback is verified and receipt issued.
Handover	Agency schedules and completes handover with documents.

Example 2 - FHA Allocation with Waitlist

An FHA program receives more scored applications than units. The published criteria include age 21-55, BVN and the supplied weighted factors. The allocation engine selects the number of candidates that matches available units; remaining eligible citizens can be waitlisted. Each decision preserves score, method, batch and unit availability.

Example 3 - FMBN Mortgage / Rent-to-Own Program

The program injects NHF, LTV, rate and tenure information. A citizen provides NHF contribution history and income. After approval and allocation, the citizen accepts a payment plan, pays the deposit and then creates individual installment invoices from allocation.payment_plan. Finance reconciles every receipt.

Example 4 - FCTA Title Transfer

A citizen files a title-transfer case, receives the supplied NGN 150,000 fee invoice, pays, and the officer checks existing mortgage, court order, acquisition notice, boundary dispute and ground rent. When cleared, the authorised certificate or transfer evidence is issued and retained.

Example 5 - TSA Reconciliation Variance

Leaseora shows NGN 5,000,000 in GovReceipts while Remita/TSA reports NGN 4,950,000 for the same period. GovReconciliation records variance_detected. Finance investigates fee/net settlement, timing, duplicate or missing reference before closing. The dashboard alert remains until resolved.

30 Government Agency Onboarding Checklist

Agency and policy setup

☐ Agency legal name, code, type, parent and jurisdiction approved.

☐ Country, currency and public contact details confirmed.

☐ Government Admin and officer accounts created with individual access.

☐ Program policy, fees, dates and eligibility rules approved.

☐ Allocation method and committee authority documented.

☐ Offer, payment-plan, handover and revocation policy approved.

☐ Title-case rules, fees and signatories approved.

☐ Tax Office scope and permissions approved.

Finance and technology setup

☐ Primary agency bank account configured and independently verified.

☐ Remita/TSA and secondary gateway credentials tested.

☐ Gateway callbacks and government webhooks verified and signed.

☐ Agency wallet and payout approval configured.

☐ Invoice, receipt and reconciliation formats approved.

☐ Email delivery, support inbox and notification recipients tested.

☐ Mobile APIs tested with public and Sanctum-authenticated scenarios.

☐ Backup, audit, incident response and support contacts documented.

Data migration / pilot

☐ Estate register cleaned and approved.

☐ Unit numbers, prices, statuses and publication reconciled.

☐ Existing applications and allocations mapped where migration applies.

☐ Open invoices, receipts and TSA records reconciled.

☐ One pilot program and small unit batch selected.

☐ Success measures and go-live gate approved.

31 User Acceptance Testing and Go-Live Validation

Test area	Test case	Expected result
Agency isolation	Government Admin tries another agency record.	Access denied; no data leakage.
Agency setup	Create, activate and configure agency.	Correct dashboard and jurisdiction.
Bank / gateway	Add account; configure/test Remita and secondary gateway.	Secure successful connection.
Program	Create, AI-draft, review, activate, close.	Correct data and application availability.
Estate / units	Create estate, bulk units, publish/reserve/release.	Unique inventory and correct statuses.
Citizen browse	Browse programs, estates and units by country.	Only eligible public records shown.
Eligibility	Test score below and above threshold.	Correct score, requirement and recommendation.
Application	Submit valid and invalid NIN/document cases.	Confirmation or incomplete with notes.
Verification	Verify and fail document review.	Correct status and audit.
Scoring	Single and batch scoring.	Reproducible score and status.
Allocation	Merit, FIFO, ballot and manual under concurrency.	No duplicate unit allocation.
Offer	Issue, resend, expire, accept and decline.	Correct emails, status and unit release.
Payment plan	Accept with deposit, interest and installments.	Correct JSON schedule and invoice.
Gateway payment	Pay test invoice and replay callback.	One receipt and one agency credit only.
Wallet payment	Pay invoice plus fee.	Correct debit, fee, receipt and agency credit.
Bank transfer	Upload proof; approve and reject.	Pending until authorised settlement review.
Handover	Schedule, mark ready, upload, complete.	Timeline and documents complete.
Revenue	Dashboard and monthly trend.	Totals reconcile with receipts.
TSA reconciliation	Matched and variance cases.	Correct status and alerts.
Title case	File, pay, verify, encumbrance, certificate.	Full controlled history.
Tax Office	Review and export authorised records.	No unrelated data access.
Mobile API	Public browse and protected actions.	Parity with web and correct auth.
Notifications	Trigger every supplied mail.	Correct recipient and context.

Go-live gate

Do not place live citizens, public money or allocation stock into production until agency isolation, unit concurrency, payment verification, receipt generation, reconciliation, offer expiry, permission and audit tests pass.

32 Common Issues and Troubleshooting

Issue	Recommended action
Government user cannot access dashboard	Confirm active agency, Government role and government middleware.
Admin sees another agency's data	Stop use immediately; review government_isolation on all routes and queries.
Program not visible	Confirm active status, country, dates, featured/public flags and application acceptance.
Estate or unit missing	Confirm country scope, estate status, unit available status and is_published.
Eligibility result unexpected	Review inputs, agency adapter rules, threshold and scoring version.
Duplicate application blocked	Check for existing active application in the same program.
Application becomes incomplete	Review NIN format, age, income, NHF and verification_notes.
Score seems inconsistent	Review AI base, bonuses, Nigeria score and normalisation implementation.
Allocation does not run	Confirm scored applications, available units, method and permissions.
Unit allocated twice	Review row locking, transactions and status re-check.
Citizen cannot accept offer	Confirm ownership, issue fields, expiry, allocation status and profile.
Payment plan wrong	Review metadata, deposit, interest, term, first date and rounding.
Gateway shows success but invoice pending	Check server verification, callback reference, webhook and provider status.
Bank proof uploaded but unpaid	Finance must verify cleared funds and approve.
Wallet payment fails	Check currency wallet, invoice amount, fee and balance.
Receipt duplicated	Review callback idempotency and unique transaction constraints.
TSA variance alert	Compare receipt/gateway/TSA amount, net fees, date and reference.
Unit not released after decline/revoke	Complete approved status transaction and update unit availability.
Title case delayed	Review assigned officer, required evidence, fee and encumbrance result.
Mobile result differs from web	Compare country, auth, ownership and service calls.
AI output seems wrong	Use source data and policy; disregard unsupported AI output.

Support information to include

Provide agency, program, estate, unit, application/allocation/invoice reference, affected user, date/time, route/action, expected result, actual result and a redacted screenshot. Never send full NIN, gateway credentials or unredacted financial documents.

33 Frequently Asked Questions

Can any landlord create a government agency?

No. Agency creation is a Super Admin or approved self-registration workflow. The account must be activated and hold a Government role.

Can a real estate company use the module?

Only when formally authorised within the government agency workflow and given the required role and agency-scoped permissions.

Can citizens browse without logging in?

The supplied overview says public browsing is available, while one route note applies auth to /government. Confirm the live middleware and publish the correct rule.

Does an eligibility score guarantee allocation?

No. It is a preliminary or scoring input; approval, available units and the allocation method still apply.

Can one citizen submit two active applications to the same program?

The create flow blocks a duplicate active application for the same program.

What allocation methods are supported?

Merit, FIFO, ballot and manual allocation.

Can an officer manually allocate a unit?

Yes, if authorised, the unit is available and the application has no allocation.

How long is an offer valid?

The supplied default is 30 days, but program policy or admin configuration may determine the actual period.

Can the citizen pay in installments?

Yes, when the program metadata creates a payment plan. Each installment can generate its own invoice.

Which payment methods are supported?

Remita/TSA, Paystack, Stripe, Flutterwave, wallet and bank transfer are described.

Does bank proof mean payment is complete?

No. An authorised officer must verify cleared funds.

Can an invoice be waived?

Yes through an authorised admin action with a recorded reason.

What happens when an offer is declined or expires?

The allocation records the outcome and the unit is released to available after the workflow completes.

What is TSA reconciliation?

It compares Remita/TSA credited amounts with Leaseora GovReceipt totals and records matched, variance or pending-review results.

Does the module issue land title automatically?

No. It manages the authorised title-case workflow, evidence, checks and certificate record.

What does the Tax Office see?

Authorised tax records, landlord compliance, properties, flags, reconciliation and analytics according to permission.

Can AI approve an application or tax case?

No. AI supports auto-fill, scoring inputs and analytics; human statutory decision remains required.

Is the mobile app equivalent to web?

The supplied GovernmentMobileController mirrors core citizen browsing, applications, allocations and payment orchestration, subject to the same controls.

34 Quick Reference - 43 Operational Steps

1. Create the GovAgency from Super Admin.

2. Approve a self-registered agency.

3. Government Admin logs in.

4. Configure agency settings.

5. Add and verify agency bank accounts.

6. Configure and test Remita/TSA and other gateways.

7. Create the government program.

8. Review AI auto-fill and activate/close the program.

9. Create the estate.

10. Create, publish and control units.

11. Citizen opens the government portal.

12. Citizen browses programs and agency requirements.

13. Citizen browses estates and available units.

14. Citizen checks eligibility.

15. Citizen opens dashboard and application form.

16. Citizen submits NIN, data and documents.

17. Agency lists and filters applications.

18. Officer verifies documents and changes status.

19. Officer scores one or batches applications.

20. Run merit, FIFO or ballot allocation.

21. Create a manual allocation when authorised.

22. Issue, resend or expire the offer letter.

23. Citizen accepts and receives payment plan/deposit invoice.

24. Citizen declines and unit is released.

25. Citizen views invoices.

26. Citizen pays through gateway.

27. Citizen pays through wallet.

28. Citizen uploads bank-transfer proof.

29. Citizen creates and pays an installment invoice.

30. Agency schedules and completes handover.

31. Agency manages revocation, waiver and manual payment actions.

32. Finance reviews the revenue dashboard.

33. Finance performs Remita/TSA reconciliation.

34. Agency manages wallet and payout requests.

35. Citizen files a title case.

36. Title officer verifies, checks encumbrance and issues certificate.

37. Agency maintains the asset registry.

38. Citizen support manages inquiry chat.

39. Tax Office reviews tax/compliance records.

40. Tax Office uses AI analytics with human review.

41. Super Admin oversees agencies and global statistics.

42. Super Admin reviews alerts and agency payouts.

43. Mobile app uses public and authenticated Government APIs.

35 Technical Reference - Core Models

Model / table	Purpose and key fields
GovAgency / gov_agencies	name, code, type, parent, country, jurisdiction, active/status, currency, metadata.
GovProgram / gov_programs	agency, name/code/type, fee, dates, accepting/featured, country, payment-plan metadata.
GovEstate / gov_estates	agency/program, location, status, total units, coordinates.
GovUnit / gov_units	estate, unit number/type, bedrooms/bathrooms, area, price, status, publication.
GovApplication / gov_applications	application number, citizen, program/unit, NIN, JSON data/documents, status, score and timeline.
GovAllocation / gov_allocations	application, unit, program, offer, acceptance, payment plan, handover, batch, approval and status.
GovInvoice / gov_invoices	agency, polymorphic invoiceable, type/category, payer, amounts, status, issue/due/paid dates, metadata.
GovReceipt / gov_receipts	invoice, agency, amount, currency, method, receipt number, paid date and reference.
GovReconciliation / gov_reconciliations	TSA amount, system amount, variance and status.
GovAgencyBankAccount	Agency receiving/payout account and primary/active controls.
GovAgencyPaymentGateway	Agency-specific gateway configuration and active state.
GovPaymentAttempt	Gateway payment attempt and GOV reference.
GovAllocation activity / timeline records	Actor, date, status transition and description as assembled by the controller.
GovTitleCase	Citizen title request, fee, documents, status, officer, encumbrances and certificate.
GovAsset	Government land, building or infrastructure asset.
Government inquiry ChatRoom / messages	Citizen and government support conversation context.

36 Technical Reference - Controllers and Services

Class	Responsibility
GovAuthController	Government login/logout and role redirect.
GovAgencyRegistrationController	Public agency self-registration.
GovAgencyController	Agency CRUD, dashboard stats, alerts and AI recommendations.
SuperAdminGovAgencyController	Platform agency creation, activation, deactivation and oversight.
GovSettingsController	Agency portal settings.
GovProgramController	Program CRUD, AI auto-fill, activation, closure and statistics.
GovEstateController	Estate CRUD, bulk units, work orders, images and statistics.
GovUnitController	Unit CRUD, publish, reserve, release, duplicate and bulk actions.
CitizenPortalController	Country-scoped landing, programs, estates, units, citizen dashboard and requirement injection.
GovApplicationController	Eligibility, application submission, admin review, verification, status, scoring and batch scoring.
GovAllocationController	Automated/manual allocation, offers, citizen response, installment invoice and handover actions.
GovRevenueController	Invoices, gateway/wallet/bank payments, callbacks, receipts, reconciliation and reports.
GovTitleCaseController	Title-case filing, status, verification, encumbrances, assignment and certificate.
GovAssetController	Government asset registry.
GovAgencyBankAccountController	Agency bank accounts.
GovAgencyPaymentGatewayController	Per-agency gateway setup and status.
GovAgencyWalletController	Agency wallet, withdrawals, transactions, payouts and webhooks.
GovAgencyPayoutController	Super Admin agency payout management.
GovernmentInquiryInboxController	Government inquiry chat.
GovernmentMobileController	Mobile citizen portal and payment orchestration.
AllocationEngine	Scoring integration and concurrent allocation processing.
NigeriaGovernmentAdapter	FMHUD/FHA/FMBN/FCTA rules, validation, scoring and Remita config.
CurrencyExchangeService	Display conversion for citizen-facing program/unit values.
PaymentGatewayFactory	Creates configured Remita/Paystack/Flutterwave/Stripe processors.
FeeCalculationService	Government wallet payment fee configuration.
Tax Office controllers	Tax records, compliance, properties, flags, reconciliation, analytics, AI and exports.

37 Technical Reference - Controller Actions by Functional Area

Functional area	Key actions / routes
Agency setup	POST /superadmin/gov-agencies; GET/POST /government/register; activate/deactivate.
Government login	GovAuthController@create / @store.
Settings	GovSettingsController@index / @update.
Bank accounts	add, set-primary, toggle-active.
Payment gateways	configure, enable, disable, status.
Programs	create/store, ai-autofill, activate, deactivate, close, images, statistics, eligibility preview.
Estates	store, status, bulk units, images, work orders, statistics.
Units	store, publish, unpublish, reserve, release, duplicate, bulk-publish, work orders.
Citizen browse	CitizenPortalController@index, @programs, estates and units actions.
Eligibility / application	checkEligibility, create, store, citizen dashboard.
Admin application	index, verify, status, score, batch-score.
Allocation	processAllocations, store manual, issue/resend/expire, admin accept/reject.
Citizen offer	accept, decline, payInstallment.
Allocation admin	complete, revoke, record-payment, waive-payment, update-payment-due, schedule/ready/upload handover, invoices.
Citizen invoice	myInvoices, initiatePayment, payment callback, payWithWallet, bankTransfer.
Bank proof review	approve / reject under government admin revenue.
Revenue	dashboard, AJAX stats/trend, performReconciliation.
Agency wallet	balance, withdraw, cancel payout, transactions, payouts.
Webhooks	/api/government/webhooks/credit and /payout.
Title cases	citizen store; admin index, status, verify, encumbrances, assign, certificate.
Land rules	GET /government/land-admin-rules.
Assets	GovAssetController resource.
Inquiries	index, unread, show, reply, resolve, reopen.
Tax Office	dashboard, records, export, compliance, history, properties, flags, reconciliation, analytics and AI routes.
Mobile	GovernmentMobileController public browse and Sanctum citizen endpoints.

38 Technical Reference - Payment, Receipt and Reconciliation Controls

Control point	Required behaviour
Invoice amount	Use stored total_amount and currency; ignore client modifications.
Gateway session	Include invoice, citizen, agency, amount, currency and unique GOV reference.
Gateway verification	Verify server-side and process callback/webhook idempotently.
Wallet payment	Check balance; calculate fee; debit, receipt and agency credit atomically.
Bank evidence	Store proof in pending state; verify bank settlement before approval.
GovReceipt	Create once after paid status; use unique receipt and transaction references.
Agency wallet credit	Prevent duplicate credit on callback replay.
Installment posting	Use metadata.installment_number and prevent duplicate invoice/payment.
Waiver	Use waived status and authority/reason; distinguish from paid.
Reconciliation	Match invoice, attempt, receipt, gateway/TSA, wallet and payout.
Webhook security	Validate signature, timestamp, environment and replay.
Payout	Approve within available settled balance and record bank result.

39 Technical Reference - Allocation, Scoring and Concurrency

Control point	Required behaviour
Candidate set	Only applications eligible under the approved status and program.
Available stock	Count and select units belonging to the program and agency.
Method approval	Store merit, FIFO, ballot or manual method and decision authority.
Score version	Retain scoring inputs, formula/version and output.
Row lock	SELECT available unit FOR UPDATE inside the allocation transaction.
Re-check	Confirm unit is still available and application has no allocation.
Atomic update	Create allocation and update unit/application in one transaction.
Batch identity	Store BATCH-{date} or manual batch reference.
Failure recovery	Rollback all records when any step fails.
Audit / appeal	Preserve method, candidate list, score, unit and reason.

Ballot transparency

Random ordering must use an approved, reproducible or independently auditable process where public policy requires it. The supplied scenario names RANDOM ORDER but does not define seed, witness or publication controls.

40 Nigerian Agency Rules Reference

Agency / service	Supplied rules
FMBN	NHF contribution 2.5%; LTV 90%; NHF 6%, Non-NHF 9%, Rent-to-Own 6.5%; tenure 5-30 years; NHF number validation.
FHA	Age 21-55; BVN required; income 25%, employment 20%, family 15%, housing 15%, NHF years 15%, credit 10%.
FMHUD	Age 18-60; NIN; minimum monthly income NGN 30,000; priority categories.
FCTA	C-of-O, R-of-O, Deed of Assignment; ground rent; encumbrance and title case processing.
General Nigeria eligibility preview	100-point income/employment/family/housing/NHF/credit score with threshold 50.
Government payments	Remita/TSA primary; Paystack secondary in portal setup; other supported gateways appear in payment flow.

Verify current policy

Rates, fees, ages, thresholds and statutory rules can change. The values above are the supplied scenario, not a legal or regulatory update. Confirm them with the relevant agency before launch.

41 Data Security, Privacy and Audit Requirements

Data / action	Required protection
NIN / BVN / identity documents	Access control, encryption, masked display and retention limits.
Income / employment / credit	Purpose limitation, consent, lawful criteria and restricted exports.
Citizen documents	Malware scan, protected URLs, audit access and deletion policy.
Bank / gateway credentials	Encrypted at rest; never returned to client or logged.
Payment callbacks / webhooks	Signed, idempotent, replay-protected and environment-checked.
Allocation decisions	Actor, method, score, batch, unit and timestamp retained.
Waivers / manual payments	Approval reason, evidence and immutable history.
Title / encumbrance data	Legal access controls and evidential chain.
Tax records	Tax-office-only permission and protected exports.
AI prompts / outputs	Minimise personal data; store source, version and human decision separately.
Agency isolation	Applied to every web/API query, export and background job.

42 Implementation Details Requiring Confirmation

Area	Why confirmation is required
Public portal middleware	Overview says unauthenticated browsing; one landing-page note states auth. Confirm route policy.
Government role names	Exact role labels and tax-office authorisation middleware are not fully enumerated.
Program status values	Actions are supplied, but complete enum and visibility guards are not.
Application invoice timing	Scenario creates application_fee invoice on approval; confirm whether fee is due before or after review.
Scoring normalisation	AI max 1,000 + bonuses + Nigeria score 100 lacks a final documented formula.
Eligibility legality	Sensitive criteria require agency/legal validation, explanation and appeal process.
Ballot audit	Random-order seed, witness and reproducibility are not supplied.
Offer expiry condition	Supplied acceptance text contains an expiry comparison that should be checked against intended logic.
Payment-plan edge cases	Zero interest, rounding, proration, final installment, grace, penalties and early repayment need confirmation.
Gateway configuration	Portal setup prioritises Remita/Paystack; payment flow also names Stripe/Flutterwave. Confirm enabled set.
Callback/webhook idempotency	Unique constraints and replay handling are not detailed.
Bank proof completion	Storage/verification fields and notification classes are not fully listed.
Agency wallet settlement	Gross/net fee treatment, payout timing and reversal rules require policy.
TSA data source	Import/API format, reference matching and reconciliation tolerance are not supplied.
Unit occupancy after handover	Exact unit status update on handover completion is not stated.
Title-case model fields	Full status list, invoice link and certificate storage are not supplied.
Asset registry schema	Specific GovAsset fields and lifecycle are not supplied.
Audit timeline model	Controller assembles a timeline, but underlying event model is not named.
Email delivery and retry	Queue, retry and failed-mail handling are not supplied.
Mobile payment endpoints	Controller capability is described, but full endpoint list is not supplied.
Tax AI data governance	Prompt, model, retention and explainability controls are not supplied.

Source-grounded limitation

This guide preserves the supplied backend names, values and behaviours. Items above are deliberately not filled with assumptions and must be checked against the live code, configuration, government policy and applicable law before formal training or production use.

43 Key Highlights

Capability	Business value
Multi-tenant government infrastructure	Each agency manages isolated programs, citizens, allocations and revenue.
Country-scoped public portal	Citizens see relevant programs, estates, units and converted display values.
Nigeria-specialised rules	FMHUD, FHA, FMBN and FCTA requirement adapters.
Structured eligibility and scoring	Pre-check, verification, AI/government scoring and batch processing.
Auditable allocation	Merit, FIFO, ballot and manual methods with locked unit assignment.
Offer and payment-plan workflow	Offer letters, deposit, amortisation, installments and handover.
Multi-channel government payments	Remita/TSA, Paystack, Stripe, Flutterwave, wallet and bank transfer.
Revenue accountability	GovReceipt, agency wallet, TSA reconciliation, variances and payouts.
Land administration	Title cases, encumbrance checks, certificates and rules API.
Tax Office oversight	Landlord tax records, compliance, reconciliation and AI analytics.
Citizen support and mobile access	Inquiry inbox and mobile browsing/application/allocation services.
Super Admin control	Agency lifecycle, global statistics, alerts and payout oversight.

LEASEORA

GOVERNMENT SERVICES

Digital infrastructure for public housing programs, citizen applications, transparent allocation, government revenue and accountable land administration.

Support and onboarding

support@leaseora.com | leaseora.com

Was this article helpful?

Your feedback helps us improve our documentation.

Back to Knowledge Base More in GOVERNMENT

Article Info

Category GOVERNMENT

Reading Time 54 min

Published Jul 30, 2026

Tweet Share

🤝

Need more help?

Our support team is available to assist you.

Contact Support

GOVERNMENT SERVICES

1 Purpose, Scope and Terminology

What one connected public-housing record should contain

2 Roles and Responsibilities

3 Complete Module Journey

4 Access Control, Route Tiers and Data Isolation

Access validation checklist

5 Implementation Prerequisites and Agency Onboarding

Business and policy information to prepare

Recommended implementation sequence

6 Phase 1 - Create and Activate a Government Agency

7 Phase 2 - Configure the Government Portal

8 Phase 3 - Create and Manage Government Programs

9 Phase 4 - Create Estates and Units

10 Phase 5 - Citizen Discovers Programs, Estates and Units

11 Phase 6 - Check Eligibility Before Applying

12 Phase 7 - Citizen Submits an Application

13 Phase 8 - Verify, Review and Score Applications

14 Phase 9 - Allocate Units

15 Phase 10 - Issue and Respond to Allocation Offers

16 Phase 11 - Invoices, Payments and Receipts

17 Phase 12 - Post-Acceptance Allocation and Handover

18 Phase 13 - Revenue, Reconciliation and Agency Wallet

19 Phase 14 - Manage FCTA Title Cases

20 Phase 15 - Maintain the Government Asset Registry

21 Phase 16 - Respond to Citizen Inquiries

22 Phase 17 - Tax Office Sub-Portal

23 Phase 18 - Super Admin Oversight

24 Phase 19 - Mobile Citizen Services and Webhooks

25 Status Lifecycles and Record Relationships

26 Notification and Email Matrix

27 Staff Permissions and Segregation of Duties

Minimum security practices

28 Dashboards, Reports and Management Review

Recommended review cadence

29 Worked Examples

Example 1 - FMHUD Featured Housing Program

Example 2 - FHA Allocation with Waitlist

Example 3 - FMBN Mortgage / Rent-to-Own Program

Example 4 - FCTA Title Transfer

Example 5 - TSA Reconciliation Variance

30 Government Agency Onboarding Checklist

Agency and policy setup

Finance and technology setup

Data migration / pilot

31 User Acceptance Testing and Go-Live Validation

32 Common Issues and Troubleshooting

33 Frequently Asked Questions

34 Quick Reference - 43 Operational Steps

35 Technical Reference - Core Models

36 Technical Reference - Controllers and Services

37 Technical Reference - Controller Actions by Functional Area

38 Technical Reference - Payment, Receipt and Reconciliation Controls

39 Technical Reference - Allocation, Scoring and Concurrency

40 Nigerian Agency Rules Reference

41 Data Security, Privacy and Audit Requirements

42 Implementation Details Requiring Confirmation

43 Key Highlights

Was this article helpful?

Table of Contents

Article Info

Share

Need more help?