Payments Workspace

Primary User Story

As a back-office or collections officer, I want a single place to capture and review loan payments and see how they are allocated between principal, profit and fees, so that I can reconcile customer payments quickly and answer questions about outstanding balances.

• Entry points: from the sidebar (`Payments`), from Loan Inquiry quick action “Pay now”, or from a reconciliation exception.
• Outcome: a payment is recorded with clear allocation and a complete audit trail.

Tabs & Functional Areas

• Process Payment: capture new loan repayments and automatically allocate them.
• Early Settlement: calculate payoff amount and process full settlement of the loan.
• Payment Allocation History: view detailed allocation rows for historical payments for a loan.
• Payment Allocation Analyzer: simulate “what-if” allocation scenarios, helpful for explaining to auditors or customers.
• Reconciliation: link back to bank files or external payment sources to reconcile unmatched items.

Process Payment – Standard Repayment

This flow is used when a customer has already made a payment through a bank channel (SADAD, SARIE, direct debit, etc.) and the officer is recording and allocating it in the LMS.

• Identify the loan: search by Loan ID, customer identifier or scan from inquiry context.
• Select due installments: choose one or more installments to be paid, including overdue ones if applicable.
• Enter payment reference: capture the bank payment reference number and channel; this is mandatory for reconciliation.
• Review allocation: system proposes allocation across principal, profit, fees and penalties according to product rules and regulatory constraints.
• Confirm & post: on confirmation, the system posts the payment, updates balances and writes an audit record.

If any business rule fails (e.g., payment amount less than minimum due, blocked account, write-off status), the system should show a clear error message and prevent posting.

Early Settlement – Full Payoff

Early Settlement is initiated when a customer wants to close the loan before maturity.

• User Story: as an operations officer, I want to calculate the final payoff amount including accrued profit, penalties, fees and rebates, so that I can settle the loan in one go.
• Inputs: loan identifier, effective settlement date, and any negotiated waivers or discounts.
• System behaviour: the engine calculates outstanding principal, accrued profit, unearned profit reversals and applicable penalties, then returns a single settlement amount.
• Outputs: settlement quote (valid for a specific window), detailed breakdown, and the accounting entries to be posted once the payment is confirmed.

Allocation History – Explaining Past Payments

Allocation History is primarily used for customer disputes and audit queries.

• Typical question: “Why did my outstanding balance not reduce by the full amount I paid?”
• View: grid showing each payment with columns for principal, profit, fees, VAT, penalties and residuals; filters by date range and payment channel.
• Drill-down: clicking a payment line shows the exact allocation logic and any waivers applied.
• Compliance: supports regulatory checks for correct allocation order (e.g., penalties before fees, then profit, then principal) as per product design.

Allocation Analyzer – “What-if” Scenarios

The Allocation Analyzer helps product, risk and finance teams understand how different payment amounts or timing would affect allocation and balances.

• Scenario inputs: hypothetical payment amount, payment date, number of installments and penalty/fee switches.
• Outputs: simulated allocation breakdown and projected balances without actually posting any transaction.
• Usage: used in production troubleshooting or during design workshops; also helpful for explaining product behaviour to regulators.

Reconciliation Use-Cases

• Unmatched bank items: reconciliation view highlights payments present in bank files but not in LMS; officers can search and match them to loans or flag them as suspense items.
• Duplicate payments: rules identify possible duplicates (same reference, amount, timestamp); officers decide whether to apply, reverse or refund.
• Partial and bulk payments: supports allocation of a single incoming amount across multiple loans or installments according to business rules.

Controls & Edge Cases

• Role-based access: only authorised users can post payments, process early settlements or adjust allocations; browse-only users can see history but not modify.
• Cut-off times: payment effective date may be auto-adjusted based on the processing cut-off and calendar rules (e.g., no backdating beyond a certain window).
• Error handling: for any failure in posting or external communication, the system must show clear guidance and avoid partial postings.
• Auditability: every payment capture, edit, reversal or settlement must be logged with user, timestamp and before/after values.