Dispute Resolution
Overview
The Dispute Resolution module manages the full lifecycle of disputes raised by rate payers, agents, or web submissions. It supports dispute categories and titles, dependencies between disputes, claim requests for compensation, and web requests submitted through the public portal. Disputes flow through a resolution workflow with status tracking and messaging.
Navigate to: Sidebar → Dispute Resolution
Dispute Categories
Navigate to: /disputeresolution/category
Manage the categories under which disputes can be filed.
| Element | Description |
|---|---|
| Search bar | Search categories by name |
| Add Category button | Create a new dispute category |
| Category card | Shows category name, description, and active dispute count |
Category Card
| Field | Description |
|---|---|
| Category Name | e.g. "Billing Dispute", "Property Record Issue", "Payment Dispute" |
| Description | What this category covers |
| Active Disputes | Number of open disputes in this category |
| Status | Active or Inactive |
Add / Edit Category
| Field | Required | Description |
|---|---|---|
| Category Name | Yes | Unique name for the category |
| Description | Yes | What disputes in this category cover |
| Status | Yes | Active or Inactive |
!!! tip "Things to check" - Category names are unique - Active categories appear in the dispute filing form - Inactive categories are hidden from the filing form - Active dispute count is accurate
Dispute Titles
Navigate to: /disputeresolution/disputetitle
Manage specific dispute titles within categories.
| Element | Description |
|---|---|
| Search bar | Search titles by name or category |
| Add Title button | Create a new dispute title |
| Title card | Shows title name, parent category, and status |
Title Card
| Field | Description |
|---|---|
| Title Name | e.g. "Incorrect Bill Amount", "Duplicate Payment" |
| Category | Parent dispute category |
| Description | What this title covers |
| Status | Active or Inactive |
Add / Edit Title
| Field | Required | Description |
|---|---|---|
| Title Name | Yes | Unique name for the title |
| Category | Yes | Parent category from the dropdown |
| Description | Yes | What disputes with this title cover |
| Status | Yes | Active or Inactive |
!!! tip "Things to check" - Title names are unique within their category - Category dropdown shows only active categories - Active titles appear in the dispute filing form - Titles correctly link back to their parent category
Dispute Dependencies
Navigate to: /disputeresolution/dependency
Manage dependencies between disputes — when one dispute is related to or blocked by another.
| Element | Description |
|---|---|
| Search bar | Search dependencies by dispute or related dispute |
| Add Dependency button | Create a new dependency link |
| Dependency card | Shows the linked disputes and dependency type |
Dependency Card
| Field | Description |
|---|---|
| Primary Dispute | The dispute that depends on another |
| Related Dispute | The dispute that is a dependency |
| Dependency Type | Blocked By, Related To, Superseded By |
| Status | Active or Resolved |
Add / Edit Dependency
| Field | Required | Description |
|---|---|---|
| Primary Dispute | Yes | Search and select the primary dispute |
| Related Dispute | Yes | Search and select the related dispute |
| Dependency Type | Yes | Blocked By, Related To, or Superseded By |
| Notes | No | Explanation of the dependency |
!!! tip "Things to check"
- A dispute cannot depend on itself
- Circular dependencies are prevented
- Blocked By dependencies prevent resolution of the primary dispute
- Related To dependencies are informational only
- Superseded By marks the primary dispute as superseded
Dispute List
Navigate to: /disputeresolution/dispute
| Element | Description |
|---|---|
| Search bar | Search disputes by ID, title, rate payer, or category |
| Filter tabs | Filter by status (All, Pending, In Review, Resolved, Rejected) |
| Add Dispute button | File a new dispute |
| Dispute card | Shows dispute details and status |
Dispute Card
| Field | Description |
|---|---|
| Dispute ID | System-generated unique identifier (e.g. #DSP-2026-100000002) |
| Title | Dispute title |
| Category | Dispute category |
| Status badge | Pending, In Review, Resolved, or Rejected |
| Priority | Low, Medium, High, Critical |
| Filed By | Name of the person who filed the dispute |
| Rate Payer | Associated rate payer |
| Property | Associated property (if applicable) |
| Date Filed | When the dispute was filed |
Filter Tabs
| Tab | Shows |
|---|---|
| All | All disputes regardless of status |
| Pending | Disputes awaiting initial review |
| In Review | Disputes currently being investigated |
| Resolved | Disputes that have been resolved |
| Rejected | Disputes that were rejected |
!!! tip "Things to check" - Filter tabs correctly narrow the list by status - Search works across ID, title, rate payer, and category fields - Dispute cards show all required information - Status transitions are tracked in the audit log - Tapping a dispute card opens the dispute details
Add Dispute
Navigate to: Sidebar → Dispute Resolution → Add Dispute
Dispute Form
| Field | Required | Description |
|---|---|---|
| Rate Payer | Yes | Search and select the rate payer filing the dispute |
| Property | No | Select associated property (filtered by rate payer) |
| Dispute Category | Yes | Select from active categories |
| Dispute Title | Yes | Select from active titles (filtered by category) |
| Priority | Yes | Low, Medium, High, Critical |
| Description | Yes | Detailed description of the issue |
| Related Type | Yes | Property, Bill, Payment, Other |
| Related Record ID | Conditional | ID of the related bill, property, or payment |
| Contact Method | Yes | Email, Phone, WhatsApp |
| Contact Info | Yes | Email address, phone number, or WhatsApp number |
| Supporting Documents | No | Upload files (max 5, JPG/PNG/PDF, 10MB each) |
Dispute Filing Flow
Select Rate Payer → Select Property (optional)
↓
Select Category → Select Title (filtered by category)
↓
Set Priority → Enter Description
↓
Select Related Type → Enter Related Record ID (if applicable)
↓
Set Contact Method → Enter Contact Info
↓
Upload Supporting Documents (optional)
↓
SUBMIT
↓
Dispute Created (Pending) → Rate Payer Notified
!!! tip "Things to check"
- Rate Payer search returns matching results
- Property dropdown filters by the selected rate payer
- Dispute Title options filter by the selected Category
- Related Record ID is validated (must exist in the system)
- Required fields block submission when left blank
- Supporting document upload respects limits (5 files, 10MB, JPG/PNG/PDF)
- After submission, the dispute appears in the list with Pending status
Dispute Details
Navigate to: Sidebar → Dispute Resolution → Dispute List → View Details
Dispute Information
| Field | Description |
|---|---|
| Dispute ID | Unique identifier |
| Title | Dispute title |
| Category | Dispute category |
| Status | Current status |
| Priority | Assigned priority |
| Filed By | Who filed the dispute |
| Rate Payer | Associated rate payer |
| Related Type | Property, Bill, Payment, or Other |
| Related Record | ID of the related record |
| Date Filed | When the dispute was filed |
| Description | Full description of the issue |
Attachments
| Element | Description |
|---|---|
| File list | All uploaded supporting documents |
| Download | Download individual files |
| Preview | Preview images and PDFs |
| Add Attachment button | Upload additional documents |
Resolution Notes
| Element | Description |
|---|---|
| Notes timeline | Chronological list of resolution notes |
| Add Note | Add a new resolution note |
| Assignee | Current assignee responsible for resolution |
Actions
| Action | Description |
|---|---|
| Assign | Assign the dispute to a staff member for resolution |
| Update Status | Change the dispute status |
| Add Note | Add an internal resolution note |
| Resolve | Mark the dispute as resolved |
| Reject | Reject the dispute with a reason |
!!! tip "Things to check" - Dispute details match what was entered during filing - Status changes are reflected immediately - Resolution notes are timestamped and attributed - Assignee changes are logged in the audit trail - Resolve/Reject requires a reason or note - Rate payer is notified of status changes
Resolution List
Navigate to: /disputeresolution/resolution
| Element | Description |
|---|---|
| Search bar | Search resolved disputes |
| Filter options | Filter by resolution date, category, or MMDA |
| Resolution card | Shows resolved dispute summary |
Resolution Card
| Field | Description |
|---|---|
| Dispute ID | Original dispute identifier |
| Title | Dispute title |
| Category | Dispute category |
| Resolution | Resolution outcome |
| Resolved By | Staff member who resolved the dispute |
| Resolution Date | When the dispute was resolved |
| Rate Payer | Associated rate payer |
| Time to Resolve | Days from filing to resolution |
Claim Requests
Navigate to: /disputeresolution/claimrequests
Claims filed by rate payers for compensation or adjustment.
| Element | Description |
|---|---|
| Search bar | Search claims by ID, rate payer, or status |
| Filter tabs | Filter by status (All, Pending, Approved, Rejected) |
| Claim card | Shows claim details and status |
Claim Card
| Field | Description |
|---|---|
| Claim ID | Unique identifier |
| Rate Payer | Name of the claimant |
| Claim Type | Type of claim (refund, adjustment, compensation) |
| Amount Claimed | Claimed amount in GHS/GH₵ |
| Status badge | Pending, Approved, or Rejected |
| Date Filed | When the claim was filed |
Claim Request Details
Navigate to: /disputeresolution/claimrequests/:id
| Field | Description |
|---|---|
| Claim ID | Unique identifier |
| Rate Payer | Claimant information |
| Claim Type | Type of claim |
| Amount Claimed | Claimed amount (GHS/GH₵) |
| Reason | Reason for the claim |
| Supporting Documents | Uploaded evidence |
| Status | Current status |
| Resolution | Resolution outcome (if resolved) |
| Approved Amount | Amount approved (if approved) |
| Approved By | Staff member who approved |
Actions
| Action | Description |
|---|---|
| Approve | Approve the claim (full or partial amount) |
| Reject | Reject the claim with a reason |
| Request More Info | Request additional information from the claimant |
!!! tip "Things to check" - Claim amount is validated (positive value) - Approved amount cannot exceed claimed amount - Rejection requires a reason - Rate payer is notified of claim status changes - Approved claims trigger a payment or credit adjustment
Web Requests
Navigate to: /disputeresolution/webrequests
Disputes and requests submitted through the public web portal (Rate Payer App or website).
| Element | Description |
|---|---|
| Search bar | Search web requests by ID, name, or status |
| Filter tabs | Filter by status (All, Pending, In Review, Resolved) |
| Request card | Shows request details and status |
Request Card
| Field | Description |
|---|---|
| Request ID | Unique identifier |
| Requester Name | Name of the person who submitted |
| Request Type | Dispute, enquiry, complaint, etc. |
| Subject | Request subject |
| Status badge | Pending, In Review, or Resolved |
| Date Submitted | When the request was submitted |
Web Request Details
Navigate to: /disputeresolution/webrequests/:id
| Field | Description |
|---|---|
| Request ID | Unique identifier |
| Requester | Contact information |
| Request Type | Type of request |
| Subject | Request subject |
| Description | Full description |
| Attachments | Uploaded files |
| Status | Current status |
| Response | Admin response |
| Responded By | Staff member who responded |
| Response Date | When the response was sent |
Actions
| Action | Description |
|---|---|
| Respond | Send a response to the requester |
| Convert to Dispute | Convert the web request into a formal dispute |
| Resolve | Mark as resolved |
!!! tip "Things to check" - Web requests from the public portal appear here - Response is sent to the requester via their preferred contact method - Convert to Dispute correctly creates a new dispute with the request data - Requester is notified of responses and status changes - All web request data is preserved when converted to a dispute
Dispute Resolution Workflow
Dispute Filed (Pending)
↓
Admin Reviews (In Review)
↓
Investigation / Communication
↓ Resolve ↓ Reject
Resolved ✅ Rejected ❌
↓ ↓
Rate Payer Notified Rate Payer Notified
↓
Claim Request (if applicable)
↓ Approve ↓ Reject
Claim Approved ✅ Claim Rejected ❌
↓
Payment / Credit Adjustment
!!! tip "Things to check" - Full dispute lifecycle is trackable from filing to resolution - Status transitions are logged in the audit trail - Rate payers are notified at each status change - Resolution notes provide a complete communication history - Claim requests link back to the original dispute - Web requests can be converted to formal disputes - All actions are attributed to the staff member who performed them