ApplicationTrustAccounting — Debtor Module User Manual

Audience: Collections clerks, attorneys, finance staff, and compliance officers
Version: 1.0 — June 2026
Jurisdiction: South Africa (National Credit Act / in duplum rule compliance)

Table of Contents

1. Introduction
2. Getting Started
3. Key Concepts
   • Debtor Account Statuses
   • The Ledger Buckets
   • The In Duplum Rule
4. Navigating the Debtor Module
   • Debtor Explorer
   • Debtor Dashboard
   • Recovery Dashboard
5. Ledger Operations
   • Viewing the Debtor Ledger
   • Recording a Trust Receipt as a Debtor Payment
   • Allocating Payments
   • Allocating Suspense
   • Accruing Interest
   • Exporting the Ledger
6. Collections — Payment Plans
   • Creating a Payment Plan
   • Recording an Instalment Payment
   • Marking a Plan as Defaulted
   • Settlement Quotes
7. Enforcement
   • Recording a Judgment
   • Issuing a Writ
   • Recording a Writ Return
   • Writing Off a Debt
8. Age Analysis
9. Compliance Rules
10. Operational Checklist
11. Troubleshooting

1. Introduction

The Debtor Module manages the collection of outstanding debts for law firm matters. It tracks all amounts owed to the firm or on behalf of clients, maintains a detailed per-debtor ledger, enforces South African debt-collection law (including the in duplum rule), and supports the full lifecycle from initial debt registration through payment plan, judgment, enforcement, and eventual settlement or write-off.

2. Getting Started

Accessing the Debtor Module

The Debtor Module is accessible via the Debtors menu in the main menu bar. Your role determines which sub-menus and actions are visible to you.

Main Menu Structure

Selecting a Debtor Account

Most actions in the Debtor Module operate on the currently selected debtor account. To select one:

1. Open Debtor Explorer (Debtors → Debtor Explorer).
2. Use the search bar to find the account by debtor name, reference number, matter, or ID number.
3. Click the account row to select it. The selected account becomes the active context for all subsequent menu actions.

If you attempt a menu action without first selecting an account, the system will display a warning asking you to select one.

3. Key Concepts

3.1 Debtor Account Statuses

Every debtor account moves through a defined lifecycle. The current status controls which operations are available.

3.2 The Ledger Buckets

The debtor ledger tracks amounts across seven separate buckets. Each transaction posts to one or more buckets depending on its type.

When a payment is received, the system allocates it across the buckets according to a configurable allocation order (typically: costs → interest → capital → commission → VAT → disbursements).

3.3 The In Duplum Rule

The in duplum rule is a South African legal rule codified in the National Credit Act. It states:

Interest that has accrued and is owed (but unpaid) may never exceed the outstanding capital at the time credit was first extended.

Example:
Original capital: R 10,000
In duplum cap: R 10,000
If unpaid interest reaches R 10,000, the system automatically stops accruing further interest until a payment reduces the interest balance below the cap.

After a judgment, the in duplum cap resets to the judgment capital amount, allowing fresh interest accrual on the judgment sum. The system handles this reset automatically when a judgment is recorded.

The system records every cap event in an audit log (the debtor_in_duplum_events table) so that compliance can be demonstrated to the court or regulator.

4. Navigating the Debtor Module

4.1 Debtor Explorer

Open via Debtors → Debtor Explorer.

The Explorer lists all debtor accounts with key summary columns:

Searching and Filtering:

• Type in the search bar to filter by name, reference, or matter number.
• Use the Status filter to show only accounts in a specific status (e.g., show only ACTIVE accounts).
• Double-click a row to open the debtor account workspace.

4.2 Debtor Dashboard

Open via Debtors → Debtor Dashboard.

The Dashboard provides a firm-wide view of the debtor book:

4.3 Recovery Dashboard

Open via Debtors → Recovery Dashboard.

The Recovery Dashboard focuses on active collections:

• Accounts currently on payment plans (with plan health indicators)
• Accounts in arrears and the number of missed instalments
• Accounts with active writs (enforcement actions)
• Accounts that are overdue for a follow-up action

This view is intended for collections supervisors to track the health of the collections portfolio at a glance.

5. Ledger Operations

5.1 Viewing the Debtor Ledger

Open via Debtors → Ledger → Debtor Ledger, or by opening the debtor account workspace from the Explorer.

The ledger displays every transaction for the selected debtor account in chronological order. Each row shows:

Reversed entries are shown in a strikethrough style. Both the original and the reversal entry remain visible in the ledger for a complete audit trail.

5.2 Recording a Trust Receipt as a Debtor Payment

Open via Debtors → Ledger → Record Trust Receipt as Debtor.

Use this when a client's trust receipt in the financial module should also be applied as a payment against the debtor account — typically when a debtor pays funds into the firm's trust account and those funds are to be applied to the debt.

Steps:

1. Select the debtor account in the Debtor Explorer.
2. Go to Debtors → Ledger → Record Trust Receipt as Debtor.
3. The dialog will show the most recent unallocated trust receipt for the linked matter.
4. Confirm the amount, date, and reference.
5. Click Confirm.

What the system does:

• Posts a credit entry in the debtor ledger (reducing the outstanding balance)
• Links the debtor ledger entry to the trust ledger entry for a complete cross-module audit trail
• Triggers the standard payment allocation logic (see Section 5.3)

5.3 Allocating Payments

Open via Debtors → Ledger → Allocation.

Payment allocation applies a payment (credit) to the outstanding balances across the seven buckets according to the configured allocation order.

The default allocation order is:

1. Costs
2. Interest
3. Capital
4. Commission
5. VAT
6. Disbursements
7. Suspense (if any remainder)

Steps:

1. Select the debtor account.
2. Go to Debtors → Ledger → Allocation.
3. The allocation screen shows:
   • Current balance per bucket
   • The payment amount available for allocation
   • The proposed allocation across buckets (pre-calculated)
4. Review the proposed allocation.
5. Click Allocate to confirm.

What the system does:

• Posts a credit to each applicable bucket in the correct order
• Any excess over the total outstanding is posted to the Suspense bucket for manual review

Failure conditions:

5.4 Allocating Suspense

Open via Debtors → Ledger → Allocate Suspense.

Suspense funds are payments that were received but could not be immediately allocated (for example, a payment that exceeded the total outstanding, or a payment received before the account was fully set up).

Steps:

1. Select the debtor account.
2. Go to Debtors → Ledger → Allocate Suspense.
3. The dialog shows the total amount currently held in suspense.
4. Review the proposed re-allocation (the system will apply the standard allocation order to the suspense amount).
5. Click Allocate Suspense to confirm.

What the system does:

• Moves the suspense balance into the applicable buckets in order
• Records the allocation with a full audit trail linking back to the original suspense entry

Note: If no unallocated suspense balance exists, the action will display a message and take no action.

5.5 Accruing Interest

Open via Debtors → Ledger → Accrue Interest.

Interest accrual is typically run automatically by the system's nightly batch task for all eligible accounts. The manual accrual option allows you to trigger accrual for a specific account outside of the batch schedule — for example, to bring an account up to date before generating a settlement quote.

Eligibility for interest accrual:

• Account must be in status ACTIVE, PAYMENT_PLAN, or JUDGMENT
• Account must have an active interest rate configuration attached
• The in duplum cap must not have been reached (if it has, accrual is blocked automatically)

Steps:

1. Select the debtor account.
2. Go to Debtors → Ledger → Accrue Interest.
3. The dialog shows:
   • The current capital balance (interest is calculated on capital only)
   • The annual interest rate and day-count convention (ACT/365 or ACT/360)
   • The calculated interest amount for the accrual period
   • The in duplum cap status
4. Confirm the accrual date and click Accrue.

What the system does:

• Calculates daily interest: Capital × Annual Rate × Days ÷ Day Count
• Applies the in duplum cap — if the calculated interest would exceed the remaining capacity under the cap, it is reduced to the remaining capacity
• Posts an INTEREST_ACCRUAL entry to the Interest bucket of the debtor ledger
• Records a cap event if the cap is reached
• Uses an idempotency key (INTEREST_ACCRUAL:{accountId}:{date}) to prevent duplicate accruals on the same date

Failure conditions:

5.6 Exporting the Ledger

Open via Debtors → Ledger → Export Ledger.

Exports the selected debtor account's full ledger to a spreadsheet or PDF. Useful for providing a statement of account to the debtor or their attorney, or for attaching to court papers.

Steps:

1. Select the debtor account.
2. Go to Debtors → Ledger → Export Ledger.
3. Select the export format (Excel / PDF) and date range.
4. Click Export.

The exported file includes all ledger entries with running balances, the debtor reference, and the export date.

6. Collections — Payment Plans

6.1 Creating a Payment Plan

Open via Debtors → Collections → Create Payment Plan.

A payment plan is a formal instalment arrangement with the debtor. Only one active payment plan can exist for a debtor account at a time.

Pre-conditions:

• The account must be in ACTIVE or DEFAULTED status
• The total outstanding balance must be greater than zero

Steps:

1. Select the debtor account.
2. Go to Debtors → Collections → Create Payment Plan.
3. Complete the plan details:
   • Start Date — the date of the first instalment (must be in an open accounting period)
   • Instalment Amount — the agreed monthly payment
   • Frequency — Monthly (default), Weekly, or Bi-weekly
   • Number of Instalments — calculated automatically from the balance and instalment amount, or enter manually
   • Notes / Reason — a brief description of the arrangement (e.g., "Debtor approached requesting payment arrangement")
4. Click Create Plan.

What the system does:

• Creates the payment plan record with status ACTIVE
• Transitions the debtor account status from ACTIVE → PAYMENT_PLAN
• Generates the instalment schedule (one record per expected instalment)
• Logs the plan creation in the audit trail

Accounting note: No ledger entries are created when a plan is set up. Entries are created only when actual instalment payments are received.

6.2 Recording an Instalment Payment

Open via Debtors → Collections → Payment Plan (the Payment Plan workspace).

When the debtor pays an instalment, record it here to update the plan and the ledger simultaneously.

Steps:

1. Select the debtor account.
2. Open the Payment Plan workspace (Debtors → Collections → Payment Plan).
3. The workspace shows the instalment schedule with status for each instalment (PENDING, PAID, MISSED).
4. Click on the instalment to pay, or use Record Instalment Payment.
5. Enter:
   • Amount Paid — actual amount received (may differ from the scheduled instalment)
   • Payment Date
   • Reference — EFT reference or receipt number
6. Click Confirm.

What the system does:

• Posts a credit entry to the debtor ledger via the standard allocation logic
• Marks the instalment as PAID (or PARTIAL if the amount is less than due)
• If the amount paid exceeds the instalment due, the excess is allocated to the next instalment or posted to suspense
• Updates the plan status:
  • All instalments current → ACTIVE
  • One or more missed → IN_ARREARS
• Sends a targeted refresh notification to any open debtor workspace views

6.3 Marking a Plan as Defaulted

Open via Debtors → Collections → Mark Plan Defaulted.

Use this when the debtor has failed to meet the terms of the payment plan and you need to formally default the arrangement (for example, before proceeding to judgment).

Steps:

1. Select the debtor account (must have an ACTIVE or IN_ARREARS payment plan).
2. Go to Debtors → Collections → Mark Plan Defaulted.
3. The system looks up the active plan automatically.
4. Enter a reason for the default (this is recorded on the plan and on the debtor account).
5. Confirm the action.

What the system does:

• Changes the payment plan status to DEFAULTED
• Changes the debtor account status to DEFAULTED
• Records the reason and the user who actioned the default

Failure conditions:

6.4 Settlement Quotes

Open via Debtors → Collections → Settlement Quote.

A settlement quote gives the debtor a fixed amount they can pay to fully settle the debt, valid for a specified period (typically 7 or 14 days).

Steps:

1. Select the debtor account.
2. Go to Debtors → Collections → Settlement Quote.
3. The workspace shows:
   • Current outstanding balance per bucket
   • Any applicable discount or concession (attorney discretion)
   • Accrued interest to the proposed settlement date
4. Enter:
   • Quote Date — date the quote is calculated to
   • Valid Until Date — expiry date of the quote
   • Discount Amount (if any is being offered)
5. Click Generate Quote.

The system calculates the settlement amount including all accrued interest to the quote date. The quote is saved and can be printed or exported.

Accepting a settlement: If the debtor pays the quoted amount before the expiry date, record the payment via the standard allocation process. Then mark the account as SETTLED manually once the balance is confirmed as zero.

7. Enforcement

7.1 Recording a Judgment

Open via Debtors → Enforcement → Record Judgment.

Once a court has issued judgment in favour of the firm (or client), the judgment details must be recorded against the debtor account.

Steps:

1. Select the debtor account.
2. Go to Debtors → Enforcement → Record Judgment.
3. Enter the judgment details:
   • Court — the court that issued the judgment
   • Case Number — the court case reference
   • Judgment Date — the date judgment was granted
   • Judgment Capital Amount — the capital amount as per the judgment order
   • Judgment Costs Amount — costs awarded by the court
   • Notes — any additional details from the judgment order
4. Click Record Judgment.

What the system does:

• Records the judgment details against the debtor account
• Transitions the account status to JUDGMENT
• Resets the in duplum cap to the judgment capital amount, allowing fresh interest accrual on the judgment sum (as required under South African case law following judgment)
• Records the cap reset in the in duplum audit log

Important: Only record a judgment once a formal court order has been obtained. This action changes the in duplum cap and has accounting implications.

7.2 Issuing a Writ

Open via Debtors → Enforcement → Judgment (the Judgment workspace).

A writ of execution is the court document that authorises the sheriff to enforce the judgment (e.g., attach and sell the debtor's assets).

Steps:

1. Select the debtor account (must be in JUDGMENT status).
2. Open the Judgment workspace.
3. Click Issue Writ.
4. Enter:
   • Writ Number — the number assigned by the court
   • Issue Date — the date the writ was issued
   • Sheriff — the sheriff's office assigned to enforce the writ
   • Notes (optional)
5. Click Confirm.

What the system does:

• Records the writ details against the judgment record
• Updates the judgment status to WRIT_ISSUED
• Both the writ issuance and any subsequent updates are wrapped in a database transaction — if any part fails, the entire update is rolled back

7.3 Recording a Writ Return

When the sheriff returns the writ (either with funds recovered or with a nulla bona return — no assets found), record the outcome here.

Steps:

1. Open the Judgment workspace for the relevant account.
2. Click Record Writ Return.
3. Enter:
   • Return Date — the date the writ was returned
   • Return Type — SATISFIED (funds recovered), PARTIAL (partially satisfied), or NULLA_BONA (no assets)
   • Amount Recovered (if any)
   • Notes — sheriff's report reference or remarks
4. Click Confirm.

What the system does:

• Records the return outcome against the writ record
• If funds were recovered, triggers a payment allocation against the debtor ledger
• Updates the judgment and writ status accordingly

7.4 Writing Off a Debt

Open via Debtors → Enforcement → Write Off Debt.

A write-off is used when the debt is deemed irrecoverable (for example, after a nulla bona return, or when the debtor is deceased or insolvent with no assets). Writing off removes the debt from the active book.

This action is irreversible. The written-off balance will be credited in full across all ledger buckets, reducing the outstanding to zero.

Steps:

1. Select the debtor account.
2. Go to Debtors → Enforcement → Write Off Debt.
3. A confirmation dialog will appear showing:
   • The debtor reference and name
   • The total outstanding balance per bucket that will be written off
4. Enter a reason for the write-off (required for audit purposes).
5. Confirm the action.

What the system does:

• Loads the live balance across all seven buckets
• Posts a credit entry to each bucket for the full outstanding amount, reducing all balances to zero
• Uses an idempotency key (WRITE_OFF:{accountId}) to prevent duplicate write-offs
• Changes the debtor account status to WRITTEN_OFF
• Records the reason and the acting user

Accounting impact:

Failure conditions:

8. Age Analysis

The age analysis breaks down the debtor's outstanding balance into time buckets based on how long each amount has been owed. Each ledger entry is aged individually by its own entry date — recent charges appear in the current bucket even if older charges exist on the same account.

Viewing the age analysis:

The age analysis is displayed in the Debtor Dashboard (for the whole book) and in the individual account workspace (for a single debtor). It is calculated as of today's date by default; you can change the As-At Date to produce a historical view.

Note: Credits and over-payments (negative net amounts per entry date) are excluded from the age analysis — they do not represent aged debt.

9. Compliance Rules

Rule 1: The In Duplum Rule

Interest that has accrued and remains unpaid may never exceed the outstanding capital at the time the credit was first extended. The system enforces this automatically:

• Before each interest accrual, the system calculates the remaining capacity under the cap
• If the calculated interest would exceed the remaining capacity, it is reduced to the remaining capacity
• If the cap has already been reached, no interest is accrued and a cap event is logged
• After judgment, the cap resets to the judgment capital amount

Violation: Any attempt to accrue interest beyond the cap is silently prevented by the system. No user action is required.

Rule 2: No Negative Debtor Balances

Payments that exceed the outstanding balance are placed in the Suspense bucket rather than allowed to create a negative balance. Suspense must be resolved via the Allocate Suspense function (Section 5.4).

Rule 3: All Transactions Require an Authenticated User

Every ledger entry, plan creation, judgment, and write-off records the user who actioned it. If no user session is active, the operation is blocked. This ensures a complete, tamper-proof audit trail for every action.

Rule 4: Transactions Cannot Be Posted to Closed Accounting Periods

All debtor ledger entries must fall within an open accounting period. If the entry date falls in a closed or non-existent period, the posting is rejected.

Rule 5: Only One Active Payment Plan Per Account

A debtor account may only have one payment plan in ACTIVE or IN_ARREARS status at a time. If you attempt to create a second plan while one is still active, the system will require you to default or close the existing plan first.

Rule 6: Write-offs Are Irreversible

Once a debt is written off, the account status moves to WRITTEN_OFF and the ledger entries reducing all buckets to zero are permanent. A write-off can only be reversed by a manual ledger reversal authorised by a finance administrator.

Rule 7: Interest Does Not Accrue After Certain Status Changes

Interest accrual is blocked for accounts in SUSPENDED, WRITTEN_OFF, or SETTLED status. The nightly batch task automatically skips these accounts.

10. Operational Checklist

Use this checklist when working debtor accounts day to day:

1. Select the correct debtor account in the Explorer.
2. Confirm the account status before posting.
3. Record charges, receipts, or interest in the correct ledger bucket.
4. Allocate receipts before sending a statement or settlement quote.
5. Review age analysis before escalation or write-off.
6. Keep payment plans, judgments, and enforcement actions in the right lifecycle stage.
7. Check for overdue follow-ups and unresolved suspense balances.

Following the checklist keeps the ledger, recovery, and dashboard views aligned.

11. Troubleshooting

"Please select a debtor account first"

Cause: You triggered a Debtors menu action without first selecting an account in the Debtor Explorer.
Resolution: Open the Debtor Explorer (Debtors → Debtor Explorer), click the relevant account to select it, and then retry the action.

"No active payment plan found for this debtor account"

Cause: You attempted to mark a plan as defaulted, but the account has no plan in ACTIVE or IN_ARREARS status.
Resolution: Check the payment plan history in the Payment Plan workspace. The plan may already be in DEFAULTED status, or may not have been created yet.

"In duplum cap reached — no interest accrued"

Cause: The account's accumulated unpaid interest has reached the in duplum cap. No further interest can accrue until payments reduce the interest balance below the cap.
Resolution: No action is required from the user — the cap is being correctly enforced. Advise the debtor that additional interest is not accruing and encourage payment to release the cap. After a judgment is recorded, the cap resets to the judgment capital.

"Interest accrual failed — no active interest config"

Cause: The debtor account has no interest rate configuration attached.
Resolution: Contact your system administrator. An interest configuration (annual rate, day-count convention, and in duplum cap) must be attached to the account before accrual can proceed.

"Cannot write off: insufficient permissions"

Cause: Your user role does not include the CAN_WRITE_OFF_DEBTOR permission.
Resolution: Contact your system administrator to request the appropriate role or permission override.

The ledger balance does not match the settlement quote

Cause: Interest may have accrued between the date the quote was generated and today, or a payment may have been allocated after the quote was generated.
Resolution:

1. Re-generate the settlement quote using today's date to get a current figure.
2. Confirm that no payments were received after the original quote date that have not yet been allocated.
3. Run the age analysis to confirm the outstanding breakdown is as expected.

A ledger entry was posted in error

Posted debtor ledger entries cannot be deleted. To correct an error:

1. Contact your finance administrator.
2. The administrator will initiate a reversal of the incorrect entry via the Debtor Ledger → Reverse action (if available for your role).
3. The reversal creates a contra entry that exactly offsets the original, and both entries remain visible in the ledger for audit purposes.
4. After the reversal, re-post the correct entry.

Nightly interest accrual did not run

Cause: The nightly batch task may have been skipped due to:

• The system user (ID = 1) not existing in the users table
• No DSLContext available (database connection issue at the time the task ran)
• All accounts being at the in duplum cap (no interest to accrue)

Resolution:

1. Check the application server log for entries from DailyInterestAccrualTask at the time the task should have run.
2. Verify that a system/service user with ID = 1 exists in the database.
3. If the task reported failures for specific accounts, check those accounts individually for configuration issues.
4. Use Debtors → Ledger → Accrue Interest to manually trigger accrual for any accounts that were missed.

End of Debtor Module User Manual

Disclaimer: This manual reflects the behaviour of the ApplicationTrustAccounting Debtor Module as implemented. Compliance requirements described herein are based on South African National Credit Act regulations and in duplum rule case law as understood at the time of writing. Always consult a qualified attorney or compliance professional for authoritative legal guidance.