Waive Repayment Installment

Overview

WaiveRepaymentScheduleInstallmentCommand marks a specific loan repayment installment as Waived. Use this when a borrower has settled an installment through an external channel (cash, bank transfer, mobile money, etc.) and the system's automated NIBSS debit should not be attempted for that installment.

Note: Waiving an installment sets amountPaid = 0 and records the action in the loan's approval history with the reason supplied. It does not cancel any existing NIBSS mandate — mandate management is handled separately.

Command Details

• Command: WaiveRepaymentScheduleInstallmentCommand
• Type: Command (write operation)
• Authorization: Admin role required

API Endpoint

POST /api/bpm/cmd

Request Structure

Field	Type	Required	Description
loanRequestId	long	Yes	ID of the loan quote (LoanQuote.Id)
installmentNumber	int	Yes	1-based installment number to waive
reason	string	Yes	Reason for waiving (e.g. "Client paid by cash on 2025-09-10")

Try It Out

POST/api/bpm/cmdWaiveRepaymentScheduleInstallmentCommand

Base URL

Bearer Token

Request Body

{ "cmd": "WaiveRepaymentScheduleInstallmentCommand", "data": { "loanRequestId": 1001, "installmentNumber": 3, "reason": "Borrower paid via bank transfer on 2025-11-10 — reference TRF20251110-98765" } }

Response Structure

{
  "response": {
    "isSuccessful": true,
    "statusCode": "00",
    "message": "Installment 3 has been waived successfully.",
    "data": {
      "loanQuoteId": 1001,
      "installmentNumber": 3,
      "dueDate": "2025-11-15T00:00:00Z",
      "waivedAmount": 46666.67,
      "waivedBy": 42,
      "reason": "Borrower paid via bank transfer on 2025-11-10 — reference TRF20251110-98765"
    }
  },
  "responseCode": "00",
  "responseDescription": "Success"
}

Validation Rules

Rule	Error Code	Message
Loan not found	04	"Loan request not found."
Installment not found	04	"Installment {installmentNumber} not found for this loan."
Installment already paid	09	"Installment {installmentNumber} has already been paid and cannot be waived."
Installment already waived	09	"Installment {installmentNumber} has already been waived."

Audit Trail

Every waiver is recorded in the loan's approval history (LoanApprovalHistory) with:

Field	Value
Action	"Installment Waived"
ActionDescription	Full description including installment number, due date, amount, and reason
Comment	The reason string supplied in the request
ActionDate	UTC timestamp of the waiver
ApproverId	ID of the authenticated officer who performed the waiver

What "Waived" Means

Aspect	Behaviour
status	Set to Waived
paidDate	Set to the UTC timestamp of the waiver action
amountPaid	Set to 0 (waived, not collected)
Installment counts towards totalAmountPaid	No — amountPaid is 0
Included in outstandingAmount calculation	No — excluded from outstanding balance
NIBSS mandate cancelled	No — mandate management is separate

Related Commands

• Get Repayment Schedule — Confirm the installment was waived
• Set Collection Details — Regenerate the schedule (this clears all waivers)