Merge pull request #5785

FINERACT-2455: WC - Transaction Type - CBR

Author: adamsaghy

fineract-core/src/main/java/org/apache/fineract/commands/service/CommandWrapperBuilder.java

@@ -881,6 +881,14 @@ public CommandWrapperBuilder repaymentWorkingCapitalLoanTransaction(final Long l
         return this;
     }
 
+    public CommandWrapperBuilder creditBalanceRefundWorkingCapitalLoanTransaction(final Long loanId) {
+        this.actionName = ACTION_CREDITBALANCEREFUND;
+        this.entityName = ENTITY_WORKINGCAPITALLOAN;
+        this.entityId = loanId;
+        this.href = "/working-capital-loans/" + loanId + "/transactions?command=creditBalanceRefund";
+        return this;
+    }
+
     public CommandWrapperBuilder createClientIdentifier(final Long clientId) {
         this.actionName = ACTION_CREATE;
         this.entityName = ENTITY_CLIENTIDENTIFIER;

fineract-doc/src/docs/en/chapters/features/index.adoc

@@ -17,3 +17,4 @@ include::re-ageing.adoc[leveloffset=+1]
 include::delayed-schedule-captures.adoc[leveloffset=+1]
 include::loan-origination-details.adoc[leveloffset=+1]
 include::working-capital-amortization-schedule.adoc[leveloffset=+1]
+include::working-capital-credit-balance-refund.adoc[leveloffset=+1]

fineract-doc/src/docs/en/chapters/features/working-capital-credit-balance-refund.adoc

@@ -0,0 +1,28 @@
+= Working Capital Loan — Credit Balance Refund (CBR)
+
+== Overview
+
+Credit Balance Refund (CBR) is supported for Working Capital loans when a loan has an overpayment balance.
+
+== Core Behavior
+
+For Working Capital loans:
+
+* Overpayment is tracked in `m_wc_loan_balance.overpayment_amount`
+* `principal_outstanding` is not reduced below zero; excess repayment is tracked as overpayment
+* CBR reduces `overpayment_amount` by the refund amount
+
+== Validation
+
+CBR is allowed only when:
+
+* Loan status is `OVERPAID`
+* `overpayment_amount > 0`
+* Refund amount is positive and does not exceed current `overpayment_amount`
+
+== Status Handling
+
+After CBR:
+
+* If `overpayment_amount > 0`, the loan remains `OVERPAID`
+* If `overpayment_amount = 0` and `principal_outstanding = 0`, status transitions to `CLOSED_OBLIGATIONS_MET`

fineract-e2e-tests-core/build.gradle

@@ -71,6 +71,7 @@ dependencies {
     testImplementation 'io.github.openfeign:feign-core:13.6'
     testImplementation 'org.apache.httpcomponents:httpclient:4.5.14'
     testImplementation 'org.apache.commons:commons-lang3:3.18.0'
+    testImplementation 'com.google.guava:guava'
     testImplementation ('com.googlecode.json-simple:json-simple:1.1.1') {
         exclude group: 'junit', module: 'junit'
     }

fineract-e2e-tests-core/src/test/java/org/apache/fineract/test/messaging/event/EventCheckHelper.java

@@ -83,6 +83,7 @@
 import org.apache.fineract.test.messaging.event.loan.transaction.LoanTransactionMerchantIssuedRefundPostEvent;
 import org.apache.fineract.test.messaging.event.loan.transaction.LoanTransactionPayoutRefundPostEvent;
 import org.apache.fineract.test.messaging.event.loan.transaction.LoanUndoContractTerminationBusinessEvent;
+import org.apache.fineract.test.messaging.event.workingcapitalloan.transaction.WorkingCapitalLoanCreditBalanceRefundTransactionBusinessEvent;
 import org.apache.fineract.test.messaging.event.workingcapitalloan.transaction.WorkingCapitalLoanDisbursalTransactionBusinessEvent;
 import org.apache.fineract.test.messaging.event.workingcapitalloan.transaction.WorkingCapitalLoanUndoDisbursalTransactionBusinessEvent;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -318,6 +319,27 @@ public void workingCapitalLoanDisbursalTransactionEventCheck(final Long loanId,
                 .extractingData(WorkingCapitalLoanTransactionDataV1::getReversed).isEqualTo(Boolean.FALSE);
     }
 
+    public void workingCapitalLoanCreditBalanceRefundTransactionEventCheck(final Long loanId, final BigDecimal expectedAmount) {
+        waitForTransactionCommit();
+        final GetWorkingCapitalLoansLoanIdResponse body = ok(
+                () -> fineractClient.workingCapitalLoans().retrieveWorkingCapitalLoanById(loanId));
+        if (body.getTransactions() == null || body.getTransactions().isEmpty()) {
+            throw new IllegalStateException("No Working Capital Loan transactions found");
+        }
+
+        final GetWorkingCapitalLoanTransactionIdResponse cbrTransaction = body.getTransactions().stream()
+                .filter(t -> t.getType() != null && "loanTransactionType.creditBalanceRefund".equals(t.getType().getCode())
+                        && !Boolean.TRUE.equals(t.getReversed()))
+                .reduce((first, second) -> second)
+                .orElseThrow(() -> new IllegalStateException("Credit balance refund transaction not found"));
+
+        eventAssertion.assertEvent(WorkingCapitalLoanCreditBalanceRefundTransactionBusinessEvent.class, cbrTransaction.getId())//
+                .extractingData(WorkingCapitalLoanTransactionDataV1::getWcLoanId).isEqualTo(loanId)//
+                .extractingBigDecimal(WorkingCapitalLoanTransactionDataV1::getTransactionAmount)
+                .isEqualTo(expectedAmount == null ? cbrTransaction.getTransactionAmount() : expectedAmount)//
+                .extractingData(WorkingCapitalLoanTransactionDataV1::getReversed).isEqualTo(Boolean.FALSE);
+    }
+
     public void workingCapitalLoanUndoDisbursalTransactionEventCheck(final Long loanId) {
         workingCapitalLoanUndoDisbursalTransactionEventCheck(loanId, null);
     }

fineract-e2e-tests-core/src/test/java/org/apache/fineract/test/messaging/event/workingcapitalloan/transaction/WorkingCapitalLoanCreditBalanceRefundTransactionBusinessEvent.java

@@ -0,0 +1,27 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.test.messaging.event.workingcapitalloan.transaction;
+
+public class WorkingCapitalLoanCreditBalanceRefundTransactionBusinessEvent extends AbstractWorkingCapitalLoanTransactionEvent {
+
+    @Override
+    public String getEventName() {
+        return "WorkingCapitalLoanCreditBalanceRefundTransactionBusinessEvent";
+    }
+}