Servicing Overview

Embarc exposes a consistent set of servicing commands across the two loan engines. Each action below explains what it does, when to use it, and whether it applies to Fixed Schedule or Dynamic Schedule (promotion/BNPL) loans

Action	Endpoint / Command	Money Moves?	Description	Fixed	Dynamic
Repayment / Prepay payoff	Payments API → POST /v1/loans/{loanId}/payments/initiate	✅ borrower → lender	Collects a scheduled or payoff amount. The loan balance updates after settlement because `PaymentSettlementLoanTransactionListener` posts the repayment.	✅	✅
Foreclosure payoff	POST /v1/loans/{loanId}/transactions?command=foreclosure	✅ borrower → lender	Calculates a forced payoff, records the foreclosure transaction, and moves status to Foreclosed after funds arrive.	✅	✅
Record external payment	Payments API → POST /v1/loans/{loanId}/payments/record	✅ borrower → lender	Mirrors a payment collected outside Embarc (e.g., cash desk, lockbox) and applies the repayment allocation strategy.	✅	✅
Close (zero balance)	POST /v1/loans/{loanId}?command=close	❌	Marks a zero-balance loan as Closed after prior refunds or repayments have cleared it.	✅	✅
Undo approval	POST /v1/loans/{loanId}?command=undoApproval	❌	Rolls an Approved loan back to Submitted so terms can be edited before re-approval.	✅	✅
Charge-off	POST /v1/loans/{loanId}/transactions?command=charge-off	❌ (GL loss booking only)	Sets status to Charged-off, freezes accruals per `chargeOffBehaviour`, and posts loss entries by component.	✅	✅
Write-off	POST /v1/loans/{loanId}/transactions?command=writeoff	❌ (GL write-off only)	Clears receivables and moves the loan to Closed – Written-off. Future recoveries use `recoverypayment`.	✅	✅
Payout reversal	POST /v1/loans/{loanId}/transactions?command=payoutRefund (after Payments API payout)	✅ borrower → lender	Claws back lender-funded disbursements (ACH/RTGS). May auto-create an interest refund.	✅	✅
Merchant credit	POST /v1/loans/{loanId}/transactions?command=merchantIssuedRefund (after merchant reimburses)	✅ merchant → lender	Merchant-funded credit that reduces the schedule without moving lender cash; eligible for automatic interest refunds.	✅	✅
Excess payment refund	POST /v1/loans/{loanId}/transactions?command=refundByCash (after Payments API refund)	✅ lender → borrower	Returns amounts the borrower paid in advance while the loan remains Active (amount ≤ paid-in-advance balance).	✅	✅
Credit balance refund	POST /v1/loans/{loanId}/transactions?command=creditBalanceRefund (after Payments API refund)	✅ lender → borrower	Sends back surplus payments when the loan is Overpaid and flips status back to Active.	✅	✅
Charge refund	POST /v1/loans/{loanId}/transactions?command=chargeRefund (after Payments API refund)	✅ lender → borrower	Returns cash already collected for a fee or penalty; updates the linked charge history.	✅	✅
Goodwill credit	POST /v1/loans/{loanId}/transactions?command=goodwillCredit (after Payments API payout if cash-funded)	✅ lender → borrower (when cash-funded)	Institution-funded credit that behaves like a repayment so delinquency and allocation follow standard rules.	✅	✅
Interest refund	POST /v1/loans/{loanId}/transactions/{refundId}?command=interest-refund (or auto via refund)	✅ lender → borrower	Reverses previously accrued interest tied to payout reversals or merchant credits; can be automatic or manual.	✅	✅
Waive interest	POST /v1/loans/{loanId}/transactions?command=waiveinterest	❌	Removes unpaid accrued interest up to the waiver date while leaving principal intact.	✅	✅
Promo interest credit	POST /v1/loans/{loanId}/transactions?command=interestPaymentWaiver	❌	Dynamic-only synthetic repayment that follows the Promo / Payment Waiver allocation row (interest-first).	❌	✅
Interest pause	POST /v1/loans/{loanId}/interest-pauses	❌	Adds a term variation that halts interest accrual for a defined date window (dynamic installment, interest-bearing, IR-enabled loans only).	❌	✅
Re-age	POST /v1/loans/{loanId}/transactions?command=reAge	❌	Appends hardship installments for non-interest Dynamic loans after maturity, redistributing outstanding principal.	❌	✅
Re-amortize	POST /v1/loans/{loanId}/transactions?command=reAmortize	❌	Redistributes remaining principal across future installments on non-interest Dynamic loans before maturity.	❌	✅
Reschedule workflow	POST /v1/rescheduleloans → GET ...?command=previewLoanReschedule → POST ...?command=approve	❌	Rewrites the loan schedule. Fixed loans can combine grace, extra-term, EMI, or rate changes; Dynamic loans must choose either `adjustedDueDate` or `newInterestRate`.	✅	✅
Contract termination	POST /v1/loans/{loanId}/transactions?command=contractTermination	❌	Dynamic BNPL action that accelerates remaining amounts, tags the loan as Contract Termination, and awaits downstream payoff/refund/charge-off.	❌	✅
Buy-down fee	Payments API → `paymentCommand=buyDownFee` + POST /v1/loans/{loanId}/transactions?command=buyDownFee	✅ merchant → lender	Logs a merchant-funded subsidy and places it in the buy-down amortization pipeline (`LoanBuyDownFeeAmortizationProcessingService`).	❌	✅
Capitalized income	POST /v1/loans/{loanId}/transactions?command=capitalizedIncome	❌ (cash received earlier)	Moves earned-but-deferred revenue into a liability that `LoanCapitalizedIncomeAmortizationProcessingService` recognizes over time.	❌	✅
Down payment capture	Auto via `enableDownPayment` at disbursement or POST /v1/loans/{loanId}/transactions?command=downPayment	✅ borrower → lender	Collects the borrower’s upfront contribution for Dynamic loans; marks the down payment period as paid.	❌	✅
Recovery payment	POST /v1/loans/{loanId}/transactions?command=recoverypayment	✅ borrower / debt buyer → lender	Logs cash collected after charge-off or write-off while keeping the loan closed; credits recovery income accounts.	✅	✅
Charge adjustment	POST /v1/loans/{loanId}/charges/{chargeId}?command=adjustment	❌	Reduces the amount of a posted charge without moving cash; creates a CHARGE_ADJUSTMENT transaction.	✅	✅
Chargeback	POST /v1/loans/{loanId}/transactions/{transactionId}?command=chargeback	✅ lender → borrower/processor	Reinstates part or all of a prior repayment when the processor claws funds back (card/ACH dispute). Reopens principal on the business date; blocked on Fixed loans that have interest recalculation enabled	⚠️ (only when IR is off)	✅
Promise to Pay	POST /v1/loans/{loanId}/promises-to-pay	❌	Creates and tracks a payment promise with its own schedule and standing; evaluation marks installments due/missed, and plans close as completed/defaulted or cancel with a reason. Does not change the loan’s amortization.	✅	✅
Bankruptcy management	POST /v1/clients/{clientId}/bankruptcies	❌	Records client bankruptcy cases (chapter, petition, stay, claims/objections); enabling stay cancels autopay and blocks new enrollment; active check gates downstream workflows	✅	✅

How to choose the right action

Payments & refunds – Use the Payments API for all money-moving operations (repayments, payoffs, refunds, subsidies).
Early payoff / closure – Use prepay, foreclosure, or close for voluntary or forced settlements.
Hardship & restructuring – Use interest pause, re-age, re-amortize, or reschedule for delinquency relief (Dynamic-only where marked).
Loss recognition – Use charge-off when keeping the account for recoveries; use write-off for final closure.
Promos & BNPL – Use contract termination, buy-down fee, and capitalized income for BNPL and merchant-funded programs.
Non-cash adjustments – Use goodwill credit, waive interest, or promo interest credits where you need concessions without moving cash.

Servicing tips

Check the engine – Confirm if the loan is Fixed or Dynamic before using Dynamic-only actions.
Enforce permissions – Each action has its own permission + audit trail; ensure roles are correctly scoped.
Use undo carefully – Undo actions are only allowed while the original command is the latest transaction.