MX-362: Implement online person enrollment KYC for the Mifos Self Service Plugin

Author: IOhacker

src/main/java/org/apache/fineract/kyc/api/KycVerificationApiResource.java

@@ -12,6 +12,7 @@
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.HeaderParam;
+import jakarta.ws.rs.NotFoundException;
 import jakarta.ws.rs.POST;
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.PathParam;
@@ -85,4 +86,18 @@ public ResponseEntity<List<KycVerification>> listByClient(
         }
         return ResponseEntity.ok(verifications);
     }
+    
+    @GET
+    @Path("/clients/{clientId}/verifications/{id}")
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(summary = "Get full KYC verification details by ID")
+    public ResponseEntity<KycVerification> getVerificationById(
+            @PathParam("id") @Parameter(description = "Verification ID") final Long id) {
+
+        // Full detail endpoint — returns the complete nested tree
+        final KycVerification verification = kycVerificationService.findByIdWithDetails(id)
+                .orElseThrow(() -> new NotFoundException("KYC verification not found with id: " + id));
+
+        return ResponseEntity.ok(verification);
+    }
 }

src/main/java/org/apache/fineract/kyc/data/KycVerificationSummaryData.java

@@ -0,0 +1,65 @@
+/**
+ * Copyright since 2026 Mifos Initiative
+ *
+ * <p>This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy
+ * of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+package org.apache.fineract.kyc.data;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import java.time.OffsetDateTime;
+
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class KycVerificationSummaryData {
+
+    private Long id;
+    private Long clientId;
+    private String sessionId;
+    private String workflowId;
+    private Integer workflowVersion;
+    private String webhookType;
+    private String kycStatus;
+    private Long kycTimestamp;
+    private String decisionStatus;
+    private OffsetDateTime decisionCreatedAt;
+    private OffsetDateTime createdOnUtc;
+
+    public KycVerificationSummaryData() {}
+
+    public KycVerificationSummaryData(final Long id,
+                                      final Long clientId,
+                                      final String sessionId,
+                                      final String workflowId,
+                                      final Integer workflowVersion,
+                                      final String webhookType,
+                                      final String kycStatus,
+                                      final Long kycTimestamp,
+                                      final String decisionStatus,
+                                      final OffsetDateTime decisionCreatedAt,
+                                      final OffsetDateTime createdOnUtc) {
+        this.id = id;
+        this.clientId = clientId;
+        this.sessionId = sessionId;
+        this.workflowId = workflowId;
+        this.workflowVersion = workflowVersion;
+        this.webhookType = webhookType;
+        this.kycStatus = kycStatus;
+        this.kycTimestamp = kycTimestamp;
+        this.decisionStatus = decisionStatus;
+        this.decisionCreatedAt = decisionCreatedAt;
+        this.createdOnUtc = createdOnUtc;
+    }
+
+    // Getters
+    public Long getId() { return id; }
+    public Long getClientId() { return clientId; }
+    public String getSessionId() { return sessionId; }
+    public String getWorkflowId() { return workflowId; }
+    public Integer getWorkflowVersion() { return workflowVersion; }
+    public String getWebhookType() { return webhookType; }
+    public String getKycStatus() { return kycStatus; }
+    public Long getKycTimestamp() { return kycTimestamp; }
+    public String getDecisionStatus() { return decisionStatus; }
+    public OffsetDateTime getDecisionCreatedAt() { return decisionCreatedAt; }
+    public OffsetDateTime getCreatedOnUtc() { return createdOnUtc; }
+}

src/main/java/org/apache/fineract/kyc/domain/KycAmlScreening.java

@@ -72,7 +72,6 @@ public class KycAmlScreening {
     @Column(name = "last_modified_on_utc", nullable = false)
     private OffsetDateTime lastModifiedOnUtc;
 
-    @JsonIgnore
     @OneToMany(mappedBy = "amlScreening", cascade = CascadeType.ALL,
                fetch = FetchType.LAZY, orphanRemoval = true)
     private List<KycAmlHit> hits = new ArrayList<>();

src/main/java/org/apache/fineract/kyc/domain/KycDecision.java

@@ -60,22 +60,18 @@ public class KycDecision {
     @Column(name = "last_modified_on_utc", nullable = false)
     private OffsetDateTime lastModifiedOnUtc;
 
-    @JsonIgnore
     @OneToMany(mappedBy = "kycDecision", cascade = CascadeType.ALL,
                fetch = FetchType.LAZY, orphanRemoval = true)
     private List<KycDecisionFeature> features = new ArrayList<>();
 
-    @JsonIgnore
     @OneToMany(mappedBy = "kycDecision", cascade = CascadeType.ALL,
                fetch = FetchType.LAZY, orphanRemoval = true)
     private List<KycFaceMatch> faceMatches = new ArrayList<>();
 
-    @JsonIgnore
     @OneToMany(mappedBy = "kycDecision", cascade = CascadeType.ALL,
                fetch = FetchType.LAZY, orphanRemoval = true)
     private List<KycIdVerification> idVerifications = new ArrayList<>();
 
-    @JsonIgnore
     @OneToMany(mappedBy = "kycDecision", cascade = CascadeType.ALL,
                fetch = FetchType.LAZY, orphanRemoval = true)
     private List<KycAmlScreening> amlScreenings = new ArrayList<>();

src/main/java/org/apache/fineract/kyc/domain/KycVerification.java

@@ -13,6 +13,20 @@
 @Table(name = "m_client_kyc_verification")
 public class KycVerification {
 
+    /**
+     * @return the createdOnUtc
+     */
+    public OffsetDateTime getCreatedOnUtc() {
+        return createdOnUtc;
+    }
+
+    /**
+     * @param createdOnUtc the createdOnUtc to set
+     */
+    public void setCreatedOnUtc(OffsetDateTime createdOnUtc) {
+        this.createdOnUtc = createdOnUtc;
+    }
+
     @Id
     @GeneratedValue(strategy = GenerationType.IDENTITY)
     private Long id;
@@ -86,7 +100,7 @@ public static KycVerification create(final Long clientId,
         v.createdBy = createdBy;
         v.lastModifiedBy = createdBy;
         final OffsetDateTime now = OffsetDateTime.now();
-        v.createdOnUtc = now;
+        v.setCreatedOnUtc(now);
         v.lastModifiedOnUtc = now;
         return v;
     }

src/main/java/org/apache/fineract/kyc/service/KycVerificationService.java

@@ -9,6 +9,7 @@
 
 import java.util.List;
 import java.util.Optional;
+import org.apache.fineract.kyc.data.KycVerificationSummaryData;
 import org.apache.fineract.kyc.data.KycWebhookPayload;
 import org.apache.fineract.kyc.domain.KycVerification;
 
@@ -30,4 +31,8 @@ public interface KycVerificationService {
     List<KycVerification> findByClientId(Long clientId);
 
     List<KycVerification> findByClientIdAndStatus(Long clientId, Optional<String> status);
+    
+    List<KycVerificationSummaryData> findSummaryByClientId(Long clientId);
+    
+    List<KycVerificationSummaryData> findSummaryByClientIdAndStatus(Long clientId, Optional<String> status);
 }

src/main/java/org/apache/fineract/kyc/service/KycVerificationServiceImpl.java

@@ -16,6 +16,7 @@
 import java.time.format.DateTimeFormatter;
 import java.util.List;
 import java.util.Optional;
+import org.apache.fineract.kyc.data.KycVerificationSummaryData;
 import org.apache.fineract.kyc.data.KycWebhookPayload;
 import org.apache.fineract.kyc.data.KycWebhookPayload.AmlScreening;
 import org.apache.fineract.kyc.data.KycWebhookPayload.Decision;
@@ -245,4 +246,38 @@ private String serializeToJson(final Object obj) {
             return obj.toString();
         }
     }
+    
+    @Override
+    @Transactional(readOnly = true)
+    public List<KycVerificationSummaryData> findSummaryByClientId(final Long clientId) {
+        return kycVerificationRepository.findByClientIdOrderByCreatedOnUtcDesc(clientId)
+                .stream()
+                .map(this::toSummaryData)
+                .toList();
+    }
+
+    @Override
+    @Transactional(readOnly = true)
+    public List<KycVerificationSummaryData> findSummaryByClientIdAndStatus(final Long clientId, final Optional<String> status) {
+        return kycVerificationRepository.findByClientIdAndKycStatus(clientId, status)
+                .stream()
+                .map(this::toSummaryData)
+                .toList();
+    }
+
+    private KycVerificationSummaryData toSummaryData(final KycVerification v) {
+        return new KycVerificationSummaryData(
+                v.getId(),
+                v.getClientId(),
+                v.getSessionId(),
+                v.getWorkflowId(),
+                v.getWorkflowVersion(),
+                v.getWebhookType(),
+                v.getKycStatus(),
+                v.getKycTimestamp(),
+                v.getDecision() != null ? v.getDecision().getDecisionStatus() : null,
+                v.getDecision() != null ? v.getDecision().getDecisionCreatedAt() : null,
+                v.getCreatedOnUtc()
+        );
+    }
 }