kyc exception at client creation time and some tds work

New ClerkShareWithdrawalRequestApiResource backs a clerk-submits/manager-
approves flow for share redemption: on submit, validates and persists the
clerk-chosen settlement Payment Type (must be non-cash) plus a full audit
snapshot of the settlement row; on approve, executes the real "redeemshares"
command and, in the same transaction, credits the redemption value to the
share account's linked savings account using that stored payment type (with
a hardcoded-lookup fallback for pre-existing rows). Adds a /validate endpoint
that re-checks live account/GL state (not just the submit-time snapshot) so
a manager can verify before approving. Also exposes linked-savings-account
data on ShareAccount reads so the frontend can display/validate it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

auth.json

@@ -0,0 +1 @@
+{"username":"mifos", "password":"password"}

fetch_accounts.js

@@ -0,0 +1,18 @@
+const https = require('https');
+const agent = new https.Agent({ rejectUnauthorized: false });
+
+fetch('https://localhost:8443/fineract-provider/api/v1/authentication?username=mifos&password=password&tenantIdentifier=default', {
+    method: 'POST',
+    agent: agent
+}).then(res => res.json()).then(data => {
+    const token = data.base64EncodedAuthenticationKey;
+    return fetch('https://localhost:8443/fineract-provider/api/v1/clients/9/accounts?tenantIdentifier=default', {
+        headers: {
+            'Authorization': 'Basic ' + token,
+            'Fineract-Platform-TenantId': 'default'
+        },
+        agent: agent
+    });
+}).then(res => res.json()).then(data => {
+    console.log(JSON.stringify(data, null, 2));
+}).catch(console.error);

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientKyc.java

@@ -241,6 +241,18 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @Column(name = "remarks", length = 500)
     private String remarks;
 
+    @Column(name = "is_exception", nullable = false)
+    private Boolean isException;
+
+    @Column(name = "exception_reason", length = 200)
+    private String exceptionReason;
+
+    @Column(name = "exception_resolved", nullable = false)
+    private Boolean exceptionResolved;
+
+    @Column(name = "exception_resolved_on")
+    private LocalDate exceptionResolvedOn;
+
     // ─────────────────────────────────────────────────────────────────────────
 
     protected ClientKyc() {}
@@ -261,6 +273,8 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         this.gstinVerified = false;
         this.cinVerified = false;
         this.dinVerified = false;
+        this.isException = false;
+        this.exceptionResolved = false;
         this.initiatedOn = DateUtils.getLocalDateOfTenant();
     }
 
@@ -325,6 +339,13 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
                 command.stringValueOfParameterNamed("form15Type"), null);
         this.form15Fy = StringUtils.defaultIfEmpty(
                 command.stringValueOfParameterNamed("form15FY"), null);
+        Boolean isExceptionVal = command.booleanObjectValueOfParameterNamed("isException");
+        this.isException = isExceptionVal != null ? isExceptionVal : false;
+        this.exceptionReason = StringUtils.defaultIfEmpty(
+                command.stringValueOfParameterNamed("exceptionReason"), null);
+        Boolean exceptionResolvedVal = command.booleanObjectValueOfParameterNamed("exceptionResolved");
+        this.exceptionResolved = exceptionResolvedVal != null ? exceptionResolvedVal : false;
+        this.exceptionResolvedOn = command.localDateValueOfParameterNamed("exceptionResolvedOn");
     }
 
     public Map<String, Object> update(final JsonCommand command) {
@@ -398,6 +419,13 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
                 v -> this.form15Applicable = v);
         updateStringField(command, "form15Type", this.form15Type, actualChanges, v -> this.form15Type = v);
         updateStringField(command, "form15FY", this.form15Fy, actualChanges, v -> this.form15Fy = v);
+        updateBooleanField(command, "isException", this.isException, actualChanges, v -> this.isException = v != null ? v : false);
+        updateStringField(command, "exceptionReason", this.exceptionReason, actualChanges, v -> this.exceptionReason = v);
+        updateBooleanField(command, "exceptionResolved", this.exceptionResolved, actualChanges, v -> this.exceptionResolved = v != null ? v : false);
+        updateDateField(command, "exceptionResolvedOn", this.exceptionResolvedOn, actualChanges, v -> this.exceptionResolvedOn = v);
+        updateBooleanField(command, "panVerified", this.panVerified, actualChanges, v -> this.panVerified = v != null ? v : false);
+        updateBooleanField(command, "aadhaarVerified", this.aadhaarVerified, actualChanges, v -> this.aadhaarVerified = v != null ? v : false);
+        updateBooleanField(command, "gstinVerified", this.gstinVerified, actualChanges, v -> this.gstinVerified = v != null ? v : false);
 
         return actualChanges;
     }
@@ -795,6 +823,38 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         return form15Fy;
     }
 
+    public Boolean getIsException() {
+        return isException;
+    }
+
+    public void setIsException(Boolean isException) {
+        this.isException = isException;
+    }
+
+    public String getExceptionReason() {
+        return exceptionReason;
+    }
+
+    public void setExceptionReason(String exceptionReason) {
+        this.exceptionReason = exceptionReason;
+    }
+
+    public Boolean getExceptionResolved() {
+        return exceptionResolved;
+    }
+
+    public void setExceptionResolved(Boolean exceptionResolved) {
+        this.exceptionResolved = exceptionResolved;
+    }
+
+    public LocalDate getExceptionResolvedOn() {
+        return exceptionResolvedOn;
+    }
+
+    public void setExceptionResolvedOn(LocalDate exceptionResolvedOn) {
+        this.exceptionResolvedOn = exceptionResolvedOn;
+    }
+
     @Column(name = "is_active", nullable = false)
     private Boolean isActive = Boolean.TRUE;
 

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientKycContactLog.java

@@ -0,0 +1,204 @@
+/**
+ * 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.portfolio.client.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.time.LocalDateTime;
+
+/**
+ * One customer-outreach attempt against an open KYC exception.
+ *
+ * <p>Append-only by design — there is no setter-driven update path and the API exposes no PUT or
+ * DELETE. A contact log that can be edited after the fact is worthless as evidence, and RBI's KYC
+ * Master Direction expects the bank to be able to show what it told the customer and when.
+ *
+ * <p>Destinations are stored masked ({@code destinationMasked}); the full mobile number / email
+ * lives on {@code m_client} and is resolved server-side at send time, never accepted from the
+ * browser.
+ */
+@Entity
+@Table(name = "m_client_kyc_contact_log")
+public class ClientKycContactLog {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @Column(name = "id")
+    private Long id;
+
+    @ManyToOne
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    /** The KYC record the exception belongs to. Nullable — outreach can precede a KYC row. */
+    @Column(name = "kyc_id")
+    private Long kycId;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "channel", length = 20, nullable = false)
+    private KycContactChannel channel;
+
+    @Column(name = "notes", length = 1000, nullable = false)
+    private String notes;
+
+    @Column(name = "officer_name", length = 200)
+    private String officerName;
+
+    @Column(name = "logged_by_user_id")
+    private Long loggedByUserId;
+
+    @Column(name = "exception_reason", length = 200)
+    private String exceptionReason;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "delivery_status", length = 30, nullable = false)
+    private KycContactDeliveryStatus deliveryStatus;
+
+    @Column(name = "destination_masked", length = 120)
+    private String destinationMasked;
+
+    @Column(name = "provider", length = 40)
+    private String provider;
+
+    @Column(name = "provider_reference", length = 120)
+    private String providerReference;
+
+    @Column(name = "failure_reason", length = 500)
+    private String failureReason;
+
+    @Column(name = "message_body", length = 2000)
+    private String messageBody;
+
+    @Column(name = "contacted_at", nullable = false)
+    private LocalDateTime contactedAt;
+
+    @Column(name = "created_at", nullable = false)
+    private LocalDateTime createdAt;
+
+    protected ClientKycContactLog() {
+        // JPA
+    }
+
+    public ClientKycContactLog(final Client client, final Long kycId, final KycContactChannel channel, final String notes,
+            final String officerName, final Long loggedByUserId, final String exceptionReason, final LocalDateTime contactedAt) {
+        this.client = client;
+        this.kycId = kycId;
+        this.channel = channel;
+        this.notes = notes;
+        this.officerName = officerName;
+        this.loggedByUserId = loggedByUserId;
+        this.exceptionReason = exceptionReason;
+        this.contactedAt = contactedAt;
+        this.createdAt = contactedAt;
+        this.deliveryStatus = KycContactDeliveryStatus.NOT_APPLICABLE;
+    }
+
+    /**
+     * Stamp the outcome of a platform send onto this log row. Called once, before the row is
+     * persisted — the entity is append-only afterwards.
+     */
+    public void recordDeliveryOutcome(final KycContactDeliveryStatus status, final String destinationMasked, final String provider,
+            final String providerReference, final String failureReason, final String messageBody) {
+        this.deliveryStatus = status;
+        this.destinationMasked = destinationMasked;
+        this.provider = provider;
+        this.providerReference = providerReference;
+        this.failureReason = truncate(failureReason, 500);
+        this.messageBody = truncate(messageBody, 2000);
+    }
+
+    private static String truncate(final String value, final int max) {
+        if (value == null || value.length() <= max) {
+            return value;
+        }
+        return value.substring(0, max - 3) + "...";
+    }
+
+    public Long getId() {
+        return this.id;
+    }
+
+    public Client getClient() {
+        return this.client;
+    }
+
+    public Long getKycId() {
+        return this.kycId;
+    }
+
+    public KycContactChannel getChannel() {
+        return this.channel;
+    }
+
+    public String getNotes() {
+        return this.notes;
+    }
+
+    public String getOfficerName() {
+        return this.officerName;
+    }
+
+    public Long getLoggedByUserId() {
+        return this.loggedByUserId;
+    }
+
+    public String getExceptionReason() {
+        return this.exceptionReason;
+    }
+
+    public KycContactDeliveryStatus getDeliveryStatus() {
+        return this.deliveryStatus;
+    }
+
+    public String getDestinationMasked() {
+        return this.destinationMasked;
+    }
+
+    public String getProvider() {
+        return this.provider;
+    }
+
+    public String getProviderReference() {
+        return this.providerReference;
+    }
+
+    public String getFailureReason() {
+        return this.failureReason;
+    }
+
+    public String getMessageBody() {
+        return this.messageBody;
+    }
+
+    public LocalDateTime getContactedAt() {
+        return this.contactedAt;
+    }
+
+    public LocalDateTime getCreatedAt() {
+        return this.createdAt;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientKycContactLogRepository.java

@@ -0,0 +1,36 @@
+/**
+ * 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.portfolio.client.domain;
+
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+public interface ClientKycContactLogRepository extends JpaRepository<ClientKycContactLog, Long> {
+
+    List<ClientKycContactLog> findByClientIdOrderByContactedAtAsc(Long clientId);
+
+    /**
+     * Every contact log for the given clients in one round trip, so the exceptions grid can render
+     * "last contacted" for the whole page without an N+1 query per row.
+     */
+    @Query("SELECT l FROM ClientKycContactLog l WHERE l.client.id IN :clientIds ORDER BY l.contactedAt ASC")
+    List<ClientKycContactLog> findByClientIds(@Param("clientIds") List<Long> clientIds);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientKycRepository.java

@@ -33,6 +33,18 @@ public interface ClientKycRepository extends JpaRepository<ClientKyc, Long> {
 
     boolean existsByClientId(Long clientId);
 
+    List<ClientKyc> findByIsExceptionTrueAndExceptionResolvedFalse();
+
+    /**
+     * Resolved exceptions, keyed on {@code exceptionResolved} alone.
+     *
+     * <p>Deliberately does NOT also require {@code isException = true}. Resolving an exception
+     * clears {@code isException} — that flag means "has an OPEN exception", so leaving it set on a
+     * closed one would be wrong. An earlier version of this query required both flags, which made
+     * every resolved record invisible in both tabs the moment it was resolved.
+     */
+    List<ClientKyc> findByExceptionResolvedTrue();
+
     @Query("SELECT k FROM ClientKyc k WHERE k.kycStatus = :status")
     List<ClientKyc> findAllByStatus(@Param("status") Integer status);
 

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/KycContactChannel.java

@@ -0,0 +1,91 @@
+/**
+ * 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.portfolio.client.domain;
+
+/**
+ * The channel a KYC officer used (or asked the platform to use) to reach a customer about an open
+ * KYC exception.
+ *
+ * <p>The critical distinction is {@link #isPlatformSent()}:
+ * <ul>
+ *   <li><b>Offline channels</b> ({@code PHONE_CALL}, {@code BRANCH_VISIT}, {@code FIELD_VISIT}) are
+ *       recorded after the fact — the officer already did the thing, the platform only writes it
+ *       down.</li>
+ *   <li><b>Sending channels</b> ({@code SMS}, {@code EMAIL}, {@code WHATSAPP}) cause the platform to
+ *       actually transmit a notice to the customer at save time.</li>
+ * </ul>
+ * Mixing these up would let a "logged" row imply the customer was told something they never
+ * received, so every call site branches on this flag rather than on the channel name.
+ */
+public enum KycContactChannel {
+
+    PHONE_CALL("Phone Call", false),
+    SMS("SMS", true),
+    EMAIL("Email", true),
+    WHATSAPP("WhatsApp Message", true),
+    BRANCH_VISIT("In-Branch Visit", false),
+    FIELD_VISIT("Agent Field Visit", false);
+
+    private final String displayLabel;
+    private final boolean platformSent;
+
+    KycContactChannel(final String displayLabel, final boolean platformSent) {
+        this.displayLabel = displayLabel;
+        this.platformSent = platformSent;
+    }
+
+    public String getDisplayLabel() {
+        return this.displayLabel;
+    }
+
+    /** True when saving a log of this channel must actually transmit a message to the customer. */
+    public boolean isPlatformSent() {
+        return this.platformSent;
+    }
+
+    /**
+     * Lenient parse of whatever the UI sent. Accepts the enum name ({@code SMS}) as well as the
+     * display label, and tolerates the descriptive suffixes the dialog uses — e.g.
+     * {@code "SMS (Aadhaar OTP request)"} and {@code "Email (PAN Link request)"} — because those
+     * labels describe the *purpose* of the message, not a different channel.
+     *
+     * @return the matching channel, or {@code null} when nothing matches.
+     */
+    public static KycContactChannel fromString(final String raw) {
+        if (raw == null || raw.isBlank()) {
+            return null;
+        }
+        final String normalised = raw.trim().toUpperCase();
+        for (final KycContactChannel channel : values()) {
+            if (normalised.equals(channel.name()) || normalised.equals(channel.displayLabel.toUpperCase())) {
+                return channel;
+            }
+        }
+        // Prefix match handles the "(…request)" suffixes. Longest label first so WHATSAPP's
+        // "WHATSAPP MESSAGE" is preferred over a shorter accidental prefix.
+        KycContactChannel best = null;
+        for (final KycContactChannel channel : values()) {
+            final String label = channel.displayLabel.toUpperCase();
+            if (normalised.startsWith(label) && (best == null || label.length() > best.displayLabel.length())) {
+                best = channel;
+            }
+        }
+        return best;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/KycContactDeliveryStatus.java

@@ -0,0 +1,48 @@
+/**
+ * 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.portfolio.client.domain;
+
+/**
+ * Outcome of a platform-sent KYC contact notice.
+ *
+ * <p>Every state other than {@link #SENT} means the customer was <em>not</em> reached. The officer
+ * is shown the distinction explicitly, because a contact log that silently swallows a gateway
+ * failure would understate the bank's outreach obligation during a KYC audit.
+ */
+public enum KycContactDeliveryStatus {
+
+    /** Offline channel — nothing was transmitted and nothing was supposed to be. */
+    NOT_APPLICABLE,
+
+    /** The gateway accepted the message for delivery. */
+    SENT,
+
+    /** The gateway was reached but rejected the message, or the call errored. */
+    FAILED,
+
+    /** The customer has no mobile number / email address on file for this channel. */
+    SKIPPED_NO_DESTINATION,
+
+    /** No gateway is configured for this channel in this deployment. */
+    PROVIDER_NOT_CONFIGURED;
+
+    public boolean isDelivered() {
+        return this == SENT;
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/accounts/constants/ShareAccountApiConstants.java

@@ -102,12 +102,23 @@ public interface ShareAccountApiConstants {
 
     String shareEntityType = "share";
 
+    /** Required on a redeem-shares (withdrawal) request — Board Resolution Number and Date of
+     *  Meeting authorising the withdrawal (cooperative-sector share capital governance). */
+    String redeemresolutionnumber_paramname = "resolutionNumber";
+
+    String redeemmeetingdate_paramname = "meetingDate";
+
+    /** Loan this share account is held as margin/security against — optional, set via the
+     *  account update command. When present, a redeem request is checked against the loan's
+     *  outstanding balance. */
+    String linkedloanid_paramname = "linkedLoanId";
+
     Set<String> supportedParameters = Collections.unmodifiableSet(new HashSet<>(Arrays.asList(locale_paramname, dateformat_paramname,
             id_paramname, clientid_paramname, productid_paramname, submitteddate_paramname, approveddate_paramname, externalid_paramname,
             resolutionnumber_paramname, currency_paramname, digitsafterdecimal_paramname, inmultiplesof_paramname,
             requestedshares_paramname, savingsaccountid_paramname, lockinperiod_paramname, lockperiodfrequencytype_paramname,
             minimumactiveperiod_paramname, minimumactiveperiodfrequencytype_paramname,
             allowdividendcalculationforinactiveclients_paramname, charges_paramname, applicationdate_param, purchaseddate_paramname,
-            numberofshares_paramname, purchasedprice_paramname)));
+            numberofshares_paramname, purchasedprice_paramname, linkedloanid_paramname)));
 
 }

fineract-provider/src/main/java/org/apache/fineract/portfolio/clerkwithdrawal/api/ClerkShareWithdrawalRequestApiResource.java

@@ -0,0 +1,615 @@
+/**
+ * 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.portfolio.clerkwithdrawal.api;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonArray;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.DefaultValue;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.NotFoundException;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.WebApplicationException;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+import java.math.BigDecimal;
+import java.sql.Date;
+import java.sql.Timestamp;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.commands.domain.CommandWrapper;
+import org.apache.fineract.commands.service.CommandWrapperBuilder;
+import org.apache.fineract.commands.service.PortfolioCommandSourceWritePlatformService;
+import org.apache.fineract.infrastructure.core.data.CommandProcessingResult;
+import org.apache.fineract.infrastructure.core.serialization.FromJsonHelper;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.apache.fineract.useradministration.domain.AppUser;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Maker-checker withdrawal (redeem shares) request workflow for a Share Account, submitted only
+ * from the Clerk Dashboard. A clerk (maker) submits a request naming the shares to redeem plus the
+ * governing Board Resolution Number / Date of Meeting; a Bank Manager (checker) approves it, which
+ * server-side executes the real Fineract "redeemshares" command against the share account, or
+ * rejects it. Mirrors {@link ClerkWithdrawalRequestApiResource} (cash withdrawal) — same
+ * maker-checker shape, adapted for shares (no cash denomination/disbursement leg; a share
+ * redemption is a book-entry, not a cash handover).
+ */
+@Path("/v1/clerk/share-withdrawal-requests")
+@Component
+@Tag(name = "Clerk Share Withdrawal Requests", description = "Maker-checker share redemption workflow for clerk and bank manager.")
+@RequiredArgsConstructor
+public class ClerkShareWithdrawalRequestApiResource {
+
+    private final JdbcTemplate jdbcTemplate;
+    private final FromJsonHelper fromJsonHelper;
+    private final PlatformSecurityContext context;
+    private final PortfolioCommandSourceWritePlatformService commandsSourceWritePlatformService;
+    // Raw java.sql.Date/Timestamp values coming straight off jdbcTemplate row Maps (requested_date,
+    // meeting_date, submitted_at, actioned_at) get serialized by Gson's *default* locale-dependent
+    // format (e.g. "Aug 5, 2026 12:00:00 AM") unless a format is set here — that broke the frontend's
+    // simple split('T')[0]/split(' ')[0] date parsing, which expects an ISO-shaped string.
+    private final Gson gson = new GsonBuilder().serializeNulls().setDateFormat("yyyy-MM-dd'T'HH:mm:ss").create();
+
+    private static final String[] LIST_COLUMNS = { "id", "share_account_id", "account_no", "client_id", "client_name",
+            "requested_shares", "requested_date", "resolution_number", "meeting_date", "description", "status", "clerk_id", "clerk_name",
+            "clerk_username", "manager_id", "manager_name", "manager_username", "rejection_reason", "share_transaction_id",
+            "activity_log", "submitted_at", "actioned_at", "settlement_payment_type_id",
+            "(SELECT value FROM m_payment_type WHERE id = settlement_payment_type_id) AS settlement_payment_type_name",
+            "settlement_amount", "settlement_savings_transaction_id", "settlement_row_snapshot" };
+
+    private static final String SHARE_REDEMPTION_PAYMENT_TYPE_CODE = "SHARE_REDEMPTION_TRANSFER";
+
+    // ── POST /v1/clerk/share-withdrawal-requests ── Clerk submits new request ───
+
+    @POST
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    @Transactional
+    public String submit(final String body) {
+        final AppUser currentUser = context.authenticatedUser();
+        final JsonElement root = fromJsonHelper.parse(body);
+
+        final Long shareAccountId = fromJsonHelper.extractLongNamed("shareAccountId", root);
+        final String accountNo = fromJsonHelper.extractStringNamed("accountNo", root);
+        final Long clientId = fromJsonHelper.extractLongNamed("clientId", root);
+        final String clientName = fromJsonHelper.extractStringNamed("clientName", root);
+        final Long requestedShares = fromJsonHelper.extractLongNamed("requestedShares", root);
+        final String requestedDate = fromJsonHelper.extractStringNamed("requestedDate", root);
+        final String resolutionNumber = fromJsonHelper.extractStringNamed("resolutionNumber", root);
+        final String meetingDate = fromJsonHelper.extractStringNamed("meetingDate", root);
+        final String description = fromJsonHelper.extractStringNamed("description", root);
+        final Long settlementPaymentTypeId = fromJsonHelper.extractLongNamed("settlementPaymentTypeId", root);
+        // Full snapshot of the CR/settlement row as the clerk filled it in (account no., ECS a/c no.,
+        // amount, cheque no./date, token no., description, bank name, routing code, payment type) —
+        // stored verbatim as submitted JSON purely for audit purposes; business logic never re-reads
+        // it, since the CR row's account number is only ever used client-side to double-check against
+        // the share account's own authoritative linked-savings-account link.
+        final JsonElement snapshotElement = root.isJsonObject() ? root.getAsJsonObject().get("settlementRowSnapshot") : null;
+        final String settlementRowSnapshot = snapshotElement != null && !snapshotElement.isJsonNull() ? snapshotElement.toString()
+                : null;
+
+        if (shareAccountId == null) {
+            throw apiError(400, "Share account id is required");
+        }
+        if (accountNo == null || accountNo.isBlank()) {
+            throw apiError(400, "Account number is required");
+        }
+        if (requestedShares == null || requestedShares <= 0) {
+            throw apiError(400, "Number of shares to withdraw must be greater than zero");
+        }
+        if (requestedDate == null || requestedDate.isBlank()) {
+            throw apiError(400, "Requested date is required");
+        }
+        if (resolutionNumber == null || resolutionNumber.isBlank()) {
+            throw apiError(400, "Board Resolution Number is required for a share withdrawal");
+        }
+        if (meetingDate == null || meetingDate.isBlank()) {
+            throw apiError(400, "Date of Meeting is required for a share withdrawal");
+        }
+        if (settlementPaymentTypeId == null) {
+            throw apiError(400, "Settlement Payment Type is required — pick how the linked savings account should be credited");
+        }
+        validateSettlementPaymentType(settlementPaymentTypeId);
+
+        final String activityLog = buildActivityLog(null, "SUBMITTED", currentUser.getUsername(), null);
+
+        final Long newId = jdbcTemplate.queryForObject("""
+                INSERT INTO m_clerk_share_withdrawal_request
+                (share_account_id, account_no, client_id, client_name, requested_shares, requested_date,
+                 resolution_number, meeting_date, description, status, clerk_id, clerk_name, clerk_username,
+                 activity_log, submitted_at, settlement_payment_type_id, settlement_row_snapshot)
+                VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+                RETURNING id
+                """,
+                Long.class, shareAccountId, accountNo, clientId, clientName, requestedShares, Date.valueOf(requestedDate),
+                resolutionNumber, Date.valueOf(meetingDate), description, "PENDING", currentUser.getId(), currentUser.getDisplayName(),
+                currentUser.getUsername(), activityLog, Timestamp.from(Instant.now()), settlementPaymentTypeId, settlementRowSnapshot);
+
+        return gson.toJson(Map.of("resourceId", newId, "status", "PENDING"));
+    }
+
+    /**
+     * Settlement is always a book-transfer from Share Sundry to the linked savings account — never a
+     * cash payout at the teller counter — so cash-flagged payment types are rejected here regardless
+     * of what the clerk picked in the UI.
+     */
+    private void validateSettlementPaymentType(final Long paymentTypeId) {
+        final Map<String, Object> paymentType = jdbcTemplate
+                .queryForList("SELECT value, is_cash_payment FROM m_payment_type WHERE id = ?", paymentTypeId).stream().findFirst()
+                .orElse(null);
+        if (paymentType == null) {
+            throw apiError(400, "Settlement Payment Type " + paymentTypeId + " does not exist");
+        }
+        final boolean isCash = Boolean.TRUE.equals(paymentType.get("is_cash_payment"));
+        if (isCash) {
+            throw apiError(400, "Settlement Payment Type '" + paymentType.get("value")
+                    + "' is a cash payment type — share redemption settlement to a linked savings account must be a non-cash book-transfer");
+        }
+    }
+
+    // ── GET /v1/clerk/share-withdrawal-requests ── Manager sees all requests ────
+
+    @GET
+    @Produces(MediaType.APPLICATION_JSON)
+    public String list(@QueryParam("status") @DefaultValue("PENDING") final String status,
+            @QueryParam("offset") @DefaultValue("0") final int offset, @QueryParam("limit") @DefaultValue("20") final int limit,
+            @QueryParam("fromDate") final String fromDate, @QueryParam("toDate") final String toDate) {
+        return queryList("WHERE status = ?", new ArrayList<>(List.of(status)), fromDate, toDate, offset, limit);
+    }
+
+    // ── GET /v1/clerk/share-withdrawal-requests/my ── Clerk's own requests ──────
+
+    @GET
+    @Path("/my")
+    @Produces(MediaType.APPLICATION_JSON)
+    public String myRequests(@QueryParam("status") final String status, @QueryParam("offset") @DefaultValue("0") final int offset,
+            @QueryParam("limit") @DefaultValue("20") final int limit, @QueryParam("fromDate") final String fromDate,
+            @QueryParam("toDate") final String toDate) {
+        final AppUser currentUser = context.authenticatedUser();
+        final StringBuilder where = new StringBuilder("WHERE clerk_id = ?");
+        final List<Object> params = new ArrayList<>(List.of(currentUser.getId()));
+        if (status != null && !status.isBlank()) {
+            where.append(" AND status = ?");
+            params.add(status);
+        }
+        return queryList(where.toString(), params, fromDate, toDate, offset, limit);
+    }
+
+    private String queryList(final String baseWhere, final List<Object> baseParams, final String fromDate, final String toDate,
+            final int offset, final int limit) {
+        final StringBuilder where = new StringBuilder(baseWhere);
+        final List<Object> params = new ArrayList<>(baseParams);
+        if (fromDate != null && !fromDate.isBlank()) {
+            where.append(" AND DATE(submitted_at) >= ?");
+            params.add(Date.valueOf(fromDate));
+        }
+        if (toDate != null && !toDate.isBlank()) {
+            where.append(" AND DATE(submitted_at) <= ?");
+            params.add(Date.valueOf(toDate));
+        }
+
+        final long total = Optional
+                .ofNullable(jdbcTemplate.queryForObject("SELECT COUNT(*) FROM m_clerk_share_withdrawal_request " + where, Long.class,
+                        params.toArray()))
+                .orElse(0L);
+
+        final List<Object> pageParams = new ArrayList<>(params);
+        pageParams.add(limit);
+        pageParams.add(offset);
+
+        final List<Map<String, Object>> rows = jdbcTemplate.queryForList(
+                "SELECT " + String.join(", ", LIST_COLUMNS) + " FROM m_clerk_share_withdrawal_request " + where
+                        + " ORDER BY submitted_at DESC LIMIT ? OFFSET ?",
+                pageParams.toArray());
+
+        final JsonObject result = new JsonObject();
+        result.addProperty("totalFilteredRecords", total);
+        result.add("pageItems", gson.toJsonTree(rows));
+        return gson.toJson(result);
+    }
+
+    // ── GET /v1/clerk/share-withdrawal-requests/{id} ── Full detail ─────────────
+
+    @GET
+    @Path("/{id}")
+    @Produces(MediaType.APPLICATION_JSON)
+    public String getById(@PathParam("id") final Long id) {
+        return gson.toJson(loadRecord(id));
+    }
+
+    // ── POST /v1/clerk/share-withdrawal-requests/{id}/validate ── Manager runs live checks ──
+
+    /**
+     * Re-runs every check against the CURRENT live state (not the snapshot taken at submit time), so
+     * the checker can catch things that changed since submission — a share/savings account that got
+     * closed, a payment type that got deactivated, or (the exact bug class this session ran into) a
+     * savings product's GL Fund Source mapping for this payment type going missing, which would
+     * silently post the settlement leg to the default Cash at Vault account instead of Share Sundry.
+     */
+    @POST
+    @Path("/{id}/validate")
+    @Produces(MediaType.APPLICATION_JSON)
+    public String validate(@PathParam("id") final Long id) {
+        final Map<?, ?> record = loadRecord(id);
+        final List<Map<String, Object>> checks = new ArrayList<>();
+
+        final String status = (String) record.get("status");
+        checks.add(checkResult("Request status is PENDING", "PENDING".equals(status), String.valueOf(status)));
+
+        final String resolutionNumber = (String) record.get("resolution_number");
+        checks.add(checkResult("Board Resolution Number provided", resolutionNumber != null && !resolutionNumber.isBlank(),
+                resolutionNumber == null || resolutionNumber.isBlank() ? "Missing" : resolutionNumber));
+
+        final Object meetingDate = record.get("meeting_date");
+        checks.add(checkResult("Date of Meeting provided", meetingDate != null,
+                meetingDate == null ? "Missing" : meetingDate.toString().substring(0, Math.min(10, meetingDate.toString().length()))));
+
+        final Long shareAccountId = ((Number) record.get("share_account_id")).longValue();
+        final Long requestedShares = ((Number) record.get("requested_shares")).longValue();
+
+        final Map<String, Object> shareAccountRow = jdbcTemplate.queryForList("""
+                SELECT total_approved_shares AS totalApprovedShares, status_enum AS statusEnum, savings_account_id AS savingsAccountId
+                FROM m_share_account WHERE id = ?
+                """, shareAccountId).stream().findFirst().orElse(null);
+
+        final long heldShares = shareAccountRow != null && shareAccountRow.get("totalApprovedShares") != null
+                ? ((Number) shareAccountRow.get("totalApprovedShares")).longValue()
+                : 0L;
+        checks.add(checkResult("Shares requested within current shares held", shareAccountRow != null && requestedShares <= heldShares,
+                requestedShares + " of " + heldShares + " shares currently held"));
+
+        final int shareAccountStatus = shareAccountRow != null && shareAccountRow.get("statusEnum") != null
+                ? ((Number) shareAccountRow.get("statusEnum")).intValue()
+                : -1;
+        checks.add(checkResult("Share account is Active", shareAccountStatus == 300, "Status code: " + shareAccountStatus));
+
+        final Long savingsAccountId = shareAccountRow != null && shareAccountRow.get("savingsAccountId") != null
+                ? ((Number) shareAccountRow.get("savingsAccountId")).longValue()
+                : null;
+        checks.add(checkResult("Linked savings account confirmed", savingsAccountId != null,
+                savingsAccountId != null ? "Savings account id " + savingsAccountId : "No linked savings account configured"));
+
+        Integer savingsStatus = null;
+        Long savingsProductId = null;
+        if (savingsAccountId != null) {
+            final Map<String, Object> savingsRow = jdbcTemplate
+                    .queryForList("SELECT status_enum AS statusEnum, product_id AS productId FROM m_savings_account WHERE id = ?",
+                            savingsAccountId)
+                    .stream().findFirst().orElse(null);
+            savingsStatus = savingsRow != null && savingsRow.get("statusEnum") != null ? ((Number) savingsRow.get("statusEnum")).intValue()
+                    : null;
+            savingsProductId = savingsRow != null && savingsRow.get("productId") != null ? ((Number) savingsRow.get("productId")).longValue()
+                    : null;
+        }
+        checks.add(checkResult("Linked savings account is Active", savingsStatus != null && savingsStatus == 300,
+                savingsStatus != null ? "Status code: " + savingsStatus : "Not found"));
+
+        final Object settlementPaymentTypeIdObj = record.get("settlement_payment_type_id");
+        final Long settlementPaymentTypeId = settlementPaymentTypeIdObj instanceof Number
+                ? ((Number) settlementPaymentTypeIdObj).longValue()
+                : null;
+        final Object settlementPaymentTypeName = record.get("settlement_payment_type_name");
+        checks.add(checkResult("Settlement Payment Type selected", settlementPaymentTypeId != null,
+                settlementPaymentTypeName != null ? settlementPaymentTypeName.toString() : "Missing"));
+
+        boolean paymentTypeNonCash = false;
+        if (settlementPaymentTypeId != null) {
+            final Map<String, Object> pt = jdbcTemplate
+                    .queryForList("SELECT is_cash_payment FROM m_payment_type WHERE id = ?", settlementPaymentTypeId).stream()
+                    .findFirst().orElse(null);
+            paymentTypeNonCash = pt != null && !Boolean.TRUE.equals(pt.get("is_cash_payment"));
+        }
+        checks.add(checkResult("Settlement Payment Type is non-cash", paymentTypeNonCash,
+                paymentTypeNonCash ? "Confirmed non-cash" : "Cash payment type or not found — settlement would be rejected"));
+
+        boolean glMappingOk = false;
+        String glMappingDetail = "Linked savings account or settlement payment type missing — cannot check";
+        if (savingsProductId != null && settlementPaymentTypeId != null) {
+            final Map<String, Object> mapping = jdbcTemplate.queryForList("""
+                    SELECT gl.name AS glName FROM acc_product_mapping apm
+                    JOIN acc_gl_account gl ON gl.id = apm.gl_account_id
+                    WHERE apm.product_type = 2 AND apm.product_id = ? AND apm.payment_type = ? AND apm.financial_account_type = 1
+                    """, savingsProductId, settlementPaymentTypeId).stream().findFirst().orElse(null);
+            glMappingOk = mapping != null;
+            glMappingDetail = mapping != null ? "Fund source mapped to: " + mapping.get("glName")
+                    : "No GL Fund Source override configured for this Payment Type — settlement would silently post to the default Cash at Vault account instead of Share Sundry";
+        }
+        checks.add(checkResult("GL Fund Source mapping configured for this Payment Type", glMappingOk, glMappingDetail));
+
+        final boolean allPassed = checks.stream().allMatch(c -> Boolean.TRUE.equals(c.get("pass")));
+        final JsonObject res = new JsonObject();
+        res.addProperty("allPassed", allPassed);
+        res.add("checks", gson.toJsonTree(checks));
+        return gson.toJson(res);
+    }
+
+    private Map<String, Object> checkResult(final String label, final boolean pass, final String detail) {
+        final Map<String, Object> result = new java.util.LinkedHashMap<>();
+        result.put("label", label);
+        result.put("pass", pass);
+        result.put("detail", detail);
+        return result;
+    }
+
+    // ── POST /v1/clerk/share-withdrawal-requests/{id}/approve ── Manager approves ──
+
+    @POST
+    @Path("/{id}/approve")
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    @Transactional
+    public String approve(@PathParam("id") final Long id, final String body) {
+        final AppUser currentUser = context.authenticatedUser();
+        validateCheckerRole(currentUser);
+        final Map<?, ?> record = loadRecord(id);
+
+        if (!"PENDING".equals(record.get("status"))) {
+            throw apiError(409, "Only PENDING requests can be approved. Current status: " + record.get("status"));
+        }
+        final Long makerId = ((Number) record.get("clerk_id")).longValue();
+        if (makerId.equals(currentUser.getId())) {
+            throw apiError(403,
+                    "Maker-checker: you cannot approve a share withdrawal request you submitted yourself. Ask another manager to review it.");
+        }
+
+        final Long shareAccountId = ((Number) record.get("share_account_id")).longValue();
+        final Long requestedShares = ((Number) record.get("requested_shares")).longValue();
+        final Object requestedDateObj = record.get("requested_date");
+        final Object meetingDateObj = record.get("meeting_date");
+        final String resolutionNumber = (String) record.get("resolution_number");
+
+        final JsonObject payload = new JsonObject();
+        payload.addProperty("locale", "en");
+        payload.addProperty("dateFormat", "dd MMMM yyyy");
+        payload.addProperty("requestedDate", formatForFineract(requestedDateObj.toString()));
+        payload.addProperty("requestedShares", requestedShares);
+        payload.addProperty("resolutionNumber", resolutionNumber);
+        payload.addProperty("meetingDate", formatForFineract(meetingDateObj.toString()));
+
+        final CommandWrapper commandRequest = new CommandWrapperBuilder().createAccountCommand("share", shareAccountId, "redeemshares")
+                .withJson(payload.toString()).build();
+        final CommandProcessingResult result = commandsSourceWritePlatformService.logCommandSource(commandRequest);
+        // redeemShares() puts the newly-created share transaction's id under "requestedShares" in
+        // the changes map — NOT in getResourceId(), which for this command is the share ACCOUNT id
+        // instead. Reading getResourceId() here would silently look up the wrong row downstream.
+        final Object shareTxnIdRaw = result.getChanges() != null ? result.getChanges().get("requestedShares") : null;
+        final Long shareTransactionId = shareTxnIdRaw instanceof Number ? ((Number) shareTxnIdRaw).longValue() : null;
+        final String shareTxnId = shareTransactionId != null ? shareTransactionId.toString() : null;
+
+        // Settlement: within this SAME approval transaction, immediately credit the redemption value
+        // to the member's linked savings account. Two Fineract journal entries get posted — native
+        // redeem's Dr Share Equity / Cr Shares Reference, then this deposit's Dr Shares Reference /
+        // Cr Savings Control — but the Shares Reference leg nets to zero instantly, so the combined
+        // financial result is exactly Dr Share Equity / Cr Savings Control, same as one direct entry.
+        final Object storedSettlementPaymentTypeId = record.get("settlement_payment_type_id");
+        final Long settlementPaymentTypeId = storedSettlementPaymentTypeId instanceof Number
+                ? ((Number) storedSettlementPaymentTypeId).longValue()
+                : null;
+        final Settlement settlement = creditLinkedSavingsAccount(shareAccountId, shareTransactionId, requestedDateObj.toString(),
+                resolutionNumber, settlementPaymentTypeId);
+
+        final String settlementNote = settlement != null
+                ? "Settled " + settlement.amount() + " to linked savings account (txn #" + settlement.savingsTransactionId() + ")"
+                : "No linked savings account on this share account — settlement must be completed manually.";
+        final String updatedLog = buildActivityLog((String) record.get("activity_log"), "APPROVED", currentUser.getUsername(),
+                settlementNote);
+
+        final int approvedRows = jdbcTemplate.update("""
+                UPDATE m_clerk_share_withdrawal_request SET
+                  status = 'APPROVED', manager_id = ?, manager_name = ?, manager_username = ?,
+                  share_transaction_id = ?, activity_log = ?, actioned_at = ?,
+                  settlement_amount = ?, settlement_savings_transaction_id = ?
+                WHERE id = ? AND status = 'PENDING'
+                """, currentUser.getId(), currentUser.getDisplayName(), currentUser.getUsername(), shareTxnId, updatedLog,
+                Timestamp.from(Instant.now()), settlement != null ? settlement.amount() : null,
+                settlement != null ? settlement.savingsTransactionId() : null, id);
+        if (approvedRows == 0) {
+            throw apiError(409, "This share withdrawal request was already actioned by another manager.");
+        }
+
+        final JsonObject res = new JsonObject();
+        res.addProperty("resourceId", id);
+        res.addProperty("status", "APPROVED");
+        if (shareTxnId != null) {
+            res.addProperty("shareTransactionId", shareTxnId);
+        }
+        if (settlement != null) {
+            res.addProperty("settlementAmount", settlement.amount());
+            res.addProperty("settlementSavingsTransactionId", settlement.savingsTransactionId());
+        } else {
+            res.addProperty("settlementWarning", settlementNote);
+        }
+        return gson.toJson(res);
+    }
+
+    private record Settlement(BigDecimal amount, Long savingsTransactionId) {}
+
+    /**
+     * Credits the redemption value to the share account's linked savings account, if one exists.
+     * Reads the amount straight off the just-created redeem transaction row rather than re-deriving
+     * the unit price ourselves — the transaction was already priced by Fineract's own
+     * {@code ShareProduct#deriveMarketPrice(requestedDate)} (the requested date, not necessarily
+     * today) and already nets out any redemption charge. Uses Fineract's own native savings deposit
+     * command so the transaction is fully audited and posts its own GL entry the normal way — the
+     * debit side lands on whichever GL account is mapped to the settlement payment type the clerk
+     * chose at submit time (validated to be non-cash and persisted on the request row) — matching the
+     * Share Product's own "Shares Reference" mapping (Share Sundry) — so the two entries net to zero
+     * on that bridge account. Falls back to the legacy hardcoded
+     * {@link #SHARE_REDEMPTION_PAYMENT_TYPE_CODE} lookup only for requests submitted before this
+     * column existed.
+     */
+    private Settlement creditLinkedSavingsAccount(final Long shareAccountId, final Long shareTransactionId, final String requestedDateStr,
+            final String resolutionNumber, final Long settlementPaymentTypeId) {
+        if (shareTransactionId == null) {
+            return null;
+        }
+        final Map<String, Object> row = jdbcTemplate.queryForList("""
+                SELECT sa.savings_account_id AS savingsAccountId, sat.amount AS settlementAmount
+                FROM m_share_account_transactions sat JOIN m_share_account sa ON sa.id = sat.account_id
+                WHERE sat.id = ?
+                """, shareTransactionId).stream().findFirst().orElse(null);
+        if (row == null) {
+            return null;
+        }
+        final Long savingsAccountId = row.get("savingsAccountId") == null ? null : ((Number) row.get("savingsAccountId")).longValue();
+        if (savingsAccountId == null) {
+            return null;
+        }
+
+        final BigDecimal settlementAmount = (BigDecimal) row.get("settlementAmount");
+
+        final Long paymentTypeId = settlementPaymentTypeId != null ? settlementPaymentTypeId
+                : jdbcTemplate.queryForList("SELECT id FROM m_payment_type WHERE code_name = ?", Long.class,
+                        SHARE_REDEMPTION_PAYMENT_TYPE_CODE).stream().findFirst().orElse(null);
+
+        final JsonObject payload = new JsonObject();
+        payload.addProperty("locale", "en");
+        payload.addProperty("dateFormat", "dd MMMM yyyy");
+        payload.addProperty("transactionDate", formatForFineract(requestedDateStr));
+        payload.addProperty("transactionAmount", settlementAmount);
+        if (paymentTypeId != null) {
+            payload.addProperty("paymentTypeId", paymentTypeId);
+        }
+        payload.addProperty("note", "Share redemption settlement — Resolution No. " + resolutionNumber);
+
+        final CommandWrapper commandRequest = new CommandWrapperBuilder().savingsAccountDeposit(savingsAccountId)
+                .withJson(payload.toString()).build();
+        final CommandProcessingResult result = commandsSourceWritePlatformService.logCommandSource(commandRequest);
+        return new Settlement(settlementAmount, result.getResourceId());
+    }
+
+    // ── POST /v1/clerk/share-withdrawal-requests/{id}/reject ── Manager rejects ─
+
+    @POST
+    @Path("/{id}/reject")
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    @Transactional
+    public String reject(@PathParam("id") final Long id, final String body) {
+        final AppUser currentUser = context.authenticatedUser();
+        validateCheckerRole(currentUser);
+        final Map<?, ?> record = loadRecord(id);
+
+        if (!"PENDING".equals(record.get("status"))) {
+            throw apiError(409, "Only PENDING requests can be rejected. Current status: " + record.get("status"));
+        }
+
+        final JsonElement root = fromJsonHelper.parse(body != null && !body.isBlank() ? body : "{}");
+        final String reason = fromJsonHelper.extractStringNamed("reason", root);
+        if (reason == null || reason.isBlank()) {
+            throw apiError(400, "Rejection reason is required");
+        }
+
+        final String updatedLog = buildActivityLog((String) record.get("activity_log"), "REJECTED", currentUser.getUsername(), reason);
+
+        final int rejectedRows = jdbcTemplate.update("""
+                UPDATE m_clerk_share_withdrawal_request SET
+                  status = 'REJECTED', manager_id = ?, manager_name = ?, manager_username = ?,
+                  rejection_reason = ?, activity_log = ?, actioned_at = ?
+                WHERE id = ? AND status = 'PENDING'
+                """, currentUser.getId(), currentUser.getDisplayName(), currentUser.getUsername(), reason, updatedLog,
+                Timestamp.from(Instant.now()), id);
+        if (rejectedRows == 0) {
+            throw apiError(409, "This share withdrawal request was already actioned by another manager.");
+        }
+
+        return gson.toJson(Map.of("resourceId", id, "status", "REJECTED"));
+    }
+
+    private void validateCheckerRole(final AppUser user) {
+        if (user.hasAnyPermission("ALL_FUNCTIONS")) {
+            return;
+        }
+        final boolean isChecker = user.getRoles().stream().map(r -> r.getName() == null ? "" : r.getName().toLowerCase().trim())
+                .anyMatch(n -> n.contains("manager") || n.contains("head cashier"));
+        if (!isChecker) {
+            throw apiError(403, "Only a Bank Manager (or Head Cashier) can approve or reject share withdrawal requests.");
+        }
+    }
+
+    private Map<?, ?> loadRecord(final Long id) {
+        final List<Map<String, Object>> rows = jdbcTemplate
+                .queryForList("SELECT " + String.join(", ", LIST_COLUMNS) + " FROM m_clerk_share_withdrawal_request WHERE id = ?", id);
+        if (rows.isEmpty()) {
+            throw new NotFoundException("Share withdrawal request not found: " + id);
+        }
+        return rows.get(0);
+    }
+
+    private String formatForFineract(final String isoOrTimestamp) {
+        try {
+            final String isoDatePart = isoOrTimestamp.length() >= 10 ? isoOrTimestamp.substring(0, 10) : isoOrTimestamp;
+            final LocalDate ld = LocalDate.parse(isoDatePart, DateTimeFormatter.ISO_LOCAL_DATE);
+            return ld.format(DateTimeFormatter.ofPattern("dd MMMM yyyy"));
+        } catch (Exception e) {
+            return LocalDate.now(DateUtils.getDateTimeZoneOfTenant()).format(DateTimeFormatter.ofPattern("dd MMMM yyyy"));
+        }
+    }
+
+    private String buildActivityLog(final String existingJson, final String action, final String username, final String note) {
+        JsonArray log = new JsonArray();
+        if (existingJson != null && !existingJson.isBlank()) {
+            try {
+                log = fromJsonHelper.parse(existingJson).getAsJsonArray();
+            } catch (Exception e) {
+                log = new JsonArray();
+            }
+        }
+        final JsonObject entry = new JsonObject();
+        entry.addProperty("timestamp", Instant.now().toString());
+        entry.addProperty("action", action);
+        entry.addProperty("user", username);
+        if (note != null && !note.isBlank()) {
+            entry.addProperty("note", note);
+        }
+        log.add(entry);
+        return gson.toJson(log);
+    }
+
+    private WebApplicationException apiError(final int httpStatus, final String message) {
+        final JsonObject body = new JsonObject();
+        body.addProperty("message", message);
+        body.addProperty("defaultUserMessage", message);
+        body.addProperty("httpStatus", httpStatus);
+        final JsonArray errors = new JsonArray();
+        final JsonObject err = new JsonObject();
+        err.addProperty("defaultUserMessage", message);
+        errors.add(err);
+        body.add("errors", errors);
+        return new WebApplicationException(Response.status(httpStatus).entity(gson.toJson(body)).type(MediaType.APPLICATION_JSON).build());
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/api/ClientKycContactLogApiResource.java

@@ -0,0 +1,111 @@
+/**
+ * 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.portfolio.client.api;
+
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.core.serialization.DefaultToApiJsonSerializer;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.apache.fineract.portfolio.client.data.KycContactLogData;
+import org.apache.fineract.portfolio.client.service.KycContactLogService;
+import org.springframework.stereotype.Component;
+
+/**
+ * Customer-outreach log for KYC exceptions.
+ *
+ * <pre>
+ *   POST /v1/kyc/exceptions/{clientId}/contact-log   body: {"channel":"SMS","notes":"...","officerName":"..."}
+ *   GET  /v1/kyc/exceptions/{clientId}/contact-log
+ * </pre>
+ *
+ * <p>POST both records the attempt and — for SMS / Email / WhatsApp — sends the notice to the
+ * customer. The response carries {@code deliveryStatus} and {@code deliveryMessage} so the caller
+ * can distinguish a delivered notice from a merely-recorded one; a send failure is reported in the
+ * body with HTTP 200, not as an error, because the log row was still written.
+ *
+ * <p>No PUT or DELETE: the log is append-only evidence.
+ *
+ * <p>Authorisation reuses the client UPDATE permission — contacting a customer about their KYC is a
+ * maintenance action on that customer's record, and every KYC officer who can resolve an exception
+ * already holds it.
+ */
+@Path("/v1/kyc/exceptions/{clientId}/contact-log")
+@Component
+@Tag(name = "Client KYC Exceptions", description = "Record and send customer outreach for KYC exceptions.")
+@RequiredArgsConstructor
+public class ClientKycContactLogApiResource {
+
+    private final PlatformSecurityContext context;
+    private final KycContactLogService kycContactLogService;
+    private final DefaultToApiJsonSerializer<KycContactLogData> toApiJsonSerializer;
+
+    @POST
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Log a customer contact attempt for a KYC exception",
+            description = "Records the attempt. For channel SMS, EMAIL or WHATSAPP the notice is also transmitted to the "
+                    + "customer using the destination held on their client record. Returns the persisted log including "
+                    + "its delivery outcome.")
+    public String logContact(@PathParam("clientId") final Long clientId, final String apiRequestBodyAsJson) {
+        this.context.authenticatedUser().validateHasUpdatePermission(ClientApiConstants.CLIENT_RESOURCE_NAME);
+
+        final JsonObject payload = parse(apiRequestBodyAsJson);
+        final KycContactLogData result = this.kycContactLogService.logContact(clientId, stringOrNull(payload, "channel"),
+                stringOrNull(payload, "notes"), stringOrNull(payload, "officerName"));
+
+        return this.toApiJsonSerializer.serialize(result);
+    }
+
+    @GET
+    @Consumes(MediaType.APPLICATION_JSON)
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Retrieve the customer-contact history for a KYC exception",
+            description = "All logged outreach for this customer, oldest first.")
+    public String retrieveContactLog(@PathParam("clientId") final Long clientId) {
+        this.context.authenticatedUser().validateHasReadPermission(ClientApiConstants.CLIENT_RESOURCE_NAME);
+
+        final List<KycContactLogData> logs = this.kycContactLogService.retrieveForClient(clientId);
+        return this.toApiJsonSerializer.serialize(logs);
+    }
+
+    private JsonObject parse(final String json) {
+        if (json == null || json.isBlank()) {
+            return new JsonObject();
+        }
+        final JsonElement parsed = JsonParser.parseString(json);
+        return parsed.isJsonObject() ? parsed.getAsJsonObject() : new JsonObject();
+    }
+
+    private String stringOrNull(final JsonObject payload, final String member) {
+        final JsonElement element = payload.get(member);
+        return element == null || element.isJsonNull() ? null : element.getAsString();
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/api/ClientKycExceptionsApiResource.java

@@ -0,0 +1,73 @@
+/**
+ * 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.portfolio.client.api;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.core.serialization.DefaultToApiJsonSerializer;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.apache.fineract.portfolio.client.data.ClientKycData;
+import org.apache.fineract.portfolio.client.service.ClientKycReadPlatformService;
+import org.springframework.stereotype.Component;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import jakarta.ws.rs.QueryParam;
+
+@Path("/v1/kyc/exceptions")
+@Component
+@Tag(name = "Client KYC Exceptions", description = "Retrieve active client KYC exceptions.")
+@RequiredArgsConstructor
+public class ClientKycExceptionsApiResource {
+
+    private static final Logger LOG = LoggerFactory.getLogger(ClientKycExceptionsApiResource.class);
+
+    private final PlatformSecurityContext context;
+    private final ClientKycReadPlatformService readPlatformService;
+    private final DefaultToApiJsonSerializer<ClientKycData> toApiJsonSerializer;
+
+    @GET
+    @Consumes({ MediaType.APPLICATION_JSON })
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(summary = "Retrieve client KYC exceptions", description = "Returns the list of all clients with active or resolved KYC exceptions.")
+    public String retrieveActiveExceptions(@QueryParam("resolved") final Boolean resolved) {
+        this.context.authenticatedUser();
+        final List<ClientKycData> exceptions;
+        if (Boolean.TRUE.equals(resolved)) {
+            exceptions = this.readPlatformService.retrieveResolvedKycExceptions();
+            LOG.info("retrieveActiveExceptions: fetched {} resolved exception(s) from database", exceptions.size());
+        } else {
+            exceptions = this.readPlatformService.retrieveActiveKycExceptions();
+            LOG.info("retrieveActiveExceptions: fetched {} active exception(s) from database", exceptions.size());
+        }
+        for (ClientKycData k : exceptions) {
+            LOG.info("  -> Exception: id={}, clientId={}, clientName='{}', isException={}, exceptionResolved={}",
+                    k.getId(), k.getClientId(), k.getClientDisplayName(), k.getIsException(), k.getExceptionResolved());
+        }
+        return this.toApiJsonSerializer.serialize(exceptions);
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/command/ClientKycCommand.java

@@ -41,6 +41,9 @@ public class ClientKycCommand {
     private final Boolean verifyPan;
     private final Boolean verifyAadhaar;
     private final Boolean verifyGstin;
+    private final Boolean isException;
+    private final String exceptionReason;
+    private final Boolean exceptionResolved;
 
     // ── Aadhaar OTP flow ──────────────────────────────────────────────────────
     /** Full Aadhaar – used ONLY for OTP generation; never stored. */
@@ -54,7 +57,8 @@ public class ClientKycCommand {
             final String aadhaarNumberMasked, final String gstinNumber, final String remarks,
             final String ckycNumber, final Boolean verifyPan, final Boolean verifyAadhaar,
             final Boolean verifyGstin, final String aadhaarNumber, final String aadhaarRefNumber,
-            final String aadhaarOtp) {
+            final String aadhaarOtp, final Boolean isException, final String exceptionReason,
+            final Boolean exceptionResolved) {
         this.kycType = kycType;
         this.riskCategory = riskCategory;
         this.panNumber = panNumber;
@@ -68,6 +72,9 @@ public class ClientKycCommand {
         this.aadhaarNumber = aadhaarNumber;
         this.aadhaarRefNumber = aadhaarRefNumber;
         this.aadhaarOtp = aadhaarOtp;
+        this.isException = isException;
+        this.exceptionReason = exceptionReason;
+        this.exceptionResolved = exceptionResolved;
     }
 
     public void validateForInitiate() {
@@ -111,8 +118,9 @@ public class ClientKycCommand {
         }
 
         // At least one ID document must be provided — except for minors, who prove identity via
-        // the Birth Certificate / School ID document-type picker instead.
-        if (!skipIdentityDocumentCheck) {
+        // the Birth Certificate / School ID document-type picker instead, or if the client is marked as a KYC exception.
+        final boolean isKycException = isException != null && isException;
+        if (!skipIdentityDocumentCheck && !isKycException) {
             final boolean hasPan = panNumber != null && !panNumber.isBlank();
             final boolean hasAadhaar = aadhaarNumberMasked != null && !aadhaarNumberMasked.isBlank();
             final boolean hasGstin = gstinNumber != null && !gstinNumber.isBlank();
@@ -250,4 +258,16 @@ public class ClientKycCommand {
     public String getAadhaarRefNumber() { return aadhaarRefNumber; }
     /** OTP entered by the client. */
     public String getAadhaarOtp() { return aadhaarOtp; }
+
+    public Boolean getIsException() {
+        return isException;
+    }
+
+    public String getExceptionReason() {
+        return exceptionReason;
+    }
+
+    public Boolean getExceptionResolved() {
+        return exceptionResolved;
+    }
 }

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/data/ClientKycApiConstants.java

@@ -39,6 +39,9 @@ public final class ClientKycApiConstants {
     public static final String verifyPanParam = "verifyPan";
     public static final String verifyAadhaarParam = "verifyAadhaar";
     public static final String verifyGstinParam = "verifyGstin";
+    public static final String panVerifiedParam = "panVerified";
+    public static final String aadhaarVerifiedParam = "aadhaarVerified";
+    public static final String gstinVerifiedParam = "gstinVerified";
 
     // ── Aadhaar OTP flow parameters ───────────────────────────────────────────
     /** Full 12-digit Aadhaar – used ONLY for OTP generation; never stored per UIDAI directive. */
@@ -74,6 +77,10 @@ public final class ClientKycApiConstants {
     public static final String form15ApplicableParam = "form15Applicable";
     public static final String form15TypeParam = "form15Type";
     public static final String form15FYParam = "form15FY";
+    public static final String isExceptionParam = "isException";
+    public static final String exceptionReasonParam = "exceptionReason";
+    public static final String exceptionResolvedParam = "exceptionResolved";
+    public static final String exceptionResolvedOnParam = "exceptionResolvedOn";
 
     // ── Supported parameters for initiate/update ──────────────────────────────
     public static final Set<String> INITIATE_REQUEST_PARAMS = new HashSet<>(Arrays.asList(
@@ -83,16 +90,20 @@ public final class ClientKycApiConstants {
             kycDocumentNameParam, kycDocumentNumberParam, kycDocIssueDateParam, kycDocExpiryDateParam,
             amlCheckStatusParam, bannedEntityMatchParam, willfulDefaulterParam, ecgcSalFlagParam,
             dormantFlagParam, accountStatusParam, freezeReasonParam, freezeAuthorityParam,
-            form60TypeParam, form60DateParam, form15ApplicableParam, form15TypeParam, form15FYParam));
+            form60TypeParam, form60DateParam, form15ApplicableParam, form15TypeParam, form15FYParam,
+            isExceptionParam, exceptionReasonParam, exceptionResolvedParam, exceptionResolvedOnParam,
+            panVerifiedParam, aadhaarVerifiedParam, gstinVerifiedParam));
 
     public static final Set<String> UPDATE_REQUEST_PARAMS = new HashSet<>(Arrays.asList(
-            panNumberParam, aadhaarNumberMaskedParam, gstinNumberParam,
+            kycTypeParam, panNumberParam, aadhaarNumberMaskedParam, gstinNumberParam,
             riskCategoryParam, remarksParam, "locale", "dateFormat",
             panAadhaarSeedingStatusParam, enterprisePanParam, cinNumberParam, dinNumberParam, incorporationDateParam,
             kycDocumentNameParam, kycDocumentNumberParam, kycDocIssueDateParam, kycDocExpiryDateParam,
             amlCheckStatusParam, bannedEntityMatchParam, willfulDefaulterParam, ecgcSalFlagParam,
             dormantFlagParam, accountStatusParam, freezeReasonParam, freezeAuthorityParam,
-            form60TypeParam, form60DateParam, form15ApplicableParam, form15TypeParam, form15FYParam));
+            form60TypeParam, form60DateParam, form15ApplicableParam, form15TypeParam, form15FYParam,
+            isExceptionParam, exceptionReasonParam, exceptionResolvedParam, exceptionResolvedOnParam,
+            panVerifiedParam, aadhaarVerifiedParam, gstinVerifiedParam));
 
     /** verify command: existing flags + Aadhaar OTP fields for the verify-otp step. */
     public static final Set<String> VERIFY_REQUEST_PARAMS = new HashSet<>(Arrays.asList(

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/data/ClientKycData.java

@@ -97,10 +97,29 @@ public final class ClientKycData {
     private final LocalDate ckycUploadedOn;
     private final String ckycBatchId;
 
+    // ── Exception management ──────────────────────────────────────────────────
+    private final Boolean isException;
+    private final String exceptionReason;
+    private final Boolean exceptionResolved;
+    private final LocalDate exceptionResolvedOn;
+
     // ── Lifecycle ─────────────────────────────────────────────────────────────
     private final LocalDate initiatedOn;
     private final LocalDate verifiedOn;
     private final LocalDate rejectedOn;
     private final LocalDate expiryDate;
     private final String remarks;
+
+    private final String clientAccountNo;
+    private final String clientOfficeName;
+
+    // ── Customer contact (for KYC outreach) ──────────────────────────────────
+    // Masked only. The exceptions screen shows these so the officer knows who they are reaching,
+    // but the full values never leave the server — the send path resolves them from m_client
+    // itself, so a tampered browser cannot redirect a KYC notice to another address.
+    private final String clientMobileMasked;
+    private final String clientEmailMasked;
+    /** Whether a destination exists at all, so the UI can grey out a channel that cannot be used. */
+    private final Boolean hasMobile;
+    private final Boolean hasEmail;
 }

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/data/KycContactLogData.java

@@ -0,0 +1,64 @@
+/**
+ * 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.portfolio.client.data;
+
+import java.time.LocalDateTime;
+import lombok.Builder;
+import lombok.Getter;
+
+/**
+ * One KYC customer-contact attempt as returned to the UI.
+ *
+ * <p>{@code deliveryStatus} and {@code deliveryMessage} exist so the officer can tell a delivered
+ * notice from a failed one at a glance — the dialog shows the failure verbatim rather than a
+ * generic success toast.
+ */
+@Getter
+@Builder
+public final class KycContactLogData {
+
+    private final Long id;
+    private final Long clientId;
+    private final Long kycId;
+
+    /** Enum name, e.g. {@code SMS}. */
+    private final String channel;
+    /** Human label, e.g. {@code SMS}/{@code In-Branch Visit} — what the grid renders. */
+    private final String channelLabel;
+
+    private final String notes;
+    private final String officerName;
+    private final String exceptionReason;
+
+    /** NOT_APPLICABLE | SENT | FAILED | SKIPPED_NO_DESTINATION | PROVIDER_NOT_CONFIGURED */
+    private final String deliveryStatus;
+    /** True only for a channel that was supposed to transmit and did. */
+    private final Boolean delivered;
+    /** True when this channel transmits at all (SMS/Email/WhatsApp) vs. is recorded offline. */
+    private final Boolean platformSent;
+    /** Officer-facing sentence describing the outcome — success or the reason it failed. */
+    private final String deliveryMessage;
+
+    private final String destinationMasked;
+    private final String provider;
+    private final String providerReference;
+    private final String messageBody;
+
+    private final LocalDateTime contactedAt;
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/notification/CustomerNotificationDispatcher.java

@@ -0,0 +1,74 @@
+/**
+ * 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.portfolio.client.notification;
+
+import java.util.EnumMap;
+import java.util.List;
+import java.util.Map;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.portfolio.client.domain.KycContactChannel;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Component;
+
+/**
+ * Routes an outbound customer notice to the {@link CustomerNotificationSender} registered for its
+ * channel.
+ *
+ * <p>Senders are injected as a list and indexed by channel at startup, so a new gateway becomes
+ * available by declaring a bean — nothing here changes.
+ */
+@Component
+public class CustomerNotificationDispatcher {
+
+    private static final Logger LOG = LoggerFactory.getLogger(CustomerNotificationDispatcher.class);
+
+    private final Map<KycContactChannel, CustomerNotificationSender> sendersByChannel = new EnumMap<>(KycContactChannel.class);
+
+    public CustomerNotificationDispatcher(final List<CustomerNotificationSender> senders) {
+        for (final CustomerNotificationSender sender : senders) {
+            final CustomerNotificationSender existing = this.sendersByChannel.put(sender.getChannel(), sender);
+            if (existing != null) {
+                LOG.warn("Two senders registered for channel {} — {} replaced {}", sender.getChannel(),
+                        sender.getClass().getSimpleName(), existing.getClass().getSimpleName());
+            }
+        }
+        LOG.info("Customer notification channels available: {}", this.sendersByChannel.keySet());
+    }
+
+    /**
+     * Send on the given channel.
+     *
+     * @return the outcome; {@link CustomerNotificationResult#notConfigured} for an offline channel
+     *         or one with no registered sender. Never throws for a delivery failure.
+     */
+    public CustomerNotificationResult dispatch(final KycContactChannel channel, final Client client, final String subject,
+            final String plainBody, final String htmlBody) {
+        if (!channel.isPlatformSent()) {
+            // Caller shouldn't reach here for PHONE_CALL / visits, but guard rather than send.
+            return CustomerNotificationResult.notConfigured(null, "Channel " + channel + " is recorded offline, not transmitted");
+        }
+        final CustomerNotificationSender sender = this.sendersByChannel.get(channel);
+        if (sender == null) {
+            LOG.warn("No sender registered for channel {} — notice to client {} not transmitted.", channel, client.getId());
+            return CustomerNotificationResult.notConfigured(null, "No gateway is registered for " + channel);
+        }
+        return sender.send(client, subject, plainBody, htmlBody);
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/notification/CustomerNotificationResult.java

@@ -0,0 +1,51 @@
+/**
+ * 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.portfolio.client.notification;
+
+import org.apache.fineract.portfolio.client.domain.KycContactDeliveryStatus;
+
+/**
+ * What a {@link CustomerNotificationSender} did. Senders never throw for a delivery failure — they
+ * return a {@code FAILED} result — so that a gateway outage still produces a persisted contact-log
+ * row rather than losing the officer's notes to a rolled-back transaction.
+ */
+public record CustomerNotificationResult(KycContactDeliveryStatus status, String destinationMasked, String provider,
+        String providerReference, String failureReason) {
+
+    public static CustomerNotificationResult sent(final String destinationMasked, final String provider, final String reference) {
+        return new CustomerNotificationResult(KycContactDeliveryStatus.SENT, destinationMasked, provider, reference, null);
+    }
+
+    public static CustomerNotificationResult failed(final String destinationMasked, final String provider, final String reason) {
+        return new CustomerNotificationResult(KycContactDeliveryStatus.FAILED, destinationMasked, provider, null, reason);
+    }
+
+    public static CustomerNotificationResult noDestination(final String provider) {
+        return new CustomerNotificationResult(KycContactDeliveryStatus.SKIPPED_NO_DESTINATION, null, provider, null,
+                "Customer has no destination on file for this channel");
+    }
+
+    public static CustomerNotificationResult notConfigured(final String provider, final String reason) {
+        return new CustomerNotificationResult(KycContactDeliveryStatus.PROVIDER_NOT_CONFIGURED, null, provider, null, reason);
+    }
+
+    public boolean isDelivered() {
+        return this.status.isDelivered();
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/notification/CustomerNotificationSender.java

@@ -0,0 +1,46 @@
+/**
+ * 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.portfolio.client.notification;
+
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.portfolio.client.domain.KycContactChannel;
+
+/**
+ * Transport for one outbound customer channel.
+ *
+ * <p>Implementations are discovered by Spring and matched to a channel via {@link #getChannel()},
+ * so adding a gateway means adding a bean — no dispatcher edit. Each implementation is responsible
+ * for resolving the destination off the {@link Client} itself; callers never pass a destination in,
+ * which keeps a browser from being able to redirect a KYC notice to an arbitrary address.
+ *
+ * <p>Contract: never throw for a delivery problem. Return
+ * {@link CustomerNotificationResult#failed} instead, so the officer's contact log still persists.
+ */
+public interface CustomerNotificationSender {
+
+    KycContactChannel getChannel();
+
+    /**
+     * @param client the customer to reach; the destination is read off this record
+     * @param subject short title — used by channels that have one (email), ignored by those that don't
+     * @param plainBody the message as plain text; SMS/WhatsApp send this verbatim
+     * @param htmlBody rich rendering for channels that support it; may be null
+     */
+    CustomerNotificationResult send(Client client, String subject, String plainBody, String htmlBody);
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/notification/EmailCustomerNotificationSender.java

@@ -0,0 +1,81 @@
+/**
+ * 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.portfolio.client.notification;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.email.service.EmailSenderService;
+import org.apache.fineract.infrastructure.security.otp.util.OtpDestinationMasker;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.portfolio.client.domain.KycContactChannel;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Component;
+
+/**
+ * Email delivery via {@link EmailSenderService} — the direct-SMTP path configured from this app's
+ * own {@code spring.mail.*} properties, the same one already used for OTP emails and client-change
+ * alerts.
+ *
+ * <p>Deliberately not {@code PlatformEmailService}: that resolves SMTP credentials from the
+ * DB-backed "external services" table used by the campaign pipeline, which is a separate and
+ * typically unconfigured surface in this deployment.
+ */
+@Component
+public class EmailCustomerNotificationSender implements CustomerNotificationSender {
+
+    private static final Logger LOG = LoggerFactory.getLogger(EmailCustomerNotificationSender.class);
+    private static final String PROVIDER = "SMTP";
+
+    private final EmailSenderService emailSenderService;
+
+    public EmailCustomerNotificationSender(final EmailSenderService emailSenderService) {
+        this.emailSenderService = emailSenderService;
+    }
+
+    @Override
+    public KycContactChannel getChannel() {
+        return KycContactChannel.EMAIL;
+    }
+
+    @Override
+    public CustomerNotificationResult send(final Client client, final String subject, final String plainBody, final String htmlBody) {
+        final String to = client.getEmailAddress();
+        if (StringUtils.isBlank(to)) {
+            LOG.warn("KYC contact email skipped — client {} has no email address on file.", client.getId());
+            return CustomerNotificationResult.noDestination(PROVIDER);
+        }
+
+        final String masked = OtpDestinationMasker.maskEmail(to);
+        try {
+            final boolean accepted = StringUtils.isNotBlank(htmlBody)
+                    ? this.emailSenderService.sendHtml(to, subject, htmlBody)
+                    : this.emailSenderService.sendText(to, subject, plainBody);
+
+            if (accepted) {
+                LOG.info("KYC contact email sent to client {} at {}", client.getId(), masked);
+                return CustomerNotificationResult.sent(masked, PROVIDER, null);
+            }
+            LOG.warn("KYC contact email rejected by SMTP for client {} at {}", client.getId(), masked);
+            return CustomerNotificationResult.failed(masked, PROVIDER, "SMTP rejected the message");
+        } catch (final Exception e) {
+            LOG.error("KYC contact email failed for client {} at {}", client.getId(), masked, e);
+            return CustomerNotificationResult.failed(masked, PROVIDER, e.getMessage());
+        }
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/notification/RestGatewayNotificationSender.java

@@ -0,0 +1,213 @@
+/**
+ * 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.portfolio.client.notification;
+
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.slf4j.Logger;
+import org.springframework.http.HttpEntity;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.client.RestTemplate;
+
+/**
+ * Shared HTTP plumbing for the SMS and WhatsApp gateways.
+ *
+ * <p><b>Why this is template-driven rather than one class per vendor.</b> Indian SMS/WhatsApp
+ * gateways (MSG91, Gupshup, Kaleyra, Twilio, LincPay, …) all expose the same shape — POST a
+ * destination plus a body to a URL with a static API key — but disagree on field names, auth header,
+ * and whether the payload is JSON or form-encoded. Encoding those three differences as properties
+ * means switching or adding a vendor is a config change, not a code change, and no vendor's
+ * credentials end up hard-coded in the repo.
+ *
+ * <p>The body template supports these placeholders, substituted with correct escaping for the
+ * configured content type:
+ * <ul>
+ *   <li>{@code {{destination}}} — the customer's mobile number</li>
+ *   <li>{@code {{message}}} — the notice text</li>
+ *   <li>{@code {{senderId}}} — the DLT-registered sender ID / WhatsApp source number</li>
+ *   <li>{@code {{templateId}}} — the DLT / WhatsApp template ID, where the vendor requires one</li>
+ * </ul>
+ *
+ * <p>TRAI's DLT regime means a transactional SMS to an Indian number is only accepted when the body
+ * matches a pre-registered template, so {@code templateId} is exposed even though not every vendor
+ * needs it.
+ */
+abstract class RestGatewayNotificationSender implements CustomerNotificationSender {
+
+    private final RestTemplate restTemplate = new RestTemplate();
+
+    protected abstract Logger log();
+
+    /** Human-readable gateway name recorded on the contact log (e.g. {@code MSG91}). */
+    protected abstract String providerName();
+
+    protected abstract boolean isEnabled();
+
+    protected abstract String baseUrl();
+
+    protected abstract String path();
+
+    protected abstract String authHeaderName();
+
+    protected abstract String authHeaderValue();
+
+    protected abstract String contentType();
+
+    protected abstract String bodyTemplate();
+
+    protected abstract String senderId();
+
+    protected abstract String templateId();
+
+    /**
+     * Dotted path into the JSON response holding the vendor's message ID (e.g.
+     * {@code data.messageId}). Blank when the vendor returns no usable reference.
+     */
+    protected abstract String referenceJsonPath();
+
+    /** Resolve the customer's destination for this channel off the client record. */
+    protected abstract String resolveDestination(Client client);
+
+    /** Mask the destination for storage and logging. */
+    protected abstract String maskDestination(String destination);
+
+    @Override
+    public CustomerNotificationResult send(final Client client, final String subject, final String plainBody, final String htmlBody) {
+        final String provider = providerName();
+
+        if (!isEnabled()) {
+            log().warn("{} notice not sent for client {} — channel disabled in configuration.", provider, client.getId());
+            return CustomerNotificationResult.notConfigured(provider,
+                    "Channel is disabled — set the corresponding fineract.notification.*.enabled property to true");
+        }
+        if (StringUtils.isBlank(baseUrl()) || StringUtils.isBlank(authHeaderValue())) {
+            log().warn("{} notice not sent for client {} — gateway URL or credential missing.", provider, client.getId());
+            return CustomerNotificationResult.notConfigured(provider, "Gateway base-url or API credential is not configured");
+        }
+
+        final String destination = resolveDestination(client);
+        if (StringUtils.isBlank(destination)) {
+            log().warn("{} notice skipped — client {} has no destination on file for this channel.", provider, client.getId());
+            return CustomerNotificationResult.noDestination(provider);
+        }
+
+        final String masked = maskDestination(destination);
+        final boolean json = !MediaType.APPLICATION_FORM_URLENCODED_VALUE.equalsIgnoreCase(contentType());
+        final String payload = renderBody(destination, plainBody, json);
+
+        try {
+            final HttpHeaders headers = new HttpHeaders();
+            headers.setContentType(MediaType.parseMediaType(contentType()));
+            if (StringUtils.isNotBlank(authHeaderName())) {
+                headers.set(authHeaderName(), authHeaderValue());
+            }
+
+            final String base = baseUrl().endsWith("/") ? baseUrl().substring(0, baseUrl().length() - 1) : baseUrl();
+            final String url = base + path();
+            final ResponseEntity<String> response = this.restTemplate.postForEntity(url, new HttpEntity<>(payload, headers), String.class);
+
+            if (response.getStatusCode().is2xxSuccessful()) {
+                final String reference = extractReference(response.getBody());
+                log().info("{} notice sent to client {} at {} (ref={})", provider, client.getId(), masked, reference);
+                return CustomerNotificationResult.sent(masked, provider, reference);
+            }
+            // Non-2xx without an exception is unusual for RestTemplate but treat it as a failure
+            // rather than assuming delivery — an over-optimistic SENT would corrupt the audit trail.
+            log().warn("{} notice rejected for client {} at {} — HTTP {}", provider, client.getId(), masked, response.getStatusCode());
+            return CustomerNotificationResult.failed(masked, provider, "Gateway returned HTTP " + response.getStatusCode());
+        } catch (final Exception e) {
+            log().error("{} notice failed for client {} at {}", provider, client.getId(), masked, e);
+            return CustomerNotificationResult.failed(masked, provider, e.getMessage());
+        }
+    }
+
+    /**
+     * Substitute the placeholders, escaping each value for the target encoding. Escaping happens per
+     * value rather than on the finished string so that a message containing a quote or an ampersand
+     * cannot break out of its field and corrupt the request.
+     */
+    private String renderBody(final String destination, final String message, final boolean json) {
+        String body = bodyTemplate();
+        body = body.replace("{{destination}}", escape(destination, json));
+        body = body.replace("{{message}}", escape(message, json));
+        body = body.replace("{{senderId}}", escape(StringUtils.defaultString(senderId()), json));
+        body = body.replace("{{templateId}}", escape(StringUtils.defaultString(templateId()), json));
+        return body;
+    }
+
+    private static String escape(final String value, final boolean json) {
+        if (value == null) {
+            return "";
+        }
+        if (!json) {
+            return URLEncoder.encode(value, StandardCharsets.UTF_8);
+        }
+        final StringBuilder out = new StringBuilder(value.length() + 16);
+        for (int i = 0; i < value.length(); i++) {
+            final char c = value.charAt(i);
+            switch (c) {
+                case '"' -> out.append("\\\"");
+                case '\\' -> out.append("\\\\");
+                case '\n' -> out.append("\\n");
+                case '\r' -> out.append("\\r");
+                case '\t' -> out.append("\\t");
+                default -> {
+                    if (c < 0x20) {
+                        out.append(String.format("\\u%04x", (int) c));
+                    } else {
+                        out.append(c);
+                    }
+                }
+            }
+        }
+        return out.toString();
+    }
+
+    /** Walk {@link #referenceJsonPath()} through the response body; null if absent or unparseable. */
+    private String extractReference(final String responseBody) {
+        final String jsonPath = referenceJsonPath();
+        if (StringUtils.isBlank(jsonPath) || StringUtils.isBlank(responseBody)) {
+            return null;
+        }
+        try {
+            JsonElement node = JsonParser.parseString(responseBody);
+            for (final String segment : jsonPath.split("\\.")) {
+                if (node == null || !node.isJsonObject()) {
+                    return null;
+                }
+                final JsonObject object = node.getAsJsonObject();
+                if (!object.has(segment)) {
+                    return null;
+                }
+                node = object.get(segment);
+            }
+            return node != null && node.isJsonPrimitive() ? node.getAsString() : null;
+        } catch (final Exception e) {
+            log().debug("Could not read reference '{}' from {} response", jsonPath, providerName(), e);
+            return null;
+        }
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/notification/SmsCustomerNotificationSender.java

@@ -0,0 +1,151 @@
+/**
+ * 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.portfolio.client.notification;
+
+import org.apache.fineract.infrastructure.security.otp.util.OtpDestinationMasker;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.portfolio.client.domain.KycContactChannel;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+/**
+ * Plain-text SMS via the configured gateway. See {@link RestGatewayNotificationSender} for why the
+ * request shape is property-driven.
+ *
+ * <p>Note this is a <em>separate</em> gateway from the LincPay eKYC endpoints already configured
+ * for login OTP ({@code /mobile/generate-otp}). That endpoint generates and delivers an OTP of
+ * LincPay's own choosing; it cannot carry an arbitrary message, and routing a KYC notice through it
+ * would mint a real, verifiable OTP the customer never requested. Configure a genuine
+ * send-message endpoint here.
+ */
+@Component
+public class SmsCustomerNotificationSender extends RestGatewayNotificationSender {
+
+    private static final Logger LOG = LoggerFactory.getLogger(SmsCustomerNotificationSender.class);
+
+    @Value("${fineract.notification.sms.enabled:false}")
+    private boolean enabled;
+
+    @Value("${fineract.notification.sms.provider:SMS_GATEWAY}")
+    private String provider;
+
+    @Value("${fineract.notification.sms.base-url:}")
+    private String baseUrl;
+
+    @Value("${fineract.notification.sms.path:}")
+    private String path;
+
+    @Value("${fineract.notification.sms.auth-header-name:Authorization}")
+    private String authHeaderName;
+
+    @Value("${fineract.notification.sms.auth-header-value:}")
+    private String authHeaderValue;
+
+    @Value("${fineract.notification.sms.content-type:application/json}")
+    private String contentType;
+
+    @Value("${fineract.notification.sms.body-template:}")
+    private String bodyTemplate;
+
+    @Value("${fineract.notification.sms.sender-id:}")
+    private String senderId;
+
+    @Value("${fineract.notification.sms.template-id:}")
+    private String templateId;
+
+    @Value("${fineract.notification.sms.reference-json-path:}")
+    private String referenceJsonPath;
+
+    @Override
+    public KycContactChannel getChannel() {
+        return KycContactChannel.SMS;
+    }
+
+    @Override
+    protected Logger log() {
+        return LOG;
+    }
+
+    @Override
+    protected String providerName() {
+        return this.provider;
+    }
+
+    @Override
+    protected boolean isEnabled() {
+        return this.enabled;
+    }
+
+    @Override
+    protected String baseUrl() {
+        return this.baseUrl;
+    }
+
+    @Override
+    protected String path() {
+        return this.path;
+    }
+
+    @Override
+    protected String authHeaderName() {
+        return this.authHeaderName;
+    }
+
+    @Override
+    protected String authHeaderValue() {
+        return this.authHeaderValue;
+    }
+
+    @Override
+    protected String contentType() {
+        return this.contentType;
+    }
+
+    @Override
+    protected String bodyTemplate() {
+        return this.bodyTemplate;
+    }
+
+    @Override
+    protected String senderId() {
+        return this.senderId;
+    }
+
+    @Override
+    protected String templateId() {
+        return this.templateId;
+    }
+
+    @Override
+    protected String referenceJsonPath() {
+        return this.referenceJsonPath;
+    }
+
+    @Override
+    protected String resolveDestination(final Client client) {
+        return client.getMobileNo();
+    }
+
+    @Override
+    protected String maskDestination(final String destination) {
+        return OtpDestinationMasker.maskMobile(destination);
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/notification/WhatsAppCustomerNotificationSender.java

@@ -0,0 +1,179 @@
+/**
+ * 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.portfolio.client.notification;
+
+import org.apache.fineract.infrastructure.security.otp.util.OtpDestinationMasker;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.portfolio.client.domain.KycContactChannel;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+/**
+ * WhatsApp Business delivery via the configured gateway (Meta Cloud API, Gupshup, Twilio, …).
+ *
+ * <p>Reuses the customer's registered mobile number as the WhatsApp destination — banks do not
+ * capture a separate WhatsApp handle, and the Business API is keyed on the phone number anyway.
+ * Most providers want it in E.164 form, so {@code fineract.notification.whatsapp.country-code} is
+ * prefixed to bare 10-digit Indian numbers.
+ *
+ * <p>Meta's policy only permits business-initiated messages against an approved template outside the
+ * 24-hour customer service window, which a KYC exception notice always is — so
+ * {@code template-id} will normally need to be set alongside a template-shaped body.
+ */
+@Component
+public class WhatsAppCustomerNotificationSender extends RestGatewayNotificationSender {
+
+    private static final Logger LOG = LoggerFactory.getLogger(WhatsAppCustomerNotificationSender.class);
+
+    @Value("${fineract.notification.whatsapp.enabled:false}")
+    private boolean enabled;
+
+    @Value("${fineract.notification.whatsapp.provider:WHATSAPP_GATEWAY}")
+    private String provider;
+
+    @Value("${fineract.notification.whatsapp.base-url:}")
+    private String baseUrl;
+
+    @Value("${fineract.notification.whatsapp.path:}")
+    private String path;
+
+    @Value("${fineract.notification.whatsapp.auth-header-name:Authorization}")
+    private String authHeaderName;
+
+    @Value("${fineract.notification.whatsapp.auth-header-value:}")
+    private String authHeaderValue;
+
+    @Value("${fineract.notification.whatsapp.content-type:application/json}")
+    private String contentType;
+
+    @Value("${fineract.notification.whatsapp.body-template:}")
+    private String bodyTemplate;
+
+    @Value("${fineract.notification.whatsapp.sender-id:}")
+    private String senderId;
+
+    @Value("${fineract.notification.whatsapp.template-id:}")
+    private String templateId;
+
+    @Value("${fineract.notification.whatsapp.reference-json-path:}")
+    private String referenceJsonPath;
+
+    /** Prefixed to bare national numbers to reach E.164. Blank disables normalisation. */
+    @Value("${fineract.notification.whatsapp.country-code:91}")
+    private String countryCode;
+
+    @Override
+    public KycContactChannel getChannel() {
+        return KycContactChannel.WHATSAPP;
+    }
+
+    @Override
+    protected Logger log() {
+        return LOG;
+    }
+
+    @Override
+    protected String providerName() {
+        return this.provider;
+    }
+
+    @Override
+    protected boolean isEnabled() {
+        return this.enabled;
+    }
+
+    @Override
+    protected String baseUrl() {
+        return this.baseUrl;
+    }
+
+    @Override
+    protected String path() {
+        return this.path;
+    }
+
+    @Override
+    protected String authHeaderName() {
+        return this.authHeaderName;
+    }
+
+    @Override
+    protected String authHeaderValue() {
+        return this.authHeaderValue;
+    }
+
+    @Override
+    protected String contentType() {
+        return this.contentType;
+    }
+
+    @Override
+    protected String bodyTemplate() {
+        return this.bodyTemplate;
+    }
+
+    @Override
+    protected String senderId() {
+        return this.senderId;
+    }
+
+    @Override
+    protected String templateId() {
+        return this.templateId;
+    }
+
+    @Override
+    protected String referenceJsonPath() {
+        return this.referenceJsonPath;
+    }
+
+    @Override
+    protected String resolveDestination(final Client client) {
+        return toE164(client.getMobileNo());
+    }
+
+    @Override
+    protected String maskDestination(final String destination) {
+        return OtpDestinationMasker.maskMobile(destination);
+    }
+
+    /**
+     * Strip formatting and prefix the country code when the number is stored nationally. A number
+     * that already carries a country code (leading {@code +}, or longer than 10 digits) is passed
+     * through so we never double-prefix.
+     */
+    private String toE164(final String mobileNo) {
+        if (mobileNo == null || mobileNo.isBlank()) {
+            return null;
+        }
+        final String digits = mobileNo.replaceAll("[^0-9+]", "");
+        if (digits.isBlank()) {
+            return null;
+        }
+        if (digits.startsWith("+")) {
+            return digits.substring(1);
+        }
+        if (this.countryCode == null || this.countryCode.isBlank() || digits.length() > 10) {
+            return digits;
+        }
+        return this.countryCode + digits;
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/serialization/ClientKycCommandFromApiJsonDeserializer.java

@@ -76,8 +76,16 @@ public class ClientKycCommandFromApiJsonDeserializer {
         final String aadhaarOtp = this.fromApiJsonHelper.extractStringNamed(
                 ClientKycApiConstants.aadhaarOtpParam, element);
 
+        final Boolean isException = this.fromApiJsonHelper.extractBooleanNamed(
+                ClientKycApiConstants.isExceptionParam, element);
+        final String exceptionReason = this.fromApiJsonHelper.extractStringNamed(
+                ClientKycApiConstants.exceptionReasonParam, element);
+        final Boolean exceptionResolved = this.fromApiJsonHelper.extractBooleanNamed(
+                ClientKycApiConstants.exceptionResolvedParam, element);
+
         return new ClientKycCommand(kycType, riskCategory, panNumber, aadhaarNumberMasked,
                 gstinNumber, remarks, ckycNumber, verifyPan, verifyAadhaar, verifyGstin,
-                aadhaarNumber, aadhaarRefNumber, aadhaarOtp);
+                aadhaarNumber, aadhaarRefNumber, aadhaarOtp, isException, exceptionReason,
+                exceptionResolved);
     }
 }

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/service/ClientKycReadPlatformService.java

@@ -31,4 +31,8 @@ public interface ClientKycReadPlatformService {
      * Retrieve the KYC record for a client.
      */
     ClientKycData retrieveClientKycByClientId(Long clientId);
+
+    java.util.List<ClientKycData> retrieveActiveKycExceptions();
+
+    java.util.List<ClientKycData> retrieveResolvedKycExceptions();
 }

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/service/ClientKycReadPlatformServiceImpl.java

@@ -19,6 +19,8 @@
 package org.apache.fineract.portfolio.client.service;
 
 import lombok.RequiredArgsConstructor;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.security.otp.util.OtpDestinationMasker;
 import org.apache.fineract.portfolio.client.data.ClientKycData;
 import org.apache.fineract.portfolio.client.domain.ClientKyc;
 import org.apache.fineract.portfolio.client.domain.ClientKycRepository;
@@ -55,10 +57,19 @@ public class ClientKycReadPlatformServiceImpl implements ClientKycReadPlatformSe
         final ClientKycType type = ClientKycType.fromInt(kyc.getKycTypeValue());
         final KycRiskCategory risk = KycRiskCategory.fromInt(kyc.getRiskCategoryValue());
 
+        final String mobileNo = kyc.getClient().getMobileNo();
+        final String emailAddress = kyc.getClient().getEmailAddress();
+
         return ClientKycData.builder()
                 .id(kyc.getId())
                 .clientId(kyc.getClient().getId())
                 .clientDisplayName(kyc.getClient().getDisplayName())
+                .clientAccountNo(kyc.getClient().getAccountNumber())
+                .clientOfficeName(kyc.getClient().getOffice().getName())
+                .clientMobileMasked(StringUtils.isNotBlank(mobileNo) ? OtpDestinationMasker.maskMobile(mobileNo) : null)
+                .clientEmailMasked(StringUtils.isNotBlank(emailAddress) ? OtpDestinationMasker.maskEmail(emailAddress) : null)
+                .hasMobile(StringUtils.isNotBlank(mobileNo))
+                .hasEmail(StringUtils.isNotBlank(emailAddress))
                 .kycStatus(status.getValue())
                 .kycStatusCode(status.getCode())
                 .kycType(type.getValue())
@@ -103,6 +114,10 @@ public class ClientKycReadPlatformServiceImpl implements ClientKycReadPlatformSe
                 .ckycNumber(kyc.getCkycNumber())
                 .ckycUploadedOn(kyc.getCkycUploadedOn())
                 .ckycBatchId(kyc.getCkycBatchId())
+                .isException(kyc.getIsException())
+                .exceptionReason(kyc.getExceptionReason())
+                .exceptionResolved(kyc.getExceptionResolved())
+                .exceptionResolvedOn(kyc.getExceptionResolvedOn())
                 .initiatedOn(kyc.getInitiatedOn())
                 .verifiedOn(kyc.getVerifiedOn())
                 .rejectedOn(kyc.getRejectedOn())
@@ -110,4 +125,18 @@ public class ClientKycReadPlatformServiceImpl implements ClientKycReadPlatformSe
                 .remarks(kyc.getRemarks())
                 .build();
     }
+
+    @Override
+    public java.util.List<ClientKycData> retrieveActiveKycExceptions() {
+        return this.kycRepository.findByIsExceptionTrueAndExceptionResolvedFalse().stream()
+                .map(this::toData)
+                .collect(java.util.stream.Collectors.toList());
+    }
+
+    @Override
+    public java.util.List<ClientKycData> retrieveResolvedKycExceptions() {
+        return this.kycRepository.findByExceptionResolvedTrue().stream()
+                .map(this::toData)
+                .collect(java.util.stream.Collectors.toList());
+    }
 }

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/service/KycContactLogService.java

@@ -0,0 +1,47 @@
+/**
+ * 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.portfolio.client.service;
+
+import java.util.List;
+import org.apache.fineract.portfolio.client.data.KycContactLogData;
+
+/**
+ * Records — and, for the sending channels, actually transmits — a KYC officer's outreach to a
+ * customer with an open KYC exception.
+ */
+public interface KycContactLogService {
+
+    /**
+     * Log one contact attempt. For {@code SMS}/{@code EMAIL}/{@code WHATSAPP} this also sends the
+     * notice to the customer; for the offline channels it only records what the officer already did.
+     *
+     * <p>The log row is persisted whether or not delivery succeeded — a gateway outage must not
+     * discard the officer's notes.
+     *
+     * @param clientId customer the exception belongs to
+     * @param rawChannel channel as submitted by the UI (label or enum name)
+     * @param notes officer's summary; mandatory
+     * @param officerName officer selected in the dialog
+     * @return the persisted log, including its delivery outcome
+     */
+    KycContactLogData logContact(Long clientId, String rawChannel, String notes, String officerName);
+
+    /** All contact attempts for one customer, oldest first. */
+    List<KycContactLogData> retrieveForClient(Long clientId);
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/client/service/KycContactLogServiceImpl.java

@@ -0,0 +1,206 @@
+/**
+ * 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.portfolio.client.service;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.core.exception.PlatformApiDataValidationException;
+import org.apache.fineract.infrastructure.core.data.ApiParameterError;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
+import org.apache.fineract.infrastructure.email.service.EmailTemplateService;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.apache.fineract.portfolio.client.data.KycContactLogData;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.portfolio.client.domain.ClientKyc;
+import org.apache.fineract.portfolio.client.domain.ClientKycContactLog;
+import org.apache.fineract.portfolio.client.domain.ClientKycContactLogRepository;
+import org.apache.fineract.portfolio.client.domain.ClientKycRepository;
+import org.apache.fineract.portfolio.client.domain.ClientRepositoryWrapper;
+import org.apache.fineract.portfolio.client.domain.KycContactChannel;
+import org.apache.fineract.portfolio.client.domain.KycContactDeliveryStatus;
+import org.apache.fineract.portfolio.client.notification.CustomerNotificationDispatcher;
+import org.apache.fineract.portfolio.client.notification.CustomerNotificationResult;
+import org.apache.fineract.useradministration.domain.AppUser;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+@Service
+public class KycContactLogServiceImpl implements KycContactLogService {
+
+    private static final Logger LOG = LoggerFactory.getLogger(KycContactLogServiceImpl.class);
+
+    private static final int NOTES_MAX_LENGTH = 1000;
+
+    @Value("${fineract.email.from-name:CBSnexora}")
+    private String bankName;
+
+    /** Days the customer is given to act, quoted in the notice body. */
+    @Value("${fineract.notification.kyc-contact.response-days:15}")
+    private int responseDays;
+
+    private final ClientRepositoryWrapper clientRepositoryWrapper;
+    private final ClientKycRepository kycRepository;
+    private final ClientKycContactLogRepository contactLogRepository;
+    private final CustomerNotificationDispatcher dispatcher;
+    private final EmailTemplateService emailTemplateService;
+    private final PlatformSecurityContext context;
+
+    public KycContactLogServiceImpl(final ClientRepositoryWrapper clientRepositoryWrapper, final ClientKycRepository kycRepository,
+            final ClientKycContactLogRepository contactLogRepository, final CustomerNotificationDispatcher dispatcher,
+            final EmailTemplateService emailTemplateService, final PlatformSecurityContext context) {
+        this.clientRepositoryWrapper = clientRepositoryWrapper;
+        this.kycRepository = kycRepository;
+        this.contactLogRepository = contactLogRepository;
+        this.dispatcher = dispatcher;
+        this.emailTemplateService = emailTemplateService;
+        this.context = context;
+    }
+
+    @Override
+    @Transactional
+    public KycContactLogData logContact(final Long clientId, final String rawChannel, final String notes, final String officerName) {
+        final KycContactChannel channel = KycContactChannel.fromString(rawChannel);
+        if (channel == null) {
+            throw validationError("channel", "Unrecognised contact channel: " + rawChannel);
+        }
+        if (StringUtils.isBlank(notes)) {
+            throw validationError("notes", "A summary of the contact is required.");
+        }
+
+        final Client client = this.clientRepositoryWrapper.findOneWithNotFoundDetection(clientId);
+        final ClientKyc kyc = this.kycRepository.findByClientId(clientId).orElse(null);
+        final String exceptionReason = kyc != null ? kyc.getExceptionReason() : null;
+
+        final AppUser currentUser = this.context.authenticatedUser();
+        final LocalDateTime now = LocalDateTime.now(DateUtils.getDateTimeZoneOfTenant());
+
+        final ClientKycContactLog log = new ClientKycContactLog(client, kyc != null ? kyc.getId() : null, channel,
+                StringUtils.abbreviate(notes.trim(), NOTES_MAX_LENGTH), officerName,
+                currentUser != null ? currentUser.getId() : null, exceptionReason, now);
+
+        if (channel.isPlatformSent()) {
+            final String subject = "Action Required: KYC Verification Pending - " + this.bankName;
+            final String plainBody = buildPlainBody(client, exceptionReason, channel);
+            // Only email renders HTML; SMS/WhatsApp take the plain text and would show markup verbatim.
+            final String htmlBody = channel == KycContactChannel.EMAIL
+                    ? this.emailTemplateService.renderAlert(displayName(client), "KYC Verification Pending", plainBody)
+                    : null;
+
+            final CustomerNotificationResult result = this.dispatcher.dispatch(channel, client, subject, plainBody, htmlBody);
+            log.recordDeliveryOutcome(result.status(), result.destinationMasked(), result.provider(), result.providerReference(),
+                    result.failureReason(), plainBody);
+
+            if (!result.isDelivered()) {
+                // Logged, not thrown: the officer's notes are still worth persisting, and the UI
+                // surfaces the failure so nobody assumes the customer was reached.
+                LOG.warn("KYC contact notice to client {} via {} was not delivered — status={}, reason={}", clientId, channel,
+                        result.status(), result.failureReason());
+            }
+        }
+
+        final ClientKycContactLog saved = this.contactLogRepository.saveAndFlush(log);
+        return toData(saved);
+    }
+
+    @Override
+    @Transactional(readOnly = true)
+    public List<KycContactLogData> retrieveForClient(final Long clientId) {
+        return this.contactLogRepository.findByClientIdOrderByContactedAtAsc(clientId).stream().map(this::toData).toList();
+    }
+
+    /**
+     * The notice text. Kept short and channel-aware because an SMS over 160 GSM-7 characters is
+     * billed and delivered as multiple segments; email can afford the longer framing but reuses the
+     * same sentence so the audit trail shows one consistent message across channels.
+     */
+    private String buildPlainBody(final Client client, final String exceptionReason, final KycContactChannel channel) {
+        final String reason = StringUtils.isNotBlank(exceptionReason) ? exceptionReason : "KYC verification is incomplete";
+
+        if (channel == KycContactChannel.SMS) {
+            return "Dear " + displayName(client) + ", your KYC is pending: " + reason + ". Please visit your branch with valid "
+                    + "documents within " + this.responseDays + " days to avoid account restrictions. - " + this.bankName;
+        }
+        return "Dear " + displayName(client) + ", our records show that your KYC (Know Your Customer) verification is pending "
+                + "for the following reason: " + reason + ". As required by the Reserve Bank of India's KYC Master Direction, "
+                + "please visit your home branch with valid identity and address documents within " + this.responseDays
+                + " days. If this is not completed, operations on your account may be restricted. "
+                + "If you have already submitted these documents, please ignore this message. - " + this.bankName;
+    }
+
+    private KycContactLogData toData(final ClientKycContactLog log) {
+        final KycContactChannel channel = log.getChannel();
+        final KycContactDeliveryStatus status = log.getDeliveryStatus();
+
+        return KycContactLogData.builder()
+                .id(log.getId())
+                .clientId(log.getClient().getId())
+                .kycId(log.getKycId())
+                .channel(channel.name())
+                .channelLabel(channel.getDisplayLabel())
+                .notes(log.getNotes())
+                .officerName(log.getOfficerName())
+                .exceptionReason(log.getExceptionReason())
+                .deliveryStatus(status.name())
+                .delivered(status.isDelivered())
+                .platformSent(channel.isPlatformSent())
+                .deliveryMessage(describeDelivery(channel, status, log.getDestinationMasked(), log.getFailureReason()))
+                .destinationMasked(log.getDestinationMasked())
+                .provider(log.getProvider())
+                .providerReference(log.getProviderReference())
+                .messageBody(log.getMessageBody())
+                .contactedAt(log.getContactedAt())
+                .build();
+    }
+
+    /** Officer-facing outcome sentence. Failures name the cause so the next action is obvious. */
+    private String describeDelivery(final KycContactChannel channel, final KycContactDeliveryStatus status, final String destination,
+            final String failureReason) {
+        return switch (status) {
+            case NOT_APPLICABLE -> channel.getDisplayLabel() + " recorded.";
+            case SENT -> channel.getDisplayLabel() + " sent to " + (StringUtils.isNotBlank(destination) ? destination : "the customer")
+                    + ".";
+            case SKIPPED_NO_DESTINATION -> "Not sent — the customer has no "
+                    + (channel == KycContactChannel.EMAIL ? "email address" : "mobile number") + " on file.";
+            case PROVIDER_NOT_CONFIGURED -> "Not sent — no " + channel.getDisplayLabel()
+                    + " gateway is configured. The attempt has been logged.";
+            case FAILED -> "Not sent — the gateway rejected the message"
+                    + (StringUtils.isNotBlank(failureReason) ? " (" + failureReason + ")" : "") + ". The attempt has been logged.";
+        };
+    }
+
+    private String displayName(final Client client) {
+        if (StringUtils.isNotBlank(client.getFirstname())) {
+            return client.getFirstname();
+        }
+        if (StringUtils.isNotBlank(client.getDisplayName())) {
+            return client.getDisplayName();
+        }
+        return "Customer";
+    }
+
+    private PlatformApiDataValidationException validationError(final String parameter, final String message) {
+        final ApiParameterError error = ApiParameterError.parameterError("validation.msg.kyc.contact.log." + parameter + ".invalid",
+                message, parameter);
+        return new PlatformApiDataValidationException(List.of(error));
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/api/ShareAccountSummaryApiResource.java

@@ -0,0 +1,46 @@
+package org.apache.fineract.portfolio.shareaccounts.api;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+import java.util.Collection;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.apache.fineract.portfolio.shareaccounts.data.ShareAccountClientSummaryData;
+import org.apache.fineract.portfolio.shareaccounts.service.ShareAccountReadPlatformService;
+import org.springframework.stereotype.Component;
+
+@Path("/v1/shareaccounts/summary")
+@Component
+@Tag(name = "Share Account Summary", description = "Provides a highly optimized summary of all share accounts linked with their respective clients.")
+@RequiredArgsConstructor
+public class ShareAccountSummaryApiResource {
+
+    private final PlatformSecurityContext platformSecurityContext;
+    private final ShareAccountReadPlatformService shareAccountReadPlatformService;
+
+    @GET
+    @Consumes({ MediaType.APPLICATION_JSON })
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(summary = "List all share accounts with client details", description = "Retrieves all share accounts along with their associated client details in a single optimized query.\n\n"
+            + "Example Requests:\n\n" + "shareaccounts/summary")
+    @ApiResponse(responseCode = "200", description = "OK")
+    public Collection<ShareAccountClientSummaryData> retrieveAllSummaries(@QueryParam("searchTerm") final String searchTerm) {
+        long start = System.currentTimeMillis();
+        System.out.println("[TIMING] Start of retrieveAllSummaries (before auth)");
+        this.platformSecurityContext.authenticatedUser();
+        long afterAuth = System.currentTimeMillis();
+        System.out.println("[TIMING] Auth check: " + (afterAuth - start) + "ms");
+        Collection<ShareAccountClientSummaryData> result = this.shareAccountReadPlatformService.retrieveAllShareAccountClientSummaries(searchTerm);
+        long afterService = System.currentTimeMillis();
+        System.out.println("[TIMING] Service call total (including query): " + (afterService - afterAuth) + "ms");
+        System.out.println("[TIMING] Right before response returned: " + (System.currentTimeMillis() - start) + "ms total so far");
+        return result;
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/data/ShareAccountClientSummaryData.java

@@ -0,0 +1,54 @@
+package org.apache.fineract.portfolio.shareaccounts.data;
+
+import java.io.Serializable;
+import java.time.LocalDate;
+import lombok.Getter;
+import org.apache.fineract.organisation.monetary.data.CurrencyData;
+import org.apache.fineract.portfolio.shareaccounts.data.ShareAccountStatusEnumData;
+
+@Getter
+public class ShareAccountClientSummaryData implements Serializable {
+
+    private final Long id;
+    private final Long clientId;
+    private final String clientName;
+    private final Long officeId;
+    private final String officeName;
+    private final String accountNo;
+    private final Long productId;
+    private final String productName;
+    private final Long totalApprovedShares;
+    private final Long totalPendingForApprovalShares;
+    private final CurrencyData currency;
+    private final LocalDate activatedDate;
+    private final ShareAccountStatusEnumData status;
+
+    public ShareAccountClientSummaryData(final Long id, final Long clientId, final String clientName, final Long officeId, final String officeName, final String accountNo,
+            final Long productId, final String productName, final Long totalApprovedShares, final Long totalPendingForApprovalShares,
+            final CurrencyData currency, final LocalDate activatedDate, final ShareAccountStatusEnumData status) {
+        this.id = id;
+        this.clientId = clientId;
+        this.clientName = clientName;
+        this.officeId = officeId;
+        this.officeName = officeName;
+        this.accountNo = accountNo;
+        this.productId = productId;
+        this.productName = productName;
+        
+        if (totalApprovedShares == null) {
+            this.totalApprovedShares = Long.valueOf(0);
+        } else {
+            this.totalApprovedShares = totalApprovedShares;
+        }
+        
+        if (totalPendingForApprovalShares == null) {
+            this.totalPendingForApprovalShares = Long.valueOf(0);
+        } else {
+            this.totalPendingForApprovalShares = totalPendingForApprovalShares;
+        }
+        
+        this.currency = currency;
+        this.activatedDate = activatedDate;
+        this.status = status;
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/data/ShareAccountData.java

@@ -67,6 +67,10 @@ public class ShareAccountData implements Serializable, AccountData {
 
     private Long savingsAccountId;
 
+    private Long linkedLoanId;
+
+    private String linkedLoanAccountNo;
+
     private BigDecimal currentMarketPrice;
 
     private Integer lockinPeriod;
@@ -301,6 +305,11 @@ public class ShareAccountData implements Serializable, AccountData {
         this.currentMarketPrice = currentMarketPrice;
     }
 
+    public void setLinkedLoan(final Long linkedLoanId, final String linkedLoanAccountNo) {
+        this.linkedLoanId = linkedLoanId;
+        this.linkedLoanAccountNo = linkedLoanAccountNo;
+    }
+
     public void setDividends(Collection<ShareAccountDividendData> dividends) {
         this.dividends = dividends;
     }

fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/data/ShareAccountTransactionData.java

@@ -51,4 +51,10 @@ public class ShareAccountTransactionData implements Serializable {
 
     private final BigDecimal amountPaid;
 
+    /** Board Resolution Number / Date of Meeting that authorised this transaction — populated
+     *  only for a redeem (withdrawal) transaction; null otherwise. */
+    private final String resolutionNumber;
+
+    private final LocalDate meetingDate;
+
 }

fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/domain/ShareAccount.java

@@ -147,6 +147,12 @@ public class ShareAccount extends AbstractPersistableCustom<Long> {
     @OneToMany(cascade = CascadeType.ALL, mappedBy = "shareAccount", orphanRemoval = true, fetch = FetchType.EAGER)
     private Set<ShareAccountCharge> charges;
 
+    /** Optional loan this share account is held as margin/security against. A raw id (not a JPA
+     *  relation) since shareaccounts and loanaccount are otherwise unrelated aggregate roots in
+     *  this codebase — kept loosely coupled, resolved via a lookup where needed. */
+    @Column(name = "linked_loan_id")
+    private Long linkedLoanId;
+
     @Transient
     protected boolean accountNumberRequiresAutoGeneration = false;
 
@@ -599,6 +605,19 @@ public class ShareAccount extends AbstractPersistableCustom<Long> {
         return this.activatedDate;
     }
 
+    public Long getLinkedLoanId() {
+        return this.linkedLoanId;
+    }
+
+    public boolean setLinkedLoanId(final Long linkedLoanId) {
+        boolean returnValue = false;
+        if (this.linkedLoanId == null || !this.linkedLoanId.equals(linkedLoanId)) {
+            this.linkedLoanId = linkedLoanId;
+            returnValue = true;
+        }
+        return returnValue;
+    }
+
     public Integer status() {
         return this.status;
     }

fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/domain/ShareAccountTransaction.java

@@ -67,6 +67,14 @@ public class ShareAccountTransaction extends AbstractPersistableCustom<Long> {
     @Column(name = "is_active", nullable = false)
     private boolean active = true;
 
+    /** Board Resolution Number and Date of Meeting authorising this transaction — required for a
+     *  share withdrawal (redeem), a governance requirement for cooperative-sector share capital. */
+    @Column(name = "resolution_number")
+    private String resolutionNumber;
+
+    @Column(name = "meeting_date")
+    private LocalDate meetingDate;
+
     @OneToMany(cascade = CascadeType.ALL, mappedBy = "shareAccountTransaction", orphanRemoval = true, fetch = FetchType.EAGER)
     private Set<ShareAccountChargePaidBy> shareAccountChargesPaid = new HashSet<>();
 
@@ -109,6 +117,22 @@ public class ShareAccountTransaction extends AbstractPersistableCustom<Long> {
         return new ShareAccountTransaction(transactionDate, totalShares, shareValue, status, type, amount, null, amountPaid);
     }
 
+    public static ShareAccountTransaction createRedeemTransaction(final LocalDate transactionDate, final Long totalShares,
+            final BigDecimal shareValue, final String resolutionNumber, final LocalDate meetingDate) {
+        ShareAccountTransaction transaction = createRedeemTransaction(transactionDate, totalShares, shareValue);
+        transaction.resolutionNumber = resolutionNumber;
+        transaction.meetingDate = meetingDate;
+        return transaction;
+    }
+
+    public String getResolutionNumber() {
+        return this.resolutionNumber;
+    }
+
+    public LocalDate getMeetingDate() {
+        return this.meetingDate;
+    }
+
     public static ShareAccountTransaction createChargeTransaction(final LocalDate transactionDate, final ShareAccountCharge charge) {
         final Long totalShares = null;
         final BigDecimal unitPrice = null;

fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/serialization/ShareAccountDataSerializer.java

@@ -72,6 +72,7 @@ import org.apache.fineract.useradministration.domain.AppUser;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.stereotype.Service;
 
 @Service
@@ -93,6 +94,8 @@ public class ShareAccountDataSerializer {
 
     private final SavingsAccountReadPlatformService savingsAccountReadPlatformService;
 
+    private final JdbcTemplate jdbcTemplate;
+
     private static final Set<String> approvalParameters = new HashSet<>(
             Arrays.asList(ShareAccountApiConstants.locale_paramname, ShareAccountApiConstants.dateformat_paramname,
                     ShareAccountApiConstants.approveddate_paramname, ShareAccountApiConstants.note_paramname));
@@ -106,13 +109,14 @@ public class ShareAccountDataSerializer {
 
     private static final Set<String> addtionalSharesParameters = new HashSet<>(Arrays.asList(ShareAccountApiConstants.locale_paramname,
             ShareAccountApiConstants.requesteddate_paramname, ShareAccountApiConstants.requestedshares_paramname,
-            ShareAccountApiConstants.purchasedprice_paramname, ShareAccountApiConstants.dateformat_paramname));
+            ShareAccountApiConstants.purchasedprice_paramname, ShareAccountApiConstants.dateformat_paramname,
+            ShareAccountApiConstants.redeemresolutionnumber_paramname, ShareAccountApiConstants.redeemmeetingdate_paramname));
 
     @Autowired
     public ShareAccountDataSerializer(final PlatformSecurityContext platformSecurityContext, final FromJsonHelper fromApiJsonHelper,
             final ChargeRepositoryWrapper chargeRepository, final SavingsAccountRepositoryWrapper savingsAccountRepositoryWrapper,
             final ClientRepositoryWrapper clientRepositoryWrapper, final ShareProductRepositoryWrapper shareProductRepository,
-            final SavingsAccountReadPlatformService savingsAccountReadPlatformService) {
+            final SavingsAccountReadPlatformService savingsAccountReadPlatformService, final JdbcTemplate jdbcTemplate) {
         this.platformSecurityContext = platformSecurityContext;
         this.fromApiJsonHelper = fromApiJsonHelper;
         this.chargeRepository = chargeRepository;
@@ -120,6 +124,7 @@ public class ShareAccountDataSerializer {
         this.clientRepositoryWrapper = clientRepositoryWrapper;
         this.shareProductRepository = shareProductRepository;
         this.savingsAccountReadPlatformService = savingsAccountReadPlatformService;
+        this.jdbcTemplate = jdbcTemplate;
     }
 
     public ShareAccount validateAndCreate(JsonCommand jsonCommand) {
@@ -313,6 +318,13 @@ public class ShareAccountDataSerializer {
             }
         }
 
+        if (this.fromApiJsonHelper.parameterExists(ShareAccountApiConstants.linkedloanid_paramname, element)) {
+            final Long linkedLoanId = this.fromApiJsonHelper.extractLongNamed(ShareAccountApiConstants.linkedloanid_paramname, element);
+            if (account.setLinkedLoanId(linkedLoanId)) {
+                actualChanges.put(ShareAccountApiConstants.linkedloanid_paramname, linkedLoanId);
+            }
+        }
+
         if (this.fromApiJsonHelper.parameterExists(ShareAccountApiConstants.savingsaccountid_paramname, element)) {
             Long savingsAccountId = this.fromApiJsonHelper.extractLongNamed(ShareAccountApiConstants.savingsaccountid_paramname, element);
             baseDataValidator.reset().parameter(ShareAccountApiConstants.savingsaccountid_paramname).value(savingsAccountId).notNull()
@@ -885,6 +897,13 @@ public class ShareAccountDataSerializer {
         final Long sharesRequested = this.fromApiJsonHelper.extractLongNamed(ShareAccountApiConstants.requestedshares_paramname, element);
         baseDataValidator.reset().parameter(ShareAccountApiConstants.requestedshares_paramname).value(sharesRequested).notNull()
                 .longGreaterThanZero();
+        // Governance requirement: a share withdrawal must be authorised by a Board Resolution.
+        final String resolutionNumber = this.fromApiJsonHelper
+                .extractStringNamed(ShareAccountApiConstants.redeemresolutionnumber_paramname, element);
+        baseDataValidator.reset().parameter(ShareAccountApiConstants.redeemresolutionnumber_paramname).value(resolutionNumber).notBlank();
+        final LocalDate meetingDate = this.fromApiJsonHelper.extractLocalDateNamed(ShareAccountApiConstants.redeemmeetingdate_paramname,
+                element);
+        baseDataValidator.reset().parameter(ShareAccountApiConstants.redeemmeetingdate_paramname).value(meetingDate).notNull();
         boolean isTransactionBeforeExistingTransactions = false;
         isTransactionBeforeExistingTransactions = isTransactionBeforeExistingTransactions(requestedDate,
                 isTransactionBeforeExistingTransactions, account);
@@ -896,7 +915,8 @@ public class ShareAccountDataSerializer {
             throw new PlatformApiDataValidationException(dataValidationErrors);
         }
         BigDecimal unitPrice = account.getShareProduct().deriveMarketPrice(requestedDate);
-        ShareAccountTransaction transaction = ShareAccountTransaction.createRedeemTransaction(requestedDate, sharesRequested, unitPrice);
+        ShareAccountTransaction transaction = ShareAccountTransaction.createRedeemTransaction(requestedDate, sharesRequested, unitPrice,
+                resolutionNumber, meetingDate);
         validateRedeemRequest(account, transaction, baseDataValidator, dataValidationErrors);
         account.addAdditionalPurchasedShares(transaction);
         actualChanges.put(ShareAccountApiConstants.requestedshares_paramname, transaction);
@@ -917,6 +937,18 @@ public class ShareAccountDataSerializer {
             throw new PlatformApiDataValidationException(dataValidationErrors);
         }
 
+        final Long remainingShares = account.getTotalApprovedShares() - redeemTransaction.getTotalShares();
+
+        validateAgainstLinkedLoan(account, redeemTransaction, remainingShares, baseDataValidator, dataValidationErrors);
+        if (!dataValidationErrors.isEmpty()) {
+            throw new PlatformApiDataValidationException(dataValidationErrors);
+        }
+
+        validateMinimumSharesAndTenure(account, redeemTransaction, remainingShares, baseDataValidator, dataValidationErrors);
+        if (!dataValidationErrors.isEmpty()) {
+            throw new PlatformApiDataValidationException(dataValidationErrors);
+        }
+
         LocalDate redeemDate = redeemTransaction.getPurchasedDate();
         final Integer lockinPeriod = account.getLockinPeriodFrequency();
         final PeriodFrequencyType periodType = account.getLockinPeriodFrequencyType();
@@ -967,6 +999,63 @@ public class ShareAccountDataSerializer {
         }
     }
 
+    /** If this share account is held as margin/security against a loan, the shares remaining
+     *  after this redemption (at current unit price) must still cover that loan's outstanding
+     *  balance. */
+    private void validateAgainstLinkedLoan(final ShareAccount account, final ShareAccountTransaction redeemTransaction,
+            final Long remainingShares, final DataValidatorBuilder baseDataValidator, final List<ApiParameterError> dataValidationErrors) {
+        final Long linkedLoanId = account.getLinkedLoanId();
+        if (linkedLoanId == null) {
+            return;
+        }
+        BigDecimal outstandingLoanBalance;
+        try {
+            outstandingLoanBalance = this.jdbcTemplate.queryForObject(
+                    "SELECT COALESCE(total_outstanding_derived, principal_disbursed_derived, 0) FROM m_loan WHERE id = ? AND loan_status_id = 300",
+                    BigDecimal.class, linkedLoanId);
+        } catch (org.springframework.dao.EmptyResultDataAccessException e) {
+            // Linked loan is no longer active (closed/written-off) — nothing left to protect.
+            outstandingLoanBalance = null;
+        }
+        if (outstandingLoanBalance == null) {
+            return;
+        }
+        final BigDecimal remainingShareValue = redeemTransaction.getPurchasePrice().multiply(BigDecimal.valueOf(remainingShares));
+        if (remainingShareValue.compareTo(outstandingLoanBalance) < 0) {
+            baseDataValidator.reset().parameter(ShareAccountApiConstants.requestedshares_paramname)
+                    .value(redeemTransaction.getTotalShares())
+                    .failWithCodeNoParameterAddedToErrorCode("cannot.be.redeemed.shares.linked.to.active.loan.margin.shortfall");
+        }
+    }
+
+    /** If this redemption would bring the holding below the Share Product's configured minimum
+     *  client shares, the account must have been active for at least the product's configured
+     *  minimum active period before the reduction is allowed. */
+    private void validateMinimumSharesAndTenure(final ShareAccount account, final ShareAccountTransaction redeemTransaction,
+            final Long remainingShares, final DataValidatorBuilder baseDataValidator, final List<ApiParameterError> dataValidationErrors) {
+        final Long minimumClientShares = account.getShareProduct().getMinimumClientShares();
+        if (minimumClientShares == null || remainingShares >= minimumClientShares) {
+            return;
+        }
+        final Integer minimumActivePeriod = account.getMinimumActivePeriodFrequency();
+        final PeriodFrequencyType minimumActivePeriodType = account.getMinimumActivePeriodFrequencyType();
+        final LocalDate activatedDate = account.getActivatedDate();
+        if (minimumActivePeriod == null || minimumActivePeriodType == null || activatedDate == null) {
+            // Product enforces a minimum balance but defines no minimum tenure — reducing below
+            // minimum is simply not allowed at all in that case.
+            baseDataValidator.reset().parameter(ShareAccountApiConstants.requestedshares_paramname)
+                    .value(redeemTransaction.getTotalShares())
+                    .failWithCodeNoParameterAddedToErrorCode("cannot.be.redeemed.below.minimum.shares.required.by.product");
+            return;
+        }
+        final LocalDate eligibleFromDate = deriveLockinPeriodDuration(minimumActivePeriod, minimumActivePeriodType, activatedDate);
+        if (DateUtils.isAfter(eligibleFromDate, redeemTransaction.getPurchasedDate())) {
+            baseDataValidator.reset().parameter(ShareAccountApiConstants.requesteddate_paramname)
+                    .value(redeemTransaction.getPurchasedDate())
+                    .failWithCodeNoParameterAddedToErrorCode("cannot.be.redeemed.below.minimum.shares.before.minimum.tenure");
+        }
+    }
+
     private LocalDate deriveLockinPeriodDuration(final Integer lockinPeriod, final PeriodFrequencyType periodType, LocalDate purchaseDate) {
         LocalDate lockinDate = purchaseDate;
         if (periodType != null) {
@@ -1044,6 +1133,11 @@ public class ShareAccountDataSerializer {
             throw new PlatformApiDataValidationException(dataValidationErrors);
         }
 
+        validateNoActiveLoanOrGuaranteeBeforeClosure(account, baseDataValidator, dataValidationErrors);
+        if (!dataValidationErrors.isEmpty()) {
+            throw new PlatformApiDataValidationException(dataValidationErrors);
+        }
+
         AppUser approvedUser = this.platformSecurityContext.authenticatedUser();
         final BigDecimal unitPrice = account.getShareProduct().deriveMarketPrice(DateUtils.getBusinessLocalDate());
         ShareAccountTransaction transaction = ShareAccountTransaction.createRedeemTransaction(closedDate, account.getTotalApprovedShares(),
@@ -1054,4 +1148,42 @@ public class ShareAccountDataSerializer {
         actualChanges.put(ShareAccountApiConstants.requestedshares_paramname, transaction);
         return actualChanges;
     }
+
+    /** A share account cannot be closed while the member has an active loan (share capital is
+     *  often required as continuing membership/security while a liability is outstanding) or is
+     *  standing as an active guarantor on someone else's active loan. */
+    private void validateNoActiveLoanOrGuaranteeBeforeClosure(final ShareAccount account, final DataValidatorBuilder baseDataValidator,
+            final List<ApiParameterError> dataValidationErrors) {
+        final Long clientId = account.getClientId();
+        Integer activeLoanCount;
+        try {
+            activeLoanCount = this.jdbcTemplate.queryForObject(
+                    "SELECT COUNT(id) FROM m_loan WHERE client_id = ? AND loan_status_id = 300", Integer.class, clientId);
+        } catch (org.springframework.dao.EmptyResultDataAccessException e) {
+            activeLoanCount = 0;
+        }
+        if (activeLoanCount != null && activeLoanCount > 0) {
+            baseDataValidator.reset().parameter(ShareAccountApiConstants.closeddate_paramname)
+                    .failWithCodeNoParameterAddedToErrorCode("share.account.cannot.be.closed.member.has.active.loan");
+            return;
+        }
+
+        Integer activeGuaranteeCount;
+        try {
+            activeGuaranteeCount = this.jdbcTemplate.queryForObject("""
+                    SELECT COUNT(g.id)
+                    FROM m_guarantor g
+                    JOIN m_loan l ON l.id = g.loan_id
+                    WHERE g.entity_id = ?
+                    AND g.is_active = 1
+                    AND l.loan_status_id = 300
+                    """, Integer.class, clientId);
+        } catch (org.springframework.dao.EmptyResultDataAccessException e) {
+            activeGuaranteeCount = 0;
+        }
+        if (activeGuaranteeCount != null && activeGuaranteeCount > 0) {
+            baseDataValidator.reset().parameter(ShareAccountApiConstants.closeddate_paramname)
+                    .failWithCodeNoParameterAddedToErrorCode("share.account.cannot.be.closed.member.has.active.guarantee");
+        }
+    }
 }

fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/service/PurchasedSharesReadPlatformServiceImpl.java

@@ -50,7 +50,8 @@ public class PurchasedSharesReadPlatformServiceImpl implements PurchasedSharesRe
             StringBuilder buff = new StringBuilder()
                     .append("saps.id, saps.account_id, saps.transaction_date, saps.total_shares, saps.unit_price, ")
                     .append("saps.status_enum, saps.type_enum, saps.amount, saps.charge_amount as chargeamount, ")
-                    .append("saps.amount_paid as amountPaid").append(" from m_share_account_transactions saps ");
+                    .append("saps.amount_paid as amountPaid, saps.resolution_number as resolutionNumber, saps.meeting_date as meetingDate")
+                    .append(" from m_share_account_transactions saps ");
             schema = buff.toString();
         }
 
@@ -68,9 +69,12 @@ public class PurchasedSharesReadPlatformServiceImpl implements PurchasedSharesRe
             final BigDecimal amount = JdbcSupport.getBigDecimalDefaultToZeroIfNull(rs, "amount");
             final BigDecimal chargeAmount = JdbcSupport.getBigDecimalDefaultToZeroIfNull(rs, "chargeamount");
             final BigDecimal amountPaid = JdbcSupport.getBigDecimalDefaultToZeroIfNull(rs, "amountPaid");
+            final String resolutionNumber = rs.getString("resolutionNumber");
+            final java.sql.Date meetingDateSql = rs.getDate("meetingDate");
+            final LocalDate meetingDate = meetingDateSql != null ? meetingDateSql.toLocalDate() : null;
 
             return new ShareAccountTransactionData(id, accountId, purchasedDate, numberOfShares, purchasedPrice, statusEnum, typeEnum,
-                    amount, chargeAmount, amountPaid);
+                    amount, chargeAmount, amountPaid, resolutionNumber, meetingDate);
         }
 
         public String schema() {

fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/service/ShareAccountReadPlatformService.java

@@ -23,6 +23,7 @@ import java.util.Collection;
 import java.util.Set;
 import org.apache.fineract.portfolio.accounts.service.AccountReadPlatformService;
 import org.apache.fineract.portfolio.shareaccounts.data.ShareAccountData;
+import org.apache.fineract.portfolio.shareaccounts.data.ShareAccountClientSummaryData;
 
 public interface ShareAccountReadPlatformService extends AccountReadPlatformService {
 
@@ -38,5 +39,7 @@ public interface ShareAccountReadPlatformService extends AccountReadPlatformServ
     Collection<ShareAccountData> retrieveAllShareAccountDataForDividends(Long productId, boolean fetchInActiveAccounts,
             LocalDate startDate);
 
+    Collection<ShareAccountClientSummaryData> retrieveAllShareAccountClientSummaries(String searchTerm);
+
     String retrieveAccountNumberByAccountId(Long accountId);
 }

fineract-provider/src/main/java/org/apache/fineract/portfolio/shareaccounts/service/ShareAccountReadPlatformServiceImpl.java

@@ -62,6 +62,7 @@ import org.apache.fineract.portfolio.shareaccounts.domain.ShareAccountStatusType
 import org.apache.fineract.portfolio.shareproducts.data.ShareProductData;
 import org.apache.fineract.portfolio.shareproducts.data.ShareProductMarketPriceData;
 import org.apache.fineract.portfolio.shareproducts.service.ShareProductDropdownReadPlatformService;
+import org.apache.fineract.portfolio.shareaccounts.data.ShareAccountClientSummaryData;
 import org.springframework.context.ApplicationContext;
 import org.springframework.dao.EmptyResultDataAccessException;
 import org.springframework.jdbc.core.JdbcTemplate;
@@ -221,6 +222,29 @@ public class ShareAccountReadPlatformServiceImpl implements ShareAccountReadPlat
         }, mapper);
     }
 
+    @Override
+    public Collection<ShareAccountClientSummaryData> retrieveAllShareAccountClientSummaries(String searchTerm) {
+        long start = System.currentTimeMillis();
+        System.out.println("[TIMING] Inside retrieveAllShareAccountClientSummaries, before query builder setup");
+        ShareAccountClientSummaryMapper mapper = new ShareAccountClientSummaryMapper();
+        StringBuilder queryBuilder = new StringBuilder("select ").append(mapper.schema());
+        List<Object> paramList = new ArrayList<>();
+        
+        if (searchTerm != null && !searchTerm.trim().isEmpty()) {
+            queryBuilder.append(" where (c.display_name ILIKE ? OR sa.account_no ILIKE ?)");
+            String searchPattern = "%" + searchTerm + "%";
+            paramList.add(searchPattern);
+            paramList.add(searchPattern);
+        }
+        
+        long beforeQuery = System.currentTimeMillis();
+        System.out.println("[TIMING] Before actual SQL query call. Time since service start: " + (beforeQuery - start) + "ms");
+        Collection<ShareAccountClientSummaryData> result = this.jdbcTemplate.query(queryBuilder.toString(), mapper, paramList.toArray());
+        long afterQuery = System.currentTimeMillis();
+        System.out.println("[TIMING] Query execution (JdbcTemplate): " + (afterQuery - beforeQuery) + "ms");
+        return result;
+    }
+
     public Collection<ShareAccountChargeData> convertChargesToShareAccountCharges(Collection<ChargeData> productCharges) {
         final Collection<ShareAccountChargeData> savingsCharges = new ArrayList<>();
         for (final ChargeData chargeData : productCharges) {
@@ -243,6 +267,7 @@ public class ShareAccountReadPlatformServiceImpl implements ShareAccountReadPlat
             this.purchasedShares = purchasedShares;
             StringBuilder buff = new StringBuilder().append(
                     "sa.id as id, sa.external_id as externalId, sa.resolution_number as resolutionNumber, sa.status_enum as statusEnum, ")
+                    .append("sa.linked_loan_id as linkedLoanId, ml.account_no as linkedLoanAccountNo, ")
                     .append("sa.savings_account_id, msa.account_no as savingsAccNo, ")
                     .append("c.id as clientId, c.display_name as clientName, ")
                     .append("sa.account_no as accountNo, sa.total_approved_shares as approvedShares, sa.total_pending_shares as pendingShares, ")
@@ -270,7 +295,8 @@ public class ShareAccountReadPlatformServiceImpl implements ShareAccountReadPlat
                     .append("left join m_appuser abu on abu.id = sa.approved_userid ")
                     .append("left join m_appuser avbu on rbu.id = sa.activated_userid ")
                     .append("left join m_appuser cbu on cbu.id = sa.closed_userid ")
-                    .append("left join m_savings_account msa on sa.savings_account_id = msa.id ");
+                    .append("left join m_savings_account msa on sa.savings_account_id = msa.id ")
+                    .append("left join m_loan ml on ml.id = sa.linked_loan_id ");
             this.schema = buff.toString();
         }
 
@@ -280,6 +306,8 @@ public class ShareAccountReadPlatformServiceImpl implements ShareAccountReadPlat
             final String accountNo = rs.getString("accountNo");
             final String externalId = rs.getString("externalId");
             final String resolutionNumber = rs.getString("resolutionNumber");
+            final Long linkedLoanId = JdbcSupport.getLong(rs, "linkedLoanId");
+            final String linkedLoanAccountNo = rs.getString("linkedLoanAccountNo");
             final Long savingsAccountId = JdbcSupport.getLong(rs, "savings_account_id");
             final String savingsAccountNumber = rs.getString("savingsAccNo");
             final Long clientId = JdbcSupport.getLong(rs, "clientId");
@@ -351,10 +379,12 @@ public class ShareAccountReadPlatformServiceImpl implements ShareAccountReadPlat
             final String shortProductName = null;
             final ShareAccountSummaryData summary = new ShareAccountSummaryData(id, accountNo, externalId, productId, productName,
                     shortProductName, status, currency, totalApprovedShares, totalPendingShares, timeline);
-            return new ShareAccountData(id, accountNo, externalId, resolutionNumber, savingsAccountId, savingsAccountNumber, clientId,
-                    clientName, productId, productName, status, timeline, currency, summary, charges, purchasedShares,
-                    lockinPeriodFrequency, lockinPeriodFrequencyType, minimumActivePeriod, minimumActivePeriodType,
+            final ShareAccountData shareAccountData = new ShareAccountData(id, accountNo, externalId, resolutionNumber, savingsAccountId,
+                    savingsAccountNumber, clientId, clientName, productId, productName, status, timeline, currency, summary, charges,
+                    purchasedShares, lockinPeriodFrequency, lockinPeriodFrequencyType, minimumActivePeriod, minimumActivePeriodType,
                     allowdividendsforinactiveclients);
+            shareAccountData.setLinkedLoan(linkedLoanId, linkedLoanAccountNo);
+            return shareAccountData;
 
         }
 
@@ -437,7 +467,7 @@ public class ShareAccountReadPlatformServiceImpl implements ShareAccountReadPlat
             StringBuilder buff = new StringBuilder().append(
                     "saps.id as purchasedId, saps.account_id as accountId, saps.transaction_date as transactionDate, saps.total_shares as purchasedShares, saps.unit_price as unitPrice, ")
                     .append("saps.status_enum as purchaseStatus, saps.type_enum as purchaseType, saps.amount as amount, saps.charge_amount as chargeamount, ")
-                    .append("saps.amount_paid as amountPaid ");
+                    .append("saps.amount_paid as amountPaid, saps.resolution_number as resolutionNumber, saps.meeting_date as meetingDate ");
 
             schema = buff.toString();
         }
@@ -456,8 +486,11 @@ public class ShareAccountReadPlatformServiceImpl implements ShareAccountReadPlat
             final BigDecimal amount = JdbcSupport.getBigDecimalDefaultToNullIfZero(rs, "amount");
             final BigDecimal chargeAmount = JdbcSupport.getBigDecimalDefaultToNullIfZero(rs, "chargeamount");
             final BigDecimal amountPaid = JdbcSupport.getBigDecimalDefaultToNullIfZero(rs, "amountPaid");
+            final String resolutionNumber = rs.getString("resolutionNumber");
+            final java.sql.Date meetingDateSql = rs.getDate("meetingDate");
+            final LocalDate meetingDate = meetingDateSql != null ? meetingDateSql.toLocalDate() : null;
             return new ShareAccountTransactionData(id, accountId, transactionDate, numberOfShares, purchasedPrice, statusEnum, typeEnum,
-                    amount, chargeAmount, amountPaid);
+                    amount, chargeAmount, amountPaid, resolutionNumber, meetingDate);
         }
 
         public String schema() {
@@ -495,6 +528,63 @@ public class ShareAccountReadPlatformServiceImpl implements ShareAccountReadPlat
         }
     }
 
+    private static final class ShareAccountClientSummaryMapper implements RowMapper<ShareAccountClientSummaryData> {
+
+        private final String schema;
+
+        ShareAccountClientSummaryMapper() {
+            StringBuilder buff = new StringBuilder().append("sa.id as id, c.id as clientId, c.display_name as clientName, ")
+                    .append("sa.account_no as accountNo, p.id as productId, p.name as productName, ")
+                    .append("sa.total_approved_shares as approvedShares, sa.total_pending_shares as pendingShares, ")
+                    .append("sa.currency_code as currencyCode, sa.currency_digits as currencyDigits, sa.currency_multiplesof as inMultiplesOf, ")
+                    .append("curr.name as currencyName, curr.internationalized_name_code as currencyNameCode, ")
+                    .append("curr.display_symbol as currencyDisplaySymbol, sa.activated_date as activatedDate, ")
+                    .append("sa.status_enum as statusEnum, o.id as officeId, o.name as officeName ")
+                    .append("from m_share_account sa ")
+                    .append("inner join m_client c ON c.id = sa.client_id ")
+                    .append("inner join m_office o ON o.id = c.office_id ")
+                    .append("inner join m_share_product p on p.id = sa.product_id ")
+                    .append("inner join m_currency curr on curr.code = sa.currency_code");
+            this.schema = buff.toString();
+        }
+
+        @Override
+        public ShareAccountClientSummaryData mapRow(ResultSet rs, @SuppressWarnings("unused") int rowNum) throws SQLException {
+            final Long id = rs.getLong("id");
+            final Long clientId = rs.getLong("clientId");
+            final String clientName = rs.getString("clientName");
+            final String accountNo = rs.getString("accountNo");
+            final Long productId = rs.getLong("productId");
+            final String productName = rs.getString("productName");
+            final Long totalApprovedShares = JdbcSupport.getLong(rs, "approvedShares");
+            final Long totalPendingForApprovalShares = JdbcSupport.getLong(rs, "pendingShares");
+
+            final String currencyCode = rs.getString("currencyCode");
+            final String currencyName = rs.getString("currencyName");
+            final String currencyNameCode = rs.getString("currencyNameCode");
+            final String currencyDisplaySymbol = rs.getString("currencyDisplaySymbol");
+            final Integer currencyDigits = JdbcSupport.getInteger(rs, "currencyDigits");
+            final Integer inMultiplesOf = JdbcSupport.getInteger(rs, "inMultiplesOf");
+            final CurrencyData currency = new CurrencyData(currencyCode, currencyName, currencyDigits, inMultiplesOf,
+                    currencyDisplaySymbol, currencyNameCode);
+
+            final LocalDate activatedDate = JdbcSupport.getLocalDate(rs, "activatedDate");
+            
+            final Integer statusEnum = rs.getInt("statusEnum");
+            final ShareAccountStatusEnumData status = SharesEnumerations.status(statusEnum);
+            
+            final Long officeId = rs.getLong("officeId");
+            final String officeName = rs.getString("officeName");
+
+            return new ShareAccountClientSummaryData(id, clientId, clientName, officeId, officeName, accountNo, productId, productName,
+                    totalApprovedShares, totalPendingForApprovalShares, currency, activatedDate, status);
+        }
+
+        public String schema() {
+            return this.schema;
+        }
+    }
+
     @Override
     public String retrieveAccountNumberByAccountId(Long accountId) {
         try {

fineract-provider/src/main/java/org/apache/fineract/portfolio/welcomekit/api/ClientWelcomeKitApiResource.java

@@ -0,0 +1,73 @@
+/**
+ * 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.portfolio.welcomekit.api;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.data.CommandProcessingResult;
+import org.apache.fineract.infrastructure.core.serialization.FromJsonHelper;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.apache.fineract.portfolio.welcomekit.data.ClientWelcomeKitData;
+import org.apache.fineract.portfolio.welcomekit.service.WelcomeKitReadPlatformService;
+import org.apache.fineract.portfolio.welcomekit.service.WelcomeKitWritePlatformService;
+import org.springframework.stereotype.Component;
+
+@Path("/v1/clients/{clientId}/welcomekit")
+@Component
+@Tag(name = "Welcome Kit Dispatch", description = "Manages the dispatching and tracking of welcome kits for clients.")
+@RequiredArgsConstructor
+public class ClientWelcomeKitApiResource {
+
+    private static final String RESOURCE_NAME_FOR_PERMISSIONS = "WELCOMEKIT";
+    private final PlatformSecurityContext context;
+    private final WelcomeKitReadPlatformService readPlatformService;
+    private final WelcomeKitWritePlatformService writePlatformService;
+    private final FromJsonHelper fromJsonHelper;
+
+    @GET
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(summary = "List all welcome kits for a Client")
+    public ClientWelcomeKitData getClientWelcomeKits(@PathParam("clientId") @Parameter(description = "clientId") final Long clientId) {
+        this.context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSIONS);
+        return this.readPlatformService.retrieveWelcomeKitsByClientId(clientId);
+    }
+
+    @POST
+    @Consumes({ MediaType.APPLICATION_JSON })
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(summary = "Create a new welcome kit dispatch")
+    public CommandProcessingResult dispatchWelcomeKit(@PathParam("clientId") @Parameter(description = "clientId") final Long clientId,
+            @Parameter(hidden = true) final String apiRequestBodyAsJson) {
+        this.context.authenticatedUser().validateHasPermissionTo("CREATE_" + RESOURCE_NAME_FOR_PERMISSIONS);
+        
+        final JsonCommand command = JsonCommand.fromJsonElement(clientId, this.fromJsonHelper.parse(apiRequestBodyAsJson), this.fromJsonHelper);
+        
+        return this.writePlatformService.dispatchWelcomeKit(clientId, command);
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/welcomekit/api/WelcomeKitApiResource.java

@@ -0,0 +1,67 @@
+/**
+ * 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.portfolio.welcomekit.api;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.PUT;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.core.MediaType;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.data.CommandProcessingResult;
+import org.apache.fineract.infrastructure.core.serialization.FromJsonHelper;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.apache.fineract.portfolio.welcomekit.data.ClientWelcomeKitData;
+import org.apache.fineract.portfolio.welcomekit.service.WelcomeKitReadPlatformService;
+import org.apache.fineract.portfolio.welcomekit.service.WelcomeKitWritePlatformService;
+import org.springframework.stereotype.Component;
+
+@Path("/v1/welcomekit")
+@Component
+@Tag(name = "Welcome Kit Dispatch", description = "Manages the dispatching and tracking of welcome kits for clients.")
+@RequiredArgsConstructor
+public class WelcomeKitApiResource {
+
+    private static final String RESOURCE_NAME_FOR_PERMISSIONS = "WELCOMEKIT";
+    private final PlatformSecurityContext context;
+    private final WelcomeKitWritePlatformService writePlatformService;
+    private final FromJsonHelper fromJsonHelper;
+
+    @PUT
+    @Path("{welcomeKitId}")
+    @Consumes({ MediaType.APPLICATION_JSON })
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(summary = "Update the status of an existing dispatch")
+    public CommandProcessingResult updateWelcomeKitStatus(
+            @PathParam("welcomeKitId") @Parameter(description = "welcomeKitId") final Long welcomeKitId,
+            @Parameter(hidden = true) final String apiRequestBodyAsJson) {
+        this.context.authenticatedUser().validateHasPermissionTo("UPDATE_" + RESOURCE_NAME_FOR_PERMISSIONS);
+        
+        final JsonCommand command = JsonCommand.fromJsonElement(welcomeKitId, this.fromJsonHelper.parse(apiRequestBodyAsJson), this.fromJsonHelper);
+        
+        return this.writePlatformService.updateWelcomeKitStatus(welcomeKitId, command);
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/welcomekit/data/ClientWelcomeKitData.java

@@ -0,0 +1,33 @@
+/**
+ * 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.portfolio.welcomekit.data;
+
+import java.io.Serializable;
+import java.util.List;
+import lombok.Builder;
+import lombok.Data;
+
+@Data
+@Builder
+public class ClientWelcomeKitData implements Serializable {
+
+    private final String clientName;
+    private final boolean canDispatchNew;
+    private final List<WelcomeKitDispatchData> dispatches;
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/welcomekit/data/WelcomeKitDispatchData.java

@@ -0,0 +1,40 @@
+/**
+ * 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.portfolio.welcomekit.data;
+
+import java.io.Serializable;
+import java.time.LocalDate;
+import lombok.Builder;
+import lombok.Data;
+
+@Data
+@Builder
+public class WelcomeKitDispatchData implements Serializable {
+
+    private final Long id;
+    private final Long clientId;
+    private final String clientName;
+    private final String deliveryAddress;
+    private final String deliveryMode;
+    private final String deliveryModeOtherText;
+    private final String trackingId;
+    private final String status;
+    private final LocalDate dispatchedOnDate;
+    private final LocalDate deliveredOnDate;
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/welcomekit/domain/WelcomeKitDispatch.java

@@ -0,0 +1,118 @@
+/**
+ * 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.portfolio.welcomekit.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EntityListeners;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.springframework.data.annotation.CreatedBy;
+import org.springframework.data.annotation.CreatedDate;
+import org.springframework.data.annotation.LastModifiedBy;
+import org.springframework.data.annotation.LastModifiedDate;
+import org.springframework.data.jpa.domain.support.AuditingEntityListener;
+
+@Entity
+@Table(name = "m_welcome_kit_dispatch")
+@EntityListeners(AuditingEntityListener.class)
+public class WelcomeKitDispatch extends AbstractPersistableCustom<Long> {
+
+    @ManyToOne
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    @Column(name = "delivery_address", length = 500, nullable = false)
+    private String deliveryAddress;
+
+    @Column(name = "delivery_mode", length = 50, nullable = false)
+    private String deliveryMode;
+
+    @Column(name = "delivery_mode_other_text", length = 255)
+    private String deliveryModeOtherText;
+
+    @Column(name = "tracking_id", length = 100, nullable = false, unique = true)
+    private String trackingId;
+
+    @Column(name = "status", length = 30, nullable = false)
+    private String status;
+
+    @Column(name = "dispatched_on_date", nullable = false)
+    private LocalDate dispatchedOnDate;
+
+    @Column(name = "delivered_on_date")
+    private LocalDate deliveredOnDate;
+
+    @CreatedBy
+    @Column(name = "created_by", updatable = false)
+    private Long createdBy;
+
+    @CreatedDate
+    @Column(name = "created_date", updatable = false)
+    private LocalDateTime createdDate;
+
+    @LastModifiedBy
+    @Column(name = "last_modified_by")
+    private Long lastModifiedBy;
+
+    @LastModifiedDate
+    @Column(name = "last_modified_date")
+    private LocalDateTime lastModifiedDate;
+
+    protected WelcomeKitDispatch() {
+        // Default constructor for JPA
+    }
+
+    private WelcomeKitDispatch(final Client client, final String deliveryAddress, final String deliveryMode,
+            final String deliveryModeOtherText, final String trackingId, final String status,
+            final LocalDate dispatchedOnDate) {
+        this.client = client;
+        this.deliveryAddress = deliveryAddress;
+        this.deliveryMode = deliveryMode;
+        this.deliveryModeOtherText = deliveryModeOtherText;
+        this.trackingId = trackingId;
+        this.status = status;
+        this.dispatchedOnDate = dispatchedOnDate;
+    }
+
+    public static WelcomeKitDispatch createNew(final Client client, final String deliveryAddress, final String deliveryMode,
+            final String deliveryModeOtherText, final String trackingId, final LocalDate dispatchedOnDate) {
+        return new WelcomeKitDispatch(client, deliveryAddress, deliveryMode, deliveryModeOtherText, trackingId, "DISPATCHED", dispatchedOnDate);
+    }
+
+    public Client getClient() {
+        return this.client;
+    }
+
+    public String getStatus() {
+        return this.status;
+    }
+
+    public void updateStatus(final String newStatus, final LocalDate deliveredOnDate) {
+        this.status = newStatus;
+        if ("DELIVERED".equals(newStatus)) {
+            this.deliveredOnDate = deliveredOnDate;
+        }
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/welcomekit/domain/WelcomeKitDispatchRepository.java

@@ -0,0 +1,28 @@
+/**
+ * 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.portfolio.welcomekit.domain;
+
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
+
+public interface WelcomeKitDispatchRepository extends JpaRepository<WelcomeKitDispatch, Long>, JpaSpecificationExecutor<WelcomeKitDispatch> {
+
+    List<WelcomeKitDispatch> findByClientIdOrderByCreatedDateDesc(Long clientId);
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/welcomekit/service/WelcomeKitReadPlatformService.java

@@ -0,0 +1,26 @@
+/**
+ * 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.portfolio.welcomekit.service;
+
+import org.apache.fineract.portfolio.welcomekit.data.ClientWelcomeKitData;
+
+public interface WelcomeKitReadPlatformService {
+
+    ClientWelcomeKitData retrieveWelcomeKitsByClientId(Long clientId);
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/welcomekit/service/WelcomeKitReadPlatformServiceImpl.java

@@ -0,0 +1,103 @@
+/**
+ * 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.portfolio.welcomekit.service;
+
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.time.LocalDate;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.core.domain.JdbcSupport;
+import org.apache.fineract.portfolio.welcomekit.data.ClientWelcomeKitData;
+import org.apache.fineract.portfolio.welcomekit.data.WelcomeKitDispatchData;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.core.RowMapper;
+import org.springframework.stereotype.Service;
+
+@Service
+@RequiredArgsConstructor
+public class WelcomeKitReadPlatformServiceImpl implements WelcomeKitReadPlatformService {
+
+    private final JdbcTemplate jdbcTemplate;
+
+    @Override
+    public ClientWelcomeKitData retrieveWelcomeKitsByClientId(Long clientId) {
+        final WelcomeKitDispatchMapper rm = new WelcomeKitDispatchMapper();
+        final String sql = "SELECT " + rm.schema() + " WHERE w.client_id = ? ORDER BY w.created_date DESC";
+        
+        List<WelcomeKitDispatchData> dispatches = this.jdbcTemplate.query(sql, rm, clientId);
+        
+        String clientName = this.jdbcTemplate.queryForObject("SELECT display_name FROM m_client WHERE id = ?", String.class, clientId);
+        
+        boolean canDispatchNew = true;
+        if (!dispatches.isEmpty()) {
+            WelcomeKitDispatchData latest = dispatches.get(0);
+            if ("RETURNED".equals(latest.getStatus())) {
+                canDispatchNew = true;
+            } else {
+                canDispatchNew = false;
+            }
+        }
+        
+        return ClientWelcomeKitData.builder()
+                .clientName(clientName)
+                .canDispatchNew(canDispatchNew)
+                .dispatches(dispatches)
+                .build();
+    }
+
+    private static final class WelcomeKitDispatchMapper implements RowMapper<WelcomeKitDispatchData> {
+
+        public String schema() {
+            return " w.id as id, w.client_id as clientId, c.display_name as clientName, "
+                 + " w.delivery_address as deliveryAddress, w.delivery_mode as deliveryMode, "
+                 + " w.delivery_mode_other_text as deliveryModeOtherText, w.tracking_id as trackingId, "
+                 + " w.status as status, w.dispatched_on_date as dispatchedOnDate, w.delivered_on_date as deliveredOnDate "
+                 + " FROM m_welcome_kit_dispatch w "
+                 + " JOIN m_client c ON c.id = w.client_id ";
+        }
+
+        @Override
+        public WelcomeKitDispatchData mapRow(final ResultSet rs, @SuppressWarnings("unused") final int rowNum) throws SQLException {
+            final Long id = rs.getLong("id");
+            final Long clientId = rs.getLong("clientId");
+            final String clientName = rs.getString("clientName");
+            final String deliveryAddress = rs.getString("deliveryAddress");
+            final String deliveryMode = rs.getString("deliveryMode");
+            final String deliveryModeOtherText = rs.getString("deliveryModeOtherText");
+            final String trackingId = rs.getString("trackingId");
+            final String status = rs.getString("status");
+            final LocalDate dispatchedOnDate = JdbcSupport.getLocalDate(rs, "dispatchedOnDate");
+            final LocalDate deliveredOnDate = JdbcSupport.getLocalDate(rs, "deliveredOnDate");
+
+            return WelcomeKitDispatchData.builder()
+                    .id(id)
+                    .clientId(clientId)
+                    .clientName(clientName)
+                    .deliveryAddress(deliveryAddress)
+                    .deliveryMode(deliveryMode)
+                    .deliveryModeOtherText(deliveryModeOtherText)
+                    .trackingId(trackingId)
+                    .status(status)
+                    .dispatchedOnDate(dispatchedOnDate)
+                    .deliveredOnDate(deliveredOnDate)
+                    .build();
+        }
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/welcomekit/service/WelcomeKitWritePlatformService.java

@@ -0,0 +1,29 @@
+/**
+ * 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.portfolio.welcomekit.service;
+
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.data.CommandProcessingResult;
+
+public interface WelcomeKitWritePlatformService {
+
+    CommandProcessingResult dispatchWelcomeKit(Long clientId, JsonCommand command);
+
+    CommandProcessingResult updateWelcomeKitStatus(Long welcomeKitId, JsonCommand command);
+}

fineract-provider/src/main/java/org/apache/fineract/portfolio/welcomekit/service/WelcomeKitWritePlatformServiceImpl.java

@@ -0,0 +1,112 @@
+/**
+ * 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.portfolio.welcomekit.service;
+
+import java.time.LocalDate;
+import java.util.UUID;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.data.CommandProcessingResult;
+import org.apache.fineract.infrastructure.core.data.CommandProcessingResultBuilder;
+import org.apache.fineract.infrastructure.core.exception.PlatformDataIntegrityException;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.portfolio.client.domain.ClientRepositoryWrapper;
+import org.apache.fineract.portfolio.welcomekit.domain.WelcomeKitDispatch;
+import org.apache.fineract.portfolio.welcomekit.domain.WelcomeKitDispatchRepository;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+@Service
+@RequiredArgsConstructor
+public class WelcomeKitWritePlatformServiceImpl implements WelcomeKitWritePlatformService {
+
+    private final PlatformSecurityContext context;
+    private final ClientRepositoryWrapper clientRepository;
+    private final WelcomeKitDispatchRepository welcomeKitDispatchRepository;
+
+    @Transactional
+    @Override
+    public CommandProcessingResult dispatchWelcomeKit(final Long clientId, final JsonCommand command) {
+        this.context.authenticatedUser();
+
+        final Client client = this.clientRepository.findOneWithNotFoundDetection(clientId);
+
+        final String deliveryAddress = command.stringValueOfParameterNamed("deliveryAddress");
+        final String deliveryMode = command.stringValueOfParameterNamed("deliveryMode");
+        final String deliveryModeOtherText = command.stringValueOfParameterNamed("deliveryModeOtherText");
+        final LocalDate dispatchedOnDate = command.localDateValueOfParameterNamed("dispatchedOnDate");
+
+        if (deliveryAddress == null || deliveryAddress.trim().isEmpty()) {
+            throw new PlatformDataIntegrityException("error.msg.welcomekit.deliveryAddress.cannot.be.blank",
+                    "Delivery address cannot be blank.");
+        }
+        if (deliveryMode == null || deliveryMode.trim().isEmpty()) {
+            throw new PlatformDataIntegrityException("error.msg.welcomekit.deliveryMode.cannot.be.blank",
+                    "Delivery mode cannot be blank.");
+        }
+        if (dispatchedOnDate == null) {
+            throw new PlatformDataIntegrityException("error.msg.welcomekit.dispatchedOnDate.cannot.be.blank",
+                    "Dispatched on date cannot be blank.");
+        }
+
+        final String trackingId = "WK-" + UUID.randomUUID().toString().substring(0, 8).toUpperCase();
+
+        final WelcomeKitDispatch newDispatch = WelcomeKitDispatch.createNew(client, deliveryAddress, deliveryMode, deliveryModeOtherText,
+                trackingId, dispatchedOnDate);
+
+        this.welcomeKitDispatchRepository.saveAndFlush(newDispatch);
+
+        return new CommandProcessingResultBuilder()
+                .withCommandId(command.commandId())
+                .withClientId(clientId)
+                .withEntityId(newDispatch.getId())
+                .build();
+    }
+
+    @Transactional
+    @Override
+    public CommandProcessingResult updateWelcomeKitStatus(final Long welcomeKitId, final JsonCommand command) {
+        this.context.authenticatedUser();
+
+        final WelcomeKitDispatch dispatch = this.welcomeKitDispatchRepository.findById(welcomeKitId).orElseThrow(
+                () -> new PlatformDataIntegrityException("error.msg.welcomekit.not.found", "Welcome kit not found."));
+
+        final String status = command.stringValueOfParameterNamed("status");
+
+        if (status == null || status.trim().isEmpty()) {
+            throw new PlatformDataIntegrityException("error.msg.welcomekit.status.cannot.be.blank", "Status cannot be blank.");
+        }
+
+        LocalDate deliveredOnDate = null;
+        if ("DELIVERED".equals(status)) {
+            deliveredOnDate = LocalDate.now();
+        }
+
+        dispatch.updateStatus(status, deliveredOnDate);
+
+        this.welcomeKitDispatchRepository.saveAndFlush(dispatch);
+
+        return new CommandProcessingResultBuilder()
+                .withCommandId(command.commandId())
+                .withClientId(dispatch.getClient().getId())
+                .withEntityId(dispatch.getId())
+                .build();
+    }
+}

fineract-provider/src/main/resources/application.properties

@@ -46,7 +46,7 @@ fineract.security.oauth2.client.registrations.frontend-client.require-authorizat
 fineract.tenant.host=${FINERACT_DEFAULT_TENANTDB_HOSTNAME:localhost}
 fineract.tenant.port=${FINERACT_DEFAULT_TENANTDB_PORT:5432}
 fineract.tenant.username=${FINERACT_DEFAULT_TENANTDB_UID:postgres}
-fineract.tenant.password=${FINERACT_DEFAULT_TENANTDB_PWD:Keshav@898966}
+fineract.tenant.password=${FINERACT_DEFAULT_TENANTDB_PWD:313863}
 fineract.tenant.parameters=${FINERACT_DEFAULT_TENANTDB_CONN_PARAMS:}
 fineract.tenant.timezone=${FINERACT_DEFAULT_TENANTDB_TIMEZONE:Asia/Kolkata}
 fineract.tenant.identifier=${FINERACT_DEFAULT_TENANTDB_IDENTIFIER:default}
@@ -407,7 +407,7 @@ server.tomcat.mbeanregistry.enabled=${FINERACT_SERVER_TOMCAT_MBEANREGISTRY_ENABL
 spring.datasource.hikari.driverClassName=${FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME:org.postgresql.Driver}
 spring.datasource.hikari.jdbcUrl=${FINERACT_HIKARI_JDBC_URL:jdbc:postgresql://localhost:5432/fineract_tenants}
 spring.datasource.hikari.username=${FINERACT_HIKARI_USERNAME:postgres}
-spring.datasource.hikari.password=${FINERACT_HIKARI_PASSWORD:Keshav@898966}
+spring.datasource.hikari.password=${FINERACT_HIKARI_PASSWORD:313863}
 spring.datasource.hikari.minimumIdle=${FINERACT_HIKARI_MINIMUM_IDLE:3}
 spring.datasource.hikari.maximumPoolSize=${FINERACT_HIKARI_MAXIMUM_POOL_SIZE:10}
 spring.datasource.hikari.idleTimeout=${FINERACT_HIKARI_IDLE_TIMEOUT:60000}
@@ -688,6 +688,80 @@ fineract.email.from-address=${FINERACT_EMAIL_FROM_ADDRESS:no-reply@cbsnexora.com
 fineract.email.from-name=${FINERACT_EMAIL_FROM_NAME:CBSnexora}
 fineract.email.support-address=${FINERACT_EMAIL_SUPPORT_ADDRESS:support@cbsnexora.com}
 
+# ── Customer notification gateways (KYC exception outreach) ──────────────────
+# Used by the "Log Customer Contact" action on the KYC Exceptions screen: choosing SMS, Email or
+# WhatsApp transmits a notice to the customer and records the delivery outcome on the contact log.
+#
+# Email needs no configuration here — it uses the spring.mail.* SMTP settings above.
+#
+# SMS and WhatsApp are vendor-agnostic: the request shape is described by properties so switching
+# gateway is a config change. `body-template` supports {{destination}}, {{message}}, {{senderId}}
+# and {{templateId}}; values are escaped for the configured content-type at send time.
+# Both are DISABLED by default — a channel that is off records the attempt and reports
+# "not sent, no gateway configured" rather than silently claiming success.
+#
+# NOTE: this is NOT the LincPay eKYC endpoint used for login OTP above. That endpoint mints an OTP
+# of its own and cannot carry an arbitrary message; point these at a real send-message API.
+#
+# Example (MSG91 transactional SMS):
+#   fineract.notification.sms.base-url=https://control.msg91.com
+#   fineract.notification.sms.path=/api/v5/flow/
+#   fineract.notification.sms.auth-header-name=authkey
+#   fineract.notification.sms.auth-header-value=<your authkey>
+#   fineract.notification.sms.body-template={"template_id":"{{templateId}}","short_url":"0",\
+#     "recipients":[{"mobiles":"{{destination}}","MESSAGE":"{{message}}"}]}
+#   fineract.notification.sms.reference-json-path=data.messageId
+# ┌──────────────────────────────────────────────────────────────────────────┐
+# │ LOCAL TEST GATEWAY — NOT A REAL SMS PROVIDER.                            │
+# │                                                                          │
+# │ These defaults point at scratchpad/mock-sms-gateway.js on localhost so   │
+# │ the outreach flow can be demonstrated end to end. NOTHING REACHES A      │
+# │ PHONE. Every contact-log row records provider=MOCK_SMS_GATEWAY_TEST_ONLY │
+# │ so a mock send can never be mistaken for a real delivery in the audit    │
+# │ trail.                                                                   │
+# │                                                                          │
+# │ BEFORE PRODUCTION: set FINERACT_NOTIFICATION_SMS_* to the real gateway,  │
+# │ or set FINERACT_NOTIFICATION_SMS_ENABLED=false. Do not ship the mock.    │
+# └──────────────────────────────────────────────────────────────────────────┘
+fineract.notification.sms.enabled=${FINERACT_NOTIFICATION_SMS_ENABLED:true}
+fineract.notification.sms.provider=${FINERACT_NOTIFICATION_SMS_PROVIDER:MOCK_SMS_GATEWAY_TEST_ONLY}
+fineract.notification.sms.base-url=${FINERACT_NOTIFICATION_SMS_BASE_URL:http://127.0.0.1:9797}
+fineract.notification.sms.path=${FINERACT_NOTIFICATION_SMS_PATH:/send}
+fineract.notification.sms.auth-header-name=${FINERACT_NOTIFICATION_SMS_AUTH_HEADER_NAME:Authorization}
+fineract.notification.sms.auth-header-value=${FINERACT_NOTIFICATION_SMS_AUTH_HEADER_VALUE:mock-test-key}
+fineract.notification.sms.content-type=${FINERACT_NOTIFICATION_SMS_CONTENT_TYPE:application/json}
+fineract.notification.sms.body-template=${FINERACT_NOTIFICATION_SMS_BODY_TEMPLATE:{"mobileNumber":"{{destination}}","message":"{{message}}","senderId":"{{senderId}}","templateId":"{{templateId}}"\}}
+# DLT-registered sender ID and template ID — TRAI requires both for transactional SMS in India.
+fineract.notification.sms.sender-id=${FINERACT_NOTIFICATION_SMS_SENDER_ID:}
+fineract.notification.sms.template-id=${FINERACT_NOTIFICATION_SMS_TEMPLATE_ID:}
+fineract.notification.sms.reference-json-path=${FINERACT_NOTIFICATION_SMS_REFERENCE_JSON_PATH:data.messageId}
+
+# Example (Meta WhatsApp Cloud API):
+#   fineract.notification.whatsapp.base-url=https://graph.facebook.com
+#   fineract.notification.whatsapp.path=/v21.0/<phone-number-id>/messages
+#   fineract.notification.whatsapp.auth-header-value=Bearer <access token>
+#   fineract.notification.whatsapp.body-template={"messaging_product":"whatsapp",\
+#     "to":"{{destination}}","type":"text","text":{"body":"{{message}}"}}
+#   fineract.notification.whatsapp.reference-json-path=messages.0.id
+# Business-initiated messages outside the 24h service window must use an approved template, so a
+# KYC notice will normally need the template-shaped body rather than the plain "text" one above.
+# Also pointed at the LOCAL TEST GATEWAY above — see that banner. Nothing reaches WhatsApp.
+fineract.notification.whatsapp.enabled=${FINERACT_NOTIFICATION_WHATSAPP_ENABLED:true}
+fineract.notification.whatsapp.provider=${FINERACT_NOTIFICATION_WHATSAPP_PROVIDER:MOCK_WHATSAPP_GATEWAY_TEST_ONLY}
+fineract.notification.whatsapp.base-url=${FINERACT_NOTIFICATION_WHATSAPP_BASE_URL:http://127.0.0.1:9797}
+fineract.notification.whatsapp.path=${FINERACT_NOTIFICATION_WHATSAPP_PATH:/send}
+fineract.notification.whatsapp.auth-header-name=${FINERACT_NOTIFICATION_WHATSAPP_AUTH_HEADER_NAME:Authorization}
+fineract.notification.whatsapp.auth-header-value=${FINERACT_NOTIFICATION_WHATSAPP_AUTH_HEADER_VALUE:mock-test-key}
+fineract.notification.whatsapp.content-type=${FINERACT_NOTIFICATION_WHATSAPP_CONTENT_TYPE:application/json}
+fineract.notification.whatsapp.body-template=${FINERACT_NOTIFICATION_WHATSAPP_BODY_TEMPLATE:{"to":"{{destination}}","message":"{{message}}"\}}
+fineract.notification.whatsapp.sender-id=${FINERACT_NOTIFICATION_WHATSAPP_SENDER_ID:}
+fineract.notification.whatsapp.template-id=${FINERACT_NOTIFICATION_WHATSAPP_TEMPLATE_ID:}
+fineract.notification.whatsapp.reference-json-path=${FINERACT_NOTIFICATION_WHATSAPP_REFERENCE_JSON_PATH:data.messageId}
+fineract.notification.whatsapp.country-code=${FINERACT_NOTIFICATION_WHATSAPP_COUNTRY_CODE:91}
+
+# Days the customer is given to complete KYC, quoted in the notice body.
+fineract.notification.kyc-contact.response-days=${FINERACT_NOTIFICATION_KYC_RESPONSE_DAYS:15}
+
 # Frontend base URL — used for email links (voting, etc.)
 cbs.frontend.base-url=${CBS_FRONTEND_BASE_URL:https://cbs.godemo.in}
 

fineract-provider/src/main/resources/db/changelog/tenant/changelog-tenant.xml

@@ -435,6 +435,7 @@
     <include file="parts/0412_activate_outward_clearing_batch_job.xml" relativeToChangelogFile="true"/>
     <include file="parts/0413_inward_item_verify_signature_permission.xml" relativeToChangelogFile="true"/>
     <include file="parts/0414_inward_item_full_source_details.xml" relativeToChangelogFile="true"/>
+    <include file="parts/0415_welcome_kit_dispatch.xml" relativeToChangelogFile="true"/>
     <include file="parts/0415_add_otp_delivery_method_and_first_login_gate_to_appuser.xml" relativeToChangelogFile="true"/>
     <include file="parts/0416_create_user_agreement_tables.xml" relativeToChangelogFile="true"/>
     <include file="parts/0417_add_first_login_gate_config.xml" relativeToChangelogFile="true"/>
@@ -490,4 +491,11 @@
     <include file="parts/0435_add_aml_officer_and_principal_officer_roles.xml" relativeToChangelogFile="true"/>
     <include file="parts/0436_fix_missing_client_risk_rule_columns.xml" relativeToChangelogFile="true"/>
     <include file="parts/0437_update_aml_columns_for_risk_rules.xml" relativeToChangelogFile="true"/>
+    <include file="parts/0438_share_account_withdrawal_governance.xml" relativeToChangelogFile="true"/>
+    <include file="parts/0439_create_clerk_share_withdrawal_request.xml" relativeToChangelogFile="true"/>
+    <include file="parts/0440_seed_share_redemption_payment_type.xml" relativeToChangelogFile="true"/>
+    <include file="parts/0441_add_settlement_payment_type_to_clerk_share_withdrawal_request.xml" relativeToChangelogFile="true"/>
+    <include file="parts/0442_add_settlement_row_snapshot_to_clerk_share_withdrawal_request.xml" relativeToChangelogFile="true"/>
+    <include file="parts/0444_add_kyc_exception_fields.xml" relativeToChangelogFile="true"/>
+    <include file="parts/0445_create_kyc_contact_log.xml" relativeToChangelogFile="true"/>
 </databaseChangeLog>

fineract-provider/src/main/resources/db/changelog/tenant/parts/0345_add_sponsor_dd_payable_gl_account_sbi.xml

@@ -23,24 +23,32 @@
 
     <!-- Dedicated liability GL account for the Sponsor DD Payable balance owed to SBI, as a child
          of the existing "OTHER LIABILITY" account (gl_code 9), matching the pattern already used
-         by "INTEREST PAYABLE" (gl_code 9.2). -->
-    <changeSet author="fineract" id="0345-1-insert-sponsor-dd-payable-sbi-gl-account">
+         by "INTEREST PAYABLE" (gl_code 9.2).
+
+         parent_id is resolved by gl_code (not hardcoded) — the "OTHER LIABILITY" row's numeric id
+         is an auto-increment value that depends on each tenant's own insert history, so a
+         hardcoded id (previously 22) only happened to match the `default` tenant and broke FK
+         inserts on any tenant whose chart of accounts was seeded differently (e.g. `saga`), which
+         aborted that tenant's whole Liquibase run — and with it, the entire application startup.
+         runOnChange lets this corrected version safely re-validate on tenants where the old,
+         already-recorded version succeeded: the "gl_code 9.3 doesn't exist yet" precondition below
+         is already false there, so it's skipped rather than re-inserted. -->
+    <changeSet author="fineract" id="0345-1-insert-sponsor-dd-payable-sbi-gl-account" runOnChange="true">
         <preConditions onFail="MARK_RAN">
-            <not>
-                <sqlCheck expectedResult="1">select count(*) from acc_gl_account where gl_code = '9.3'</sqlCheck>
-            </not>
+            <and>
+                <not>
+                    <sqlCheck expectedResult="1">select count(*) from acc_gl_account where gl_code = '9.3'</sqlCheck>
+                </not>
+                <sqlCheck expectedResult="1">select count(*) from acc_gl_account where gl_code = '9'</sqlCheck>
+            </and>
         </preConditions>
-        <insert tableName="acc_gl_account">
-            <column name="name" value="Sponsor DD Payable - SBI"/>
-            <column name="gl_code" value="9.3"/>
-            <column name="parent_id" valueNumeric="22"/>
-            <column name="hierarchy" value="."/>
-            <column name="account_usage" valueNumeric="1"/>
-            <column name="classification_enum" valueNumeric="2"/>
-            <column name="disabled" valueBoolean="false"/>
-            <column name="manual_journal_entries_allowed" valueBoolean="true"/>
-            <column name="description" value="Liability owed to SBI for sponsor bank demand drafts issued on their behalf, pending clearing."/>
-        </insert>
+        <sql>
+            INSERT INTO acc_gl_account (name, gl_code, parent_id, hierarchy, account_usage, classification_enum, disabled, manual_journal_entries_allowed, description)
+            SELECT 'Sponsor DD Payable - SBI', '9.3', parent.id, '.', 1, 2, FALSE, TRUE,
+                   'Liability owed to SBI for sponsor bank demand drafts issued on their behalf, pending clearing.'
+            FROM acc_gl_account parent
+            WHERE parent.gl_code = '9';
+        </sql>
     </changeSet>
 
     <!-- Fineract's GL hierarchy path embeds the row's own auto-generated id, so it can only be

fineract-provider/src/main/resources/db/changelog/tenant/parts/0415_welcome_kit_dispatch.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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.1.xsd">
+
+    <changeSet id="0415_welcome_kit_dispatch" author="CBS" runOnChange="false">
+        <sql>
+            CREATE TABLE m_welcome_kit_dispatch (
+                id BIGSERIAL PRIMARY KEY,
+                client_id BIGINT NOT NULL REFERENCES m_client(id),
+                delivery_address VARCHAR(500) NOT NULL,
+                delivery_mode VARCHAR(50) NOT NULL,
+                delivery_mode_other_text VARCHAR(255),
+                tracking_id VARCHAR(100) NOT NULL UNIQUE,
+                status VARCHAR(30) NOT NULL DEFAULT 'DISPATCHED',
+                dispatched_on_date DATE NOT NULL,
+                delivered_on_date DATE,
+                created_by BIGINT,
+                created_date TIMESTAMP NOT NULL DEFAULT NOW(),
+                last_modified_by BIGINT,
+                last_modified_date TIMESTAMP
+            );
+
+            INSERT INTO m_permission (grouping, code, entity_name, action_name, can_maker_checker)
+            SELECT 'portfolio', 'READ_WELCOMEKIT', 'WELCOMEKIT', 'READ', false
+            WHERE NOT EXISTS (SELECT 1 FROM m_permission WHERE code = 'READ_WELCOMEKIT');
+
+            INSERT INTO m_permission (grouping, code, entity_name, action_name, can_maker_checker)
+            SELECT 'portfolio', 'CREATE_WELCOMEKIT', 'WELCOMEKIT', 'CREATE', false
+            WHERE NOT EXISTS (SELECT 1 FROM m_permission WHERE code = 'CREATE_WELCOMEKIT');
+
+            INSERT INTO m_permission (grouping, code, entity_name, action_name, can_maker_checker)
+            SELECT 'portfolio', 'UPDATE_WELCOMEKIT', 'WELCOMEKIT', 'UPDATE', false
+            WHERE NOT EXISTS (SELECT 1 FROM m_permission WHERE code = 'UPDATE_WELCOMEKIT');
+        </sql>
+    </changeSet>
+
+</databaseChangeLog>

fineract-provider/src/main/resources/db/changelog/tenant/parts/0434_seed_aml_transaction_rules.xml

@@ -32,6 +32,13 @@
         Threshold numbers marked "illustrative default" mirror the bank's own Rules Parameter
         screens where a configured value was available (Rules 1, 6, 10, 11, 12, 13); others are
         reasonable starting points meant to be tuned via the AML rule administration UI.
+
+        order_position is only unique WITHIN 0430's own 221-row insert - it collides with the
+        older, differently-numbered seed rows from 0428_add_client_risk_rules.xml (e.g. both
+        insert a row at order_position 10 and 30), which made every subquery below ambiguous
+        ("more than one row returned") and aborted the whole tenant migration. aml_check_status
+        is populated only on 0430's rows (0428's predate that column and are NULL there), so
+        pairing it with order_position uniquely targets the intended 0430 row.
     -->
     <changeSet author="fineract" id="0434-1">
         <preConditions onFail="MARK_RAN">
@@ -42,19 +49,19 @@
             VALUES
             ('CTR_THRESHOLD_10L', 'Mandatory CTR reporting threshold - single cash transaction of INR 10,00,000 or more', 'ALL', 1000000, 'THRESHOLD', null, null, true),
             ('STRUCTURED_CTR_10L_MONTHLY', 'Connected cash transactions summing to INR 10,00,000 or more within a calendar month (CTR aggregation rule)', 'ALL', 1000000, 'STRUCTURING', 30, null, true),
-            ('LARGE_CASH_TXN_25L', 'Large cash transaction', 'ALL', 2500000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 6), true),
-            ('STRUCTURING_BELOW_10L', 'Splitting of cash deposits just below INR 10,00,000 in multiple accounts in a month', 'SAVINGS', 1000000, 'STRUCTURING', 30, (SELECT id FROM m_client_risk_rule WHERE order_position = 28), true),
-            ('STRUCTURING_BELOW_50K', 'Splitting of cash deposits just below INR 50,000', 'SAVINGS', 50000, 'STRUCTURING', 30, (SELECT id FROM m_client_risk_rule WHERE order_position = 29), true),
-            ('FREQUENT_LOW_CASH_DEPOSIT', 'Frequent low cash deposits', 'SAVINGS', 50000, 'VELOCITY', 7, (SELECT id FROM m_client_risk_rule WHERE order_position = 30), true),
-            ('FREQUENT_LOW_CASH_WITHDRAWAL', 'Frequent low cash withdrawals', 'SAVINGS', 50000, 'VELOCITY', 7, (SELECT id FROM m_client_risk_rule WHERE order_position = 31), true),
-            ('FREQUENT_CASH_NEAR_10L', 'Frequent cash deposits just below INR 10,00,000', 'SAVINGS', 1000000, 'STRUCTURING', 30, (SELECT id FROM m_client_risk_rule WHERE order_position = 65), true),
-            ('RTGS_HIGH_VALUE', 'Monitoring RTGS Transactions', 'TRANSFER', 2000000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 12), true),
-            ('JEWELLER_ACCOUNT_LARGE_TXN', 'Monitoring accounts of Jewellers', 'ALL', 2000000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 13), true),
-            ('CHARITABLE_ORG_CASH_WITHDRAWAL', 'Substantial cash withdrawals in accounts of charitable organization', 'SAVINGS', 50000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 10), true),
-            ('PEP_ACCOUNT_MONITORING', 'Monitoring accounts of PEP (politically exposed person)', 'ALL', 50000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 11), true),
-            ('NEW_ACCOUNT_LARGE_TXN', 'New account Large transaction', 'ALL', 500000, 'THRESHOLD', 30, (SELECT id FROM m_client_risk_rule WHERE order_position = 14), true),
-            ('RAPID_MOVEMENT_IN_ACCOUNTS', 'Rapid Movement in accounts (same-day credit followed by debit)', 'SAVINGS', null, 'VELOCITY', 1, (SELECT id FROM m_client_risk_rule WHERE order_position = 24), true),
-            ('LOAN_REPAYMENT_IN_CASH', 'Repayment of loan in cash', 'LOAN', 200000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 73), true);
+            ('LARGE_CASH_TXN_25L', 'Large cash transaction', 'ALL', 2500000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 6 AND aml_check_status IS NOT NULL), true),
+            ('STRUCTURING_BELOW_10L', 'Splitting of cash deposits just below INR 10,00,000 in multiple accounts in a month', 'SAVINGS', 1000000, 'STRUCTURING', 30, (SELECT id FROM m_client_risk_rule WHERE order_position = 28 AND aml_check_status IS NOT NULL), true),
+            ('STRUCTURING_BELOW_50K', 'Splitting of cash deposits just below INR 50,000', 'SAVINGS', 50000, 'STRUCTURING', 30, (SELECT id FROM m_client_risk_rule WHERE order_position = 29 AND aml_check_status IS NOT NULL), true),
+            ('FREQUENT_LOW_CASH_DEPOSIT', 'Frequent low cash deposits', 'SAVINGS', 50000, 'VELOCITY', 7, (SELECT id FROM m_client_risk_rule WHERE order_position = 30 AND aml_check_status IS NOT NULL), true),
+            ('FREQUENT_LOW_CASH_WITHDRAWAL', 'Frequent low cash withdrawals', 'SAVINGS', 50000, 'VELOCITY', 7, (SELECT id FROM m_client_risk_rule WHERE order_position = 31 AND aml_check_status IS NOT NULL), true),
+            ('FREQUENT_CASH_NEAR_10L', 'Frequent cash deposits just below INR 10,00,000', 'SAVINGS', 1000000, 'STRUCTURING', 30, (SELECT id FROM m_client_risk_rule WHERE order_position = 65 AND aml_check_status IS NOT NULL), true),
+            ('RTGS_HIGH_VALUE', 'Monitoring RTGS Transactions', 'TRANSFER', 2000000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 12 AND aml_check_status IS NOT NULL), true),
+            ('JEWELLER_ACCOUNT_LARGE_TXN', 'Monitoring accounts of Jewellers', 'ALL', 2000000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 13 AND aml_check_status IS NOT NULL), true),
+            ('CHARITABLE_ORG_CASH_WITHDRAWAL', 'Substantial cash withdrawals in accounts of charitable organization', 'SAVINGS', 50000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 10 AND aml_check_status IS NOT NULL), true),
+            ('PEP_ACCOUNT_MONITORING', 'Monitoring accounts of PEP (politically exposed person)', 'ALL', 50000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 11 AND aml_check_status IS NOT NULL), true),
+            ('NEW_ACCOUNT_LARGE_TXN', 'New account Large transaction', 'ALL', 500000, 'THRESHOLD', 30, (SELECT id FROM m_client_risk_rule WHERE order_position = 14 AND aml_check_status IS NOT NULL), true),
+            ('RAPID_MOVEMENT_IN_ACCOUNTS', 'Rapid Movement in accounts (same-day credit followed by debit)', 'SAVINGS', null, 'VELOCITY', 1, (SELECT id FROM m_client_risk_rule WHERE order_position = 24 AND aml_check_status IS NOT NULL), true),
+            ('LOAN_REPAYMENT_IN_CASH', 'Repayment of loan in cash', 'LOAN', 200000, 'THRESHOLD', null, (SELECT id FROM m_client_risk_rule WHERE order_position = 73 AND aml_check_status IS NOT NULL), true);
         </sql>
     </changeSet>
 

fineract-provider/src/main/resources/db/changelog/tenant/parts/0438_share_account_withdrawal_governance.xml

@@ -0,0 +1,60 @@
+<?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.13.xsd">
+
+    <!--
+        Share withdrawal governance: a share account may optionally be linked to a loan (held
+        as margin/security) so a redeem-shares request can be checked against that loan's
+        outstanding balance; a redeem transaction records the Board Resolution Number and Date
+        of Meeting that authorised it.
+    -->
+    <changeSet author="fineract" id="0438-1">
+        <preConditions onFail="MARK_RAN">
+            <not><columnExists tableName="m_share_account" columnName="linked_loan_id"/></not>
+        </preConditions>
+        <addColumn tableName="m_share_account">
+            <column name="linked_loan_id" type="BIGINT"/>
+        </addColumn>
+    </changeSet>
+
+    <changeSet author="fineract" id="0438-2">
+        <preConditions onFail="MARK_RAN">
+            <not><foreignKeyConstraintExists foreignKeyName="FK_m_share_account_linked_loan_id"/></not>
+        </preConditions>
+        <addForeignKeyConstraint baseTableName="m_share_account" baseColumnNames="linked_loan_id"
+                                 referencedTableName="m_loan" referencedColumnNames="id"
+                                 constraintName="FK_m_share_account_linked_loan_id" />
+    </changeSet>
+
+    <changeSet author="fineract" id="0438-3">
+        <preConditions onFail="MARK_RAN">
+            <not><columnExists tableName="m_share_account_transactions" columnName="resolution_number"/></not>
+        </preConditions>
+        <addColumn tableName="m_share_account_transactions">
+            <column name="resolution_number" type="VARCHAR(100)"/>
+            <column name="meeting_date" type="DATE"/>
+        </addColumn>
+    </changeSet>
+
+</databaseChangeLog>

fineract-provider/src/main/resources/db/changelog/tenant/parts/0439_create_clerk_share_withdrawal_request.xml

@@ -0,0 +1,90 @@
+<?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.1.xsd">
+
+    <!--
+        Maker-checker for Share Account withdrawal (redeem shares) requests, submitted only from
+        the Clerk Dashboard — mirrors m_clerk_withdrawal_request (cash withdrawal), but records the
+        Board Resolution Number / Date of Meeting a share withdrawal is governed by, and links to a
+        Share Account instead of a Savings/Current account.
+    -->
+    <changeSet id="0439_create_clerk_share_withdrawal_request" author="CBS">
+        <createTable tableName="m_clerk_share_withdrawal_request">
+            <column name="id" type="BIGINT" autoIncrement="true">
+                <constraints primaryKey="true" nullable="false"/>
+            </column>
+            <column name="share_account_id" type="BIGINT">
+                <constraints nullable="false"/>
+            </column>
+            <column name="account_no" type="VARCHAR(50)">
+                <constraints nullable="false"/>
+            </column>
+            <column name="client_id" type="BIGINT"/>
+            <column name="client_name" type="VARCHAR(255)"/>
+            <column name="requested_shares" type="BIGINT">
+                <constraints nullable="false"/>
+            </column>
+            <column name="requested_date" type="DATE">
+                <constraints nullable="false"/>
+            </column>
+            <column name="resolution_number" type="VARCHAR(100)">
+                <constraints nullable="false"/>
+            </column>
+            <column name="meeting_date" type="DATE">
+                <constraints nullable="false"/>
+            </column>
+            <column name="description" type="TEXT"/>
+            <column name="status" type="VARCHAR(20)" defaultValue="PENDING">
+                <constraints nullable="false"/>
+            </column>
+            <column name="clerk_id" type="BIGINT"/>
+            <column name="clerk_name" type="VARCHAR(255)"/>
+            <column name="clerk_username" type="VARCHAR(100)"/>
+            <column name="manager_id" type="BIGINT"/>
+            <column name="manager_name" type="VARCHAR(255)"/>
+            <column name="manager_username" type="VARCHAR(100)"/>
+            <column name="rejection_reason" type="TEXT"/>
+            <column name="share_transaction_id" type="VARCHAR(100)"/>
+            <column name="activity_log" type="TEXT"/>
+            <column name="submitted_at" type="TIMESTAMP" defaultValueComputed="CURRENT_TIMESTAMP">
+                <constraints nullable="false"/>
+            </column>
+            <column name="actioned_at" type="TIMESTAMP"/>
+        </createTable>
+
+        <createIndex tableName="m_clerk_share_withdrawal_request" indexName="idx_cswr_status">
+            <column name="status"/>
+        </createIndex>
+        <createIndex tableName="m_clerk_share_withdrawal_request" indexName="idx_cswr_clerk_id">
+            <column name="clerk_id"/>
+        </createIndex>
+        <createIndex tableName="m_clerk_share_withdrawal_request" indexName="idx_cswr_submitted_at">
+            <column name="submitted_at"/>
+        </createIndex>
+        <createIndex tableName="m_clerk_share_withdrawal_request" indexName="idx_cswr_share_account_id">
+            <column name="share_account_id"/>
+        </createIndex>
+    </changeSet>
+
+</databaseChangeLog>

fineract-provider/src/main/resources/db/changelog/tenant/parts/0440_seed_share_redemption_payment_type.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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.1.xsd">
+
+    <!-- Real-world UCB practice: a share redemption's value is never handed over as cash from the
+         Share department — it is a book-transfer credited to the member's linked savings account
+         (Dr Share Capital, Cr Savings Control). This is a deliberate, manual SECOND entry the clerk
+         makes on the Transaction Entry screen (Deposit Slip on the linked savings account) after the
+         Share Withdrawal Request is approved and shares are redeemed — the redemption itself never
+         triggers this automatically. This Payment Type is the fund-source channel that drives correct
+         GL routing for that manual deposit; an accountant maps it to the Share Capital GL account via
+         the existing "Map Payment Types to Specific Funds" screen (we intentionally do NOT hardcode a
+         GL account id here — see 0345's fix for why a tenant-specific GL id baked into a migration
+         breaks on any tenant seeded differently). runOnChange lets this file's wording/flag tweaks
+         safely re-validate on any environment where it already ran — the "not already seeded"
+         precondition below is already false there, so it's skipped rather than re-inserted. -->
+    <changeSet author="fineract" id="0440-1-seed-share-redemption-payment-type" runOnChange="true">
+        <preConditions onFail="MARK_RAN">
+            <sqlCheck expectedResult="0">select count(*) from m_payment_type where code_name = 'SHARE_REDEMPTION_TRANSFER'</sqlCheck>
+        </preConditions>
+        <insert tableName="m_payment_type">
+            <column name="value" value="Share Redemption Transfer"/>
+            <column name="description" value="Manual book-transfer settlement of a share redemption to the member's linked savings account"/>
+            <column name="is_cash_payment" valueBoolean="false"/>
+            <column name="order_position" valueNumeric="0"/>
+            <column name="code_name" value="SHARE_REDEMPTION_TRANSFER"/>
+            <column name="is_system_defined" valueBoolean="false"/>
+        </insert>
+    </changeSet>
+
+</databaseChangeLog>

fineract-provider/src/main/resources/db/changelog/tenant/parts/0441_add_settlement_payment_type_to_clerk_share_withdrawal_request.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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.1.xsd">
+
+    <!-- The clerk picks which Payment Type the settlement deposit (credit to the linked savings
+         account) should use — this is captured at submit time, persisted here, validated (must not
+         be a cash payment type — settlement is always a book-transfer), and then actually used at
+         approval time instead of a hardcoded payment type lookup. Each column below is its own
+         changeset with its own existence guard — an earlier, now-superseded revision of this file
+         already created settlement_amount/settlement_savings_transaction_id on some environments
+         (including local dev), so a single combined addColumn would fail wherever those two already
+         exist but settlement_payment_type_id does not. -->
+    <changeSet author="fineract" id="0441-1-add-settlement-payment-type-id">
+        <preConditions onFail="MARK_RAN">
+            <not>
+                <columnExists tableName="m_clerk_share_withdrawal_request" columnName="settlement_payment_type_id"/>
+            </not>
+        </preConditions>
+        <addColumn tableName="m_clerk_share_withdrawal_request">
+            <column name="settlement_payment_type_id" type="BIGINT">
+                <constraints nullable="true" foreignKeyName="fk_clerk_share_wd_settlement_pt" references="m_payment_type(id)"/>
+            </column>
+        </addColumn>
+    </changeSet>
+
+    <changeSet author="fineract" id="0441-2-add-settlement-amount">
+        <preConditions onFail="MARK_RAN">
+            <not>
+                <columnExists tableName="m_clerk_share_withdrawal_request" columnName="settlement_amount"/>
+            </not>
+        </preConditions>
+        <addColumn tableName="m_clerk_share_withdrawal_request">
+            <column name="settlement_amount" type="DECIMAL(19,6)">
+                <constraints nullable="true"/>
+            </column>
+        </addColumn>
+    </changeSet>
+
+    <changeSet author="fineract" id="0441-3-add-settlement-savings-transaction-id">
+        <preConditions onFail="MARK_RAN">
+            <not>
+                <columnExists tableName="m_clerk_share_withdrawal_request" columnName="settlement_savings_transaction_id"/>
+            </not>
+        </preConditions>
+        <addColumn tableName="m_clerk_share_withdrawal_request">
+            <column name="settlement_savings_transaction_id" type="BIGINT">
+                <constraints nullable="true"/>
+            </column>
+        </addColumn>
+    </changeSet>
+
+</databaseChangeLog>

fineract-provider/src/main/resources/db/changelog/tenant/parts/0442_add_settlement_row_snapshot_to_clerk_share_withdrawal_request.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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.1.xsd">
+
+    <!-- Captures a full snapshot (as submitted JSON) of the CR/settlement row the clerk filled in on
+         the "Enter Bank Transfer" screen — account no., ECS a/c no., amount, cheque no./date, token
+         no., description, bank name, routing code — for audit purposes, alongside the columns that
+         already exist for the DR (Share) row's own fields (resolution_number, meeting_date, etc). -->
+    <changeSet author="fineract" id="0442-1-add-settlement-row-snapshot">
+        <preConditions onFail="MARK_RAN">
+            <not>
+                <columnExists tableName="m_clerk_share_withdrawal_request" columnName="settlement_row_snapshot"/>
+            </not>
+        </preConditions>
+        <addColumn tableName="m_clerk_share_withdrawal_request">
+            <column name="settlement_row_snapshot" type="TEXT">
+                <constraints nullable="true"/>
+            </column>
+        </addColumn>
+    </changeSet>
+
+</databaseChangeLog>

fineract-provider/src/main/resources/db/changelog/tenant/parts/0444_add_kyc_exception_fields.xml

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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.1.xsd">
+
+    <changeSet id="0444-kyc-is-exception" author="Antigravity">
+        <preConditions onFail="MARK_RAN">
+            <not><columnExists tableName="m_client_kyc" columnName="is_exception"/></not>
+        </preConditions>
+        <addColumn tableName="m_client_kyc">
+            <column name="is_exception" type="BOOLEAN" defaultValueBoolean="false">
+                <constraints nullable="false"/>
+            </column>
+        </addColumn>
+    </changeSet>
+
+    <changeSet id="0444-kyc-exception-reason" author="Antigravity">
+        <preConditions onFail="MARK_RAN">
+            <not><columnExists tableName="m_client_kyc" columnName="exception_reason"/></not>
+        </preConditions>
+        <addColumn tableName="m_client_kyc">
+            <column name="exception_reason" type="VARCHAR(200)"/>
+        </addColumn>
+    </changeSet>
+
+    <changeSet id="0444-kyc-exception-resolved" author="Antigravity">
+        <preConditions onFail="MARK_RAN">
+            <not><columnExists tableName="m_client_kyc" columnName="exception_resolved"/></not>
+        </preConditions>
+        <addColumn tableName="m_client_kyc">
+            <column name="exception_resolved" type="BOOLEAN" defaultValueBoolean="false">
+                <constraints nullable="false"/>
+            </column>
+        </addColumn>
+    </changeSet>
+
+    <changeSet id="0444-kyc-exception-resolved-on" author="Antigravity">
+        <preConditions onFail="MARK_RAN">
+            <not><columnExists tableName="m_client_kyc" columnName="exception_resolved_on"/></not>
+        </preConditions>
+        <addColumn tableName="m_client_kyc">
+            <column name="exception_resolved_on" type="DATE"/>
+        </addColumn>
+    </changeSet>
+</databaseChangeLog>

fineract-provider/src/main/resources/db/changelog/tenant/parts/0445_create_kyc_contact_log.xml

@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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.1.xsd">
+
+    <!--
+      Audit trail of every attempt a KYC officer makes to reach a customer about an open KYC
+      exception. Two kinds of row land here and they must stay distinguishable:
+
+        * OFFLINE channels (PHONE_CALL / BRANCH_VISIT / FIELD_VISIT) — the officer is recording
+          something that already happened away from the system. delivery_status is NOT_APPLICABLE.
+        * SENDING channels (SMS / EMAIL / WHATSAPP) — the platform actually transmits a notice.
+          delivery_status records what the gateway said, so a failed send can never be mistaken
+          for a delivered one during an RBI inspection.
+    -->
+    <changeSet id="0445-create-client-kyc-contact-log" author="Antigravity">
+        <preConditions onFail="MARK_RAN">
+            <not><tableExists tableName="m_client_kyc_contact_log"/></not>
+        </preConditions>
+        <createTable tableName="m_client_kyc_contact_log">
+            <column name="id" type="BIGINT" autoIncrement="true">
+                <constraints primaryKey="true" nullable="false"/>
+            </column>
+            <column name="client_id" type="BIGINT">
+                <constraints nullable="false"/>
+            </column>
+            <column name="kyc_id" type="BIGINT"/>
+
+            <!-- PHONE_CALL | SMS | EMAIL | WHATSAPP | BRANCH_VISIT | FIELD_VISIT -->
+            <column name="channel" type="VARCHAR(20)">
+                <constraints nullable="false"/>
+            </column>
+
+            <!-- Free-text summary the officer typed. Mandatory: this is the compliance narrative. -->
+            <column name="notes" type="VARCHAR(1000)">
+                <constraints nullable="false"/>
+            </column>
+
+            <!-- Officer as selected in the dialog, plus the authenticated user who really saved it. -->
+            <column name="officer_name" type="VARCHAR(200)"/>
+            <column name="logged_by_user_id" type="BIGINT"/>
+
+            <!-- Snapshot of the KYC exception reason at the time of contact. -->
+            <column name="exception_reason" type="VARCHAR(200)"/>
+
+            <!-- NOT_APPLICABLE | SENT | FAILED | SKIPPED_NO_DESTINATION | PROVIDER_NOT_CONFIGURED -->
+            <column name="delivery_status" type="VARCHAR(30)" defaultValue="NOT_APPLICABLE">
+                <constraints nullable="false"/>
+            </column>
+            <!-- Masked destination only (+91-XXXXX-1234 / a****@x.com). Never store it unmasked. -->
+            <column name="destination_masked" type="VARCHAR(120)"/>
+            <column name="provider" type="VARCHAR(40)"/>
+            <column name="provider_reference" type="VARCHAR(120)"/>
+            <column name="failure_reason" type="VARCHAR(500)"/>
+            <!-- Exact body transmitted, so the bank can prove what the customer was told. -->
+            <column name="message_body" type="VARCHAR(2000)"/>
+
+            <column name="contacted_at" type="DATETIME">
+                <constraints nullable="false"/>
+            </column>
+            <column name="created_at" type="DATETIME">
+                <constraints nullable="false"/>
+            </column>
+        </createTable>
+
+        <addForeignKeyConstraint baseTableName="m_client_kyc_contact_log"
+                                 baseColumnNames="client_id"
+                                 constraintName="fk_kyc_contact_log_client"
+                                 referencedTableName="m_client"
+                                 referencedColumnNames="id"/>
+
+        <createIndex tableName="m_client_kyc_contact_log" indexName="idx_kyc_contact_log_client">
+            <column name="client_id"/>
+        </createIndex>
+        <createIndex tableName="m_client_kyc_contact_log" indexName="idx_kyc_contact_log_contacted_at">
+            <column name="contacted_at"/>
+        </createIndex>
+    </changeSet>
+</databaseChangeLog>

gradle.properties

@@ -16,10 +16,11 @@
 # specific language governing permissions and limitations
 # under the License.
 #
-org.gradle.jvmargs=-Xmx6g --add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-exports=java.naming/com.sun.jndi.ldap=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.security=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.management/javax.management=ALL-UNNAMED --add-opens=java.naming/javax.naming=ALL-UNNAMED --add-opens=java.rmi/sun.rmi.transport=null
+org.gradle.jvmargs=-Xmx8g -XX:MaxMetaspaceSize=1g --add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-exports=java.naming/com.sun.jndi.ldap=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.security=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.management/javax.management=ALL-UNNAMED --add-opens=java.naming/javax.naming=ALL-UNNAMED --add-opens=java.rmi/sun.rmi.transport=null
 buildType=BUILD
 org.gradle.caching=true
 org.gradle.parallel=true
+org.gradle.workers.max=2
 org.gradle.daemon.idletimeout=10800000
 # Temporarily disabled until we fix configuration cache compatibility
 #org.gradle.configuration-cache=true

rcmainresourcesdbchangelogtenantchangelog-tenant.xml

@@ -0,0 +1,10 @@
+17e0dab43 Merge branch 'dev' of https://git.lincpay.tech/CBSNexora/cbsnexora-backend into dev
+67810bfae Add Welcome Kit Dispatch feature and Share Account summary API
+7c15fbb0c fix(documentmanagement): close leaked file handles causing Windows re-upload failures; add entity KYC document CodeValues
+6e3f195de Merge remote-tracking branch 'origin/uate' into uate
+a65d80125 feat(clients): maker-checker for client creation and edits (backend)
+f45d5890e CTR/STR report and Risk Category auto mark on bases of person occupation and anual salary enter
+3c58bb231 fix(clients): pwdCategoryOptions on edit template, minor-age threshold to 18, minor KYC identity-proof bypass
+aabda18b6 feat(clients): enforce Mother + Father/Caretaker family members on client activation
+0e5671b70 Merge remote-tracking branch 'origin/uate' into uate
+67214ec0f fix(clients): stale signature bug, CKYC fixes, monthly turnover/annual income, senior citizen/PWD classification

test_welcomekit.ps1

@@ -0,0 +1,46 @@
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}
+
+$headers = @{
+    "fineract-platform-tenantid" = "default"
+    "Content-Type" = "application/json"
+}
+$body = '{"username":"mifos", "password":"password"}'
+
+Write-Host "--- AUTHENTICATION ---"
+$authResponse = Invoke-RestMethod -Method Post -Uri "https://localhost:8443/fineract-provider/api/v1/authentication?username=mifos&password=password" -Headers $headers
+$authKey = $authResponse.base64EncodedAuthenticationKey
+$headers.Add("Authorization", "Basic $authKey")
+
+Write-Host "`n--- 1. GET /v1/clients/95/welcomekit ---"
+$res1 = Invoke-RestMethod -Method Get -Uri "https://localhost:8443/fineract-provider/api/v1/clients/95/welcomekit" -Headers $headers
+$res1 | ConvertTo-Json -Depth 10
+
+Write-Host "`n--- 2. POST /v1/clients/95/welcomekit ---"
+$postBody = @{
+    deliveryAddress = "123 Main St, Springfield"
+    deliveryMode = "POSTMAN"
+    dispatchedOnDate = "30 July 2026"
+    dateFormat = "dd MMMM yyyy"
+    locale = "en"
+} | ConvertTo-Json
+Write-Host "Request Body: $postBody"
+$res2 = Invoke-RestMethod -Method Post -Uri "https://localhost:8443/fineract-provider/api/v1/clients/95/welcomekit" -Headers $headers -Body $postBody
+$res2 | ConvertTo-Json -Depth 10
+$welcomeKitId = $res2.resourceId
+
+Write-Host "`n--- 3. GET /v1/clients/95/welcomekit (after POST) ---"
+$res3 = Invoke-RestMethod -Method Get -Uri "https://localhost:8443/fineract-provider/api/v1/clients/95/welcomekit" -Headers $headers
+$res3 | ConvertTo-Json -Depth 10
+
+Write-Host "`n--- 4. PUT /v1/welcomekit/$welcomeKitId ---"
+$putBody = @{
+    status = "DELIVERED"
+} | ConvertTo-Json
+Write-Host "Request Body: $putBody"
+$res4 = Invoke-RestMethod -Method Put -Uri "https://localhost:8443/fineract-provider/api/v1/welcomekit/$welcomeKitId" -Headers $headers -Body $putBody
+$res4 | ConvertTo-Json -Depth 10
+
+Write-Host "`n--- 5. GET /v1/clients/95/welcomekit (after PUT) ---"
+$res5 = Invoke-RestMethod -Method Get -Uri "https://localhost:8443/fineract-provider/api/v1/clients/95/welcomekit" -Headers $headers
+$res5 | ConvertTo-Json -Depth 10