TPS loan balance reductions

Finance → Collections → case → Request balance reduction · Approvals inbox

A loan balance reduction pays a TPS buyer's account credit off their loan principal, as their signed Lump Sum Payment Authority Form asks. The balance drops and the buyer pays less interest. A different person must approve it before anything changes, and once approved it cannot be undone from the app.

The officer who requests a reduction and the manager who approves it see the same explanation on screen, so this page uses the same words.

The four steps

1. An officer requests it and attaches the signed form

   From the buyer's collections case, the officer chooses Request balance reduction, enters the amount for each loan exactly as the signed form states it, and chooses Preview. The preview is the server's own calculation (the same one that runs on approval), showing per loan the balance, instalment, term and last due date before and after, the interest saved, and the credit left afterwards. The officer attaches the signed form and chooses Send for approval. Nothing on the loan changes yet.

2. A different person approves or rejects it

   The request arrives in the approvals inbox. The approver opens the signed form, checks the figures against it, and approves or rejects. The person who requested it can never approve it. Above your organisation's threshold, a second approval is needed, and it must come from yet another person: "This amount needs two approvers, neither of them you."

3. The system applies it

   On approval it is applied at once: for each loan a principal prepayment invoice is raised and paid from the account credit. Both names (who requested and who approved), the signed form and the figures are kept on the record.

4. The schedule is reshaped

   The remaining instalments are rebuilt from the lower balance, from the next unbilled instalment, using the organisation's policy (below). The buyer's statement shows the new balance immediately.

Why it takes two people

A reduction permanently changes what a buyer owes, so no single person can make one, and every one is backed by the buyer's signature. The platform enforces this three ways, not by convention:

• The person who requested a reduction can never approve it, whatever the approval policy says about self-approval.
• On a two-level request, the person who approved the first level cannot approve the second: two levels means two different approvers.
• The database itself refuses a record whose approver is its requester.

How the loan is reshaped: the policy

A reduction lowers the principal. What happens to the rest of the loan depends on the policy:

Either way the buyer pays less interest. The organisation's default is Shorten the term (tps.prepayment.policy). By default the officer cannot change it per request (tps.prepayment.officer_may_choose_policy is off), and the request form shows the policy with "set by your organisation". Where the organisation allows a choice, the officer picks it under How to reshape the loan, and changing it discards the preview, so the figures sent for approval are always the figures the officer saw.

Before you request (officer)

You need:

• The buyer's signed Lump Sum Payment Authority Form (PDF, JPEG or PNG, up to 10 MB). A request cannot be sent without it.
• Credit already on the account. A reduction uses only existing account credit. If the buyer has just paid, record that payment first; it becomes credit.
• The date on the signed form, and optionally the form reference and a note to the approver.

Enter the amounts exactly as the form states them, loan by loan (house principal and furniture principal are separate loans).

Rules the request must meet

If a preview has problems, the form says "This reduction cannot be submitted yet" and lists them; nothing is sent.

Before you approve (approver)

Open the signed form with Open the signed form and check:

• it is this buyer's form, and it is signed;
• each amount matches the amount on the form, loan by loan;
• the date on the form is the one recorded on the request.

If anything differs, reject it with the reason; the officer submits a corrected request. Approving cannot be undone from the app.

When approval is refused

The approver approves exactly what the officer saw. On approval the platform plans the reduction again and refuses if the result has moved:

A new payment arriving while the request waits does not by itself invalidate it.

Statuses

"Approved, but not applied yet" and "Apply it now"

Approving and applying are two separate moments. Rarely, the approval is recorded but the reduction is interrupted before it runs (for example by a restart). The request then shows "Approved, but not applied yet": the approval was recorded, nothing on the loan has changed. Apply it now runs it exactly as approved, as the person who approved it.

If applying it failed, the request shows "Approved, but not applied" with the reason, and Retry applying it. Nothing was half-applied that a retry cannot finish.

Either way, a retry is safe: a reduction can only ever be applied once. A retry is offered to an approver, never to the officer who requested it.

The switch: tps.surplus.prepayment_enabled

One setting decides whether a TPS buyer's money may be put against their loan principal at all. It is set per organisation, can be overridden per branch, and is labelled "Allow TPS overpayments to be applied to loan principal" in Settings → TPS. It is off by default.

It is one switch because both of those do the same thing (turn a buyer's money into principal reduction), so an organisation agrees to principal prepayments once and both follow that answer.

Turning it on applies nothing by itself. Every reduction is still requested with a signed form and approved by someone else.

What officers see while it is off

The request form still opens, so the officer can see the explanation, but it is disabled and says:

Balance reductions are switched off for this property. Applying a buyer's credit to loan principal changes what they owe, so it stays off until the organisation has agreed a prepayment process. An administrator can turn it on in Settings → TPS → "Allow TPS overpayments to be applied to loan principal" (tps.surplus.prepayment_enabled). Until then a buyer's credit can only be held against their future instalments.

Turn it on only once your organisation has agreed its prepayment process: who may request, who may approve, the default policy and any second-approval threshold.

Settings

Every default is the no-change value.

Permissions

Requesting and approving are separate permissions, so a person can hold one without the other, and approvers do not need to be administrators.

To make someone an approver, put them in a role that holds tps.balance_reductions.approve and approvals.decide (needed to use the approvals inbox). That is ordinary role configuration; see Roles & permissions. Holding the approve permission never lets anyone approve their own request.

What else to know

• The buyer is not notified automatically. Tell the buyer once a reduction is applied; their statement shows the new balance at once.
• Allocation reports for the housing programme read the financed amount less principal paid, so they reflect the reduction from the next report. See Boma Yangu reports.
• An applied reduction cannot be undone from the app. That is why the approver checks the form before approving, not after.

Common problems