# Recovery sales and client surplus

Run `php yii migrate` after pulling this update. Keep `common/uploads/recovery-proofs` and `common/uploads/custody-proofs` writable by PHP and outside public web roots. Download endpoints check branch access. Evidence supports PDF, JPG and PNG up to 10 MB.

## Sale stages

From a loan, select **Request collateral sale**, or use the recovery sale register in the collateral module. The item must be physically held, pledged to that loan, and free of another open sale or custody action. Capture the buyer, gross proceeds, selling costs, recovery reason and authority/agreement evidence. Costs cannot exceed gross proceeds; zero net proceeds are supported without negative allocations. A different CEO approves the immutable terms. Below-appraisal pricing and early recovery require an explicit CEO decision reason, highlighted on the review screen.

After approval, record the actual gross collection, date, channel, unique reference, and proof covering payment and selling costs. The amount must match approved gross proceeds. Changed buyer/price/costs require rejection and a fresh sale request. The CEO verifies the proceeds separately; a preparer cannot verify their own capture. Resolve pending repayments first. Collections are posted in effective-date order, using the loan balance at the sale payment date.

Verified net proceeds apply to interest, fees and principal according to the loan's original allocation order. Allocation never exceeds debt or net proceeds. The remainder becomes client surplus. A remaining shortfall keeps the loan active; nothing silently writes it off. Late fees continue under the original cap while principal/interest remain owed, and freeze at their clearance date. Gross sale cash, selling costs, debt recovery and client surplus stay separately identifiable.

Payment verification authorises buyer collection but does not claim a physical handover occurred. Source staff then capture actual buyer collection with date, the approved buyer's name, a unique custody reference and signed acknowledgement. Only this event marks the item **sold**. The original intake and all evidence stay available.

Open sales reserve collateral against intake edits, new pledges, transfers/releases and replacement loans. Loan repayments may continue; full settlement before sale verification makes the sale ineligible and requires rejection. Posted recoveries block historical repayment reversals and replacement loans until a reviewed recovery-correction workflow exists. Regular payments can clear retained shortfalls. A rejected evidence record remains in the register; rejecting it does not reverse an actual bank transaction or assert money was refunded. Sale corrections, buyer refunds and recovery reversals require a subsequent supported workflow.

## Surplus returns

The verified sale page shows client surplus, verified returns and outstanding surplus. Record the actual client payment with recipient, date, channel, reference, reason and proof/client acknowledgement. Pending returns reserve their amount. A separate CEO verifies or rejects the record. Verification reduces the payable and creates exactly one linked `surplus_expense` entry in **Client sale surplus return**. This dedicated register is separate from operating expenses and does not add another loan repayment or duplicate cash.

Returns cannot exceed unreserved surplus or precede sale collection. Duplicate references and repeat decisions are blocked. Unverified/rejected returns do not reduce the payable. This module does not automatically pay a bank account, import production data or provide statutory accounting entries.

## Checks

Database scenarios exercise full/partial recovery, loan balance/date reconciliation, fee cutoff, immutable pricing, permissions, self-approval, pending repayments, custody separation, duplicate posting, surplus reservation and expense linking. HTTP smoke submits sale authority, payment, buyer handover and client-return proofs through multipart forms and verifies the CEO transitions.