apache · airajena · Jan 19, 2026
diff --git a/...va/org/apache/fineract/infrastructure/configuration/api/GlobalConfigurationConstants.java b/...va/org/apache/fineract/infrastructure/configuration/api/GlobalConfigurationConstants.java
@@ -80,6 +80,7 @@ public final class GlobalConfigurationConstants {
     public static final String ALLOWED_LOAN_STATUSES_FOR_EXTERNAL_ASSET_TRANSFER = "allowed-loan-statuses-for-external-asset-transfer";
     public static final String ALLOWED_LOAN_STATUSES_OF_DELAYED_SETTLEMENT_FOR_EXTERNAL_ASSET_TRANSFER = "allowed-loan-statuses-of-delayed-settlement-for-external-asset-transfer";
     public static final String ENABLE_ORIGINATOR_CREATION_DURING_LOAN_APPLICATION = "enable-originator-creation-during-loan-application";
+    public static final String BLOCK_TRANSACTIONS_ON_CLOSED_OVERPAID_LOANS = "block-transactions-on-closed-overpaid-loans";
 
     private GlobalConfigurationConstants() {}
 }
diff --git a/...a/org/apache/fineract/infrastructure/configuration/domain/ConfigurationDomainService.java b/...a/org/apache/fineract/infrastructure/configuration/domain/ConfigurationDomainService.java
@@ -151,4 +151,6 @@ public interface ConfigurationDomainService {
     boolean isImmediateChargeAccrualPostMaturityEnabled();
 
     String getAssetOwnerTransferOustandingInterestStrategy();
+
+    boolean isBlockTransactionsOnClosedOverpaidLoansEnabled();
 }
diff --git a/...ava/org/apache/fineract/portfolio/loanaccount/serialization/LoanTransactionValidator.java b/...ava/org/apache/fineract/portfolio/loanaccount/serialization/LoanTransactionValidator.java
@@ -98,4 +98,6 @@ void validateRefund(Loan loan, LoanTransactionType loanTransactionType, LocalDat
     void validateManualInterestRefundTransaction(String json);
 
     void validateClassificationCodeValue(String codeName, Long transactionClassificationId, DataValidatorBuilder baseDataValidator);
+
+    void validateLoanNotClosedOrOverpaidForTransactions(Loan loan);
 }
diff --git a/...pache/fineract/portfolio/loanaccount/service/ProgressiveLoanTransactionValidatorImpl.java b/...pache/fineract/portfolio/loanaccount/service/ProgressiveLoanTransactionValidatorImpl.java
@@ -506,6 +506,11 @@ public void validateLoanGroupIsActive(Loan loan) {
         loanTransactionValidator.validateLoanGroupIsActive(loan);
     }
 
+    @Override
+    public void validateLoanNotClosedOrOverpaidForTransactions(Loan loan) {
+        loanTransactionValidator.validateLoanNotClosedOrOverpaidForTransactions(loan);
+    }
+
     @Override
     public void validateActivityNotBeforeLastTransactionDate(Loan loan, LocalDate activityDate, LoanEvent event) {
         loanTransactionValidator.validateActivityNotBeforeLastTransactionDate(loan, activityDate, event);

diff --git a/...rg/apache/fineract/infrastructure/configuration/domain/ConfigurationDomainServiceJpa.java b/...rg/apache/fineract/infrastructure/configuration/domain/ConfigurationDomainServiceJpa.java
@@ -548,4 +548,9 @@ public String getAssetOwnerTransferOustandingInterestStrategy() {
         return getGlobalConfigurationPropertyData(
                 GlobalConfigurationConstants.ASSET_OWNER_TRANSFER_OUTSTANDING_INTEREST_CALCULATION_STRATEGY).getStringValue();
     }
+
+    @Override
+    public boolean isBlockTransactionsOnClosedOverpaidLoansEnabled() {
+        return getGlobalConfigurationPropertyData(GlobalConfigurationConstants.BLOCK_TRANSACTIONS_ON_CLOSED_OVERPAID_LOANS).isEnabled();
+    }
 }
diff --git a/...org/apache/fineract/portfolio/loanaccount/serialization/LoanTransactionValidatorImpl.java b/...org/apache/fineract/portfolio/loanaccount/serialization/LoanTransactionValidatorImpl.java
@@ -37,6 +37,7 @@
 import org.apache.commons.lang3.StringUtils;
 import org.apache.fineract.infrastructure.codes.domain.CodeValue;
 import org.apache.fineract.infrastructure.codes.domain.CodeValueRepository;
+import org.apache.fineract.infrastructure.configuration.domain.ConfigurationDomainService;
 import org.apache.fineract.infrastructure.core.api.JsonCommand;
 import org.apache.fineract.infrastructure.core.data.ApiParameterError;
 import org.apache.fineract.infrastructure.core.data.DataValidatorBuilder;
@@ -111,6 +112,7 @@ public class LoanTransactionValidatorImpl implements LoanTransactionValidator {
     private final LoanDownPaymentTransactionValidator loanDownPaymentTransactionValidator;
     private final LoanDisbursementValidator loanDisbursementValidator;
     private final CodeValueRepository codeValueRepository;
+    private final ConfigurationDomainService configurationDomainService;
 
     private void throwExceptionIfValidationWarningsExist(final List<ApiParameterError> dataValidationErrors) {
         if (!dataValidationErrors.isEmpty()) {
@@ -666,6 +668,14 @@ public void validateLoanGroupIsActive(final Loan loan) {
         }
     }
 
+    public void validateLoanNotClosedOrOverpaidForTransactions(Loan loan) {
+        boolean blockTransactions = configurationDomainService.isBlockTransactionsOnClosedOverpaidLoansEnabled();
+        if (blockTransactions && (loan.isClosed() || loan.getStatus().isOverpaid())) {
+            throw new GeneralPlatformDomainRuleException("error.msg.loan.transaction.not.allowed.on.closed.or.overpaid",
+                    "Monetary transactions are not allowed on closed or overpaid loan accounts", loan.getId());
+        }
+    }
+
     protected void validateLoanHasNoLaterChargeRefundTransactionToReverseOrCreateATransaction(Loan loan, LocalDate transactionDate,
             String reversedOrCreated) {
         for (LoanTransaction txn : loan.getLoanTransactions()) {

diff --git a/...che/fineract/portfolio/loanaccount/service/LoanWritePlatformServiceJpaRepositoryImpl.java b/...che/fineract/portfolio/loanaccount/service/LoanWritePlatformServiceJpaRepositoryImpl.java
@@ -1095,6 +1095,7 @@ public CommandProcessingResult makeLoanRepaymentWithChargeRefundChargeType(final
             changes.put(LoanApiConstants.externalIdParameterName, txnExternalId);
         }
         Loan loan = this.loanAssembler.assembleFrom(loanId);
+        this.loanTransactionValidator.validateLoanNotClosedOrOverpaidForTransactions(loan);
         final PaymentDetail paymentDetail = this.paymentDetailWritePlatformService.createAndPersistPaymentDetail(command, changes);
         final Boolean isHolidayValidationDone = false;
         final HolidayDetailDTO holidayDetailDto = null;

diff --git a/fineract-provider/src/main/resources/db/changelog/tenant/changelog-tenant.xml b/fineract-provider/src/main/resources/db/changelog/tenant/changelog-tenant.xml
@@ -227,4 +227,5 @@
     <include file="parts/0206_transaction_summary_with_asset_owner_classification_name_bug_fix.xml" relativeToChangelogFile="true" />
     <include file="parts/0207_add_allow_full_term_for_tranche.xml" relativeToChangelogFile="true" />
     <include file="parts/0208_trial_balance_summary_with_asset_owner_journal_entry_aggregation_fix.xml" relativeToChangelogFile="true" />
+    <include file="parts/0209_add_configuration_block_transactions_on_closed_overpaid_loans.xml" relativeToChangelogFile="true" />
 </databaseChangeLog>
diff --git a/...gelog/tenant/parts/0209_add_configuration_block_transactions_on_closed_overpaid_loans.xml b/...gelog/tenant/parts/0209_add_configuration_block_transactions_on_closed_overpaid_loans.xml
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    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.
+
+-->
+<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
+                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.3.xsd">
+
+    <changeSet author="fineract" id="2">
+        <insert tableName="c_configuration">
+            <column name="name" value="block-transactions-on-closed-overpaid-loans"/>
+            <column name="value"/>
+            <column name="date_value"/>
+            <column name="string_value"/>
+            <column name="enabled" valueBoolean="false"/>
+            <column name="is_trap_door" valueBoolean="false"/>
+            <column name="description" value="If enabled: monetary transactions are blocked on closed and overpaid loan accounts"/>
+        </insert>
+    </changeSet>
+</databaseChangeLog>
diff --git a/...java/org/apache/fineract/integrationtests/BlockTransactionsOnClosedOverpaidLoansTest.java b/...java/org/apache/fineract/integrationtests/BlockTransactionsOnClosedOverpaidLoansTest.java
@@ -0,0 +1,174 @@
+/**
+ * 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.integrationtests;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+import io.restassured.builder.RequestSpecBuilder;
+import io.restassured.builder.ResponseSpecBuilder;
+import io.restassured.http.ContentType;
+import io.restassured.specification.RequestSpecification;
+import io.restassured.specification.ResponseSpecification;
+import java.util.ArrayList;
+import java.util.HashMap;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.fineract.integrationtests.common.ClientHelper;
+import org.apache.fineract.integrationtests.common.CommonConstants;
+import org.apache.fineract.integrationtests.common.GlobalConfigurationHelper;
+import org.apache.fineract.integrationtests.common.Utils;
+import org.apache.fineract.integrationtests.common.accounting.AccountHelper;
+import org.apache.fineract.integrationtests.common.loans.LoanApplicationTestBuilder;
+import org.apache.fineract.integrationtests.common.loans.LoanProductTestBuilder;
+import org.apache.fineract.integrationtests.common.loans.LoanStatusChecker;
+import org.apache.fineract.integrationtests.common.loans.LoanTestLifecycleExtension;
+import org.apache.fineract.integrationtests.common.loans.LoanTransactionHelper;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+
+@ExtendWith(LoanTestLifecycleExtension.class)
+@Slf4j
+public class BlockTransactionsOnClosedOverpaidLoansTest {
+
+    private ResponseSpecification responseSpec;
+    private RequestSpecification requestSpec;
+    private LoanTransactionHelper loanTransactionHelper;
+    private LoanTransactionHelper loanTransactionHelperForError;
+    private GlobalConfigurationHelper globalConfigurationHelper;
+    private AccountHelper accountHelper;
+    private ResponseSpecification responseSpecForError;
+
+    @BeforeEach
+    public void setup() {
+        Utils.initializeRESTAssured();
+        this.requestSpec = new RequestSpecBuilder().setContentType(ContentType.JSON).build();
+        this.requestSpec.header("Authorization", "Basic " + Utils.loginIntoServerAndGetBase64EncodedAuthenticationKey());
+        this.responseSpec = new ResponseSpecBuilder().expectStatusCode(200).build();
+        this.responseSpecForError = new ResponseSpecBuilder().expectStatusCode(403).build();
+        this.loanTransactionHelper = new LoanTransactionHelper(this.requestSpec, this.responseSpec);
+        this.loanTransactionHelperForError = new LoanTransactionHelper(this.requestSpec, this.responseSpecForError);
+        this.globalConfigurationHelper = new GlobalConfigurationHelper();
+        this.accountHelper = new AccountHelper(this.requestSpec, this.responseSpec);
+    }
+
+    @AfterEach
+    public void tearDown() {
+        this.globalConfigurationHelper.manageConfigurations("block-transactions-on-closed-overpaid-loans", false);
+    }
+
+    @Test
+    public void testTransactionsOnOverpaidLoan() {
+        this.globalConfigurationHelper.manageConfigurations("block-transactions-on-closed-overpaid-loans", true);
+
+        final Integer clientID = ClientHelper.createClient(this.requestSpec, this.responseSpec);
+        ClientHelper.verifyClientCreatedOnServer(this.requestSpec, this.responseSpec, clientID);
+
+        final Integer loanProductID = createLoanProduct();
+        final Integer loanID = applyForLoanApplication(clientID, loanProductID, "1000", "01 January 2024");
+
+        this.loanTransactionHelper.approveLoan("01 January 2024", loanID);
+        this.loanTransactionHelper.disburseLoanWithNetDisbursalAmount("01 January 2024", loanID, "1000");
+
+        this.loanTransactionHelper.makeRepayment("01 February 2024", 2000.0f, loanID);
+
+        HashMap loanStatusHashMap = (HashMap) this.loanTransactionHelper.getLoanDetail(this.requestSpec, this.responseSpec, loanID,
+                "status");
+        LoanStatusChecker.verifyLoanAccountIsOverPaid(loanStatusHashMap);
+
+        ArrayList<HashMap> repaymentErrors = (ArrayList<HashMap>) this.loanTransactionHelperForError.makeRepaymentTypePayment("repayment",
+                "02 February 2024", 10.0f, loanID, CommonConstants.RESPONSE_ERROR);
+        Assertions.assertEquals("error.msg.loan.transaction.not.allowed.on.closed.or.overpaid",
+                repaymentErrors.get(0).get(CommonConstants.RESPONSE_ERROR_MESSAGE_CODE));
+
+        Float totalOverpaid = (Float) this.loanTransactionHelper.getLoanDetail(this.requestSpec, this.responseSpec, loanID,
+                "totalOverpaid");
+        assertNotNull(totalOverpaid);
+        Assertions.assertTrue(totalOverpaid > 0);
+
+        this.loanTransactionHelper.creditBalanceRefund("03 February 2024", totalOverpaid, null, loanID, "");
+
+        loanStatusHashMap = (HashMap) this.loanTransactionHelper.getLoanDetail(this.requestSpec, this.responseSpec, loanID, "status");
+        LoanStatusChecker.verifyLoanAccountIsClosed(loanStatusHashMap);
+    }
+
+    @Test
+    public void testTransactionsOnClosedLoan() {
+        this.globalConfigurationHelper.manageConfigurations("block-transactions-on-closed-overpaid-loans", true);
+
+        final Integer clientID = ClientHelper.createClient(this.requestSpec, this.responseSpec);
+        final Integer loanProductID = createLoanProduct();
+        final Integer loanID = applyForLoanApplication(clientID, loanProductID, "1000", "01 January 2024");
+
+        this.loanTransactionHelper.approveLoan("01 January 2024", loanID);
+        this.loanTransactionHelper.disburseLoanWithNetDisbursalAmount("01 January 2024", loanID, "1000");
+
+        HashMap loanSummary = this.loanTransactionHelper.getLoanSummary(this.requestSpec, this.responseSpec, loanID);
+        Float totalOutstanding = (Float) loanSummary.get("totalOutstanding");
+        this.loanTransactionHelper.makeRepayment("01 February 2024", totalOutstanding, loanID);
+
+        HashMap loanStatusHashMap = (HashMap) this.loanTransactionHelper.getLoanDetail(this.requestSpec, this.responseSpec, loanID,
+                "status");
+        LoanStatusChecker.verifyLoanAccountIsClosed(loanStatusHashMap);
+
+        ArrayList<HashMap> repaymentErrors = (ArrayList<HashMap>) this.loanTransactionHelperForError.makeRepaymentTypePayment("repayment",
+                "02 February 2024", 10.0f, loanID, CommonConstants.RESPONSE_ERROR);
+        Assertions.assertEquals("error.msg.loan.transaction.not.allowed.on.closed.or.overpaid",
+                repaymentErrors.get(0).get(CommonConstants.RESPONSE_ERROR_MESSAGE_CODE));
+
+        this.globalConfigurationHelper.manageConfigurations("block-transactions-on-closed-overpaid-loans", false);
+        this.loanTransactionHelper.makeRepayment("03 February 2024", 10.0f, loanID);
+    }
+
+    private Integer createLoanProduct() {
+        final String principal = "1000.00";
+        LoanProductTestBuilder loanProductTestBuilder = new LoanProductTestBuilder() //
+                .withPrincipal(principal) //
+                .withShortName(Utils.uniqueRandomStringGenerator("", 4)) //
+                .withNumberOfRepayments("4") //
+                .withRepaymentAfterEvery("1") //
+                .withRepaymentTypeAsMonth() //
+                .withinterestRatePerPeriod("1") //
+                .withInterestRateFrequencyTypeAsMonths() //
+                .withAmortizationTypeAsEqualInstallments() //
+                .withInterestTypeAsDecliningBalance();
+
+        final String loanProductJSON = loanProductTestBuilder.build(null);
+        return this.loanTransactionHelper.getLoanProductId(loanProductJSON);
+    }
+
+    private Integer applyForLoanApplication(final Integer clientID, final Integer loanProductID, String principal, String submitDate) {
+        final String loanApplicationJSON = new LoanApplicationTestBuilder() //
+                .withPrincipal(principal) //
+                .withLoanTermFrequency("4") //
+                .withLoanTermFrequencyAsMonths() //
+                .withNumberOfRepayments("4") //
+                .withRepaymentEveryAfter("1") //
+                .withRepaymentFrequencyTypeAsMonths() //
+                .withInterestRatePerPeriod("1") //
+                .withAmortizationTypeAsEqualInstallments() //
+                .withInterestTypeAsDecliningBalance() //
+                .withInterestCalculationPeriodTypeSameAsRepaymentPeriod() //
+                .withExpectedDisbursementDate(submitDate) //
+                .withSubmittedOnDate(submitDate) //
+                .build(clientID.toString(), loanProductID.toString(), null);
+        return this.loanTransactionHelper.getLoanId(loanApplicationJSON);
+    }
+}
diff --git a/.../src/test/java/org/apache/fineract/integrationtests/common/GlobalConfigurationHelper.java b/.../src/test/java/org/apache/fineract/integrationtests/common/GlobalConfigurationHelper.java
@@ -557,6 +557,13 @@ private static ArrayList<HashMap> getAllDefaultGlobalConfigurations() {
         enableImmediateChargeAccrualPostMaturity.put("trapDoor", false);
         defaults.add(enableImmediateChargeAccrualPostMaturity);
 
+        HashMap<String, Object> blockTransactionsOnClosedOverpaidLoans = new HashMap<>();
+        blockTransactionsOnClosedOverpaidLoans.put("name", GlobalConfigurationConstants.BLOCK_TRANSACTIONS_ON_CLOSED_OVERPAID_LOANS);
+        blockTransactionsOnClosedOverpaidLoans.put("value", 0L);
+        blockTransactionsOnClosedOverpaidLoans.put("enabled", false);
+        blockTransactionsOnClosedOverpaidLoans.put("trapDoor", false);
+        defaults.add(blockTransactionsOnClosedOverpaidLoans);
+
         HashMap<String, Object> assetOwnerTransferInterestOutstandingStrategy = new HashMap<>();
         assetOwnerTransferInterestOutstandingStrategy.put("name",
                 GlobalConfigurationConstants.ASSET_OWNER_TRANSFER_OUTSTANDING_INTEREST_CALCULATION_STRATEGY);