feat: add merchant settlement and reconciliation

Author: AliEmre007

backend/src/main/java/com/payledger/platform/ledger/application/LedgerAccountService.java

@@ -1,12 +1,14 @@
 package com.payledger.platform.ledger.application;
 
 import com.payledger.platform.ledger.domain.LedgerAccount;
+import com.payledger.platform.ledger.domain.LedgerAccountType;
 import com.payledger.platform.ledger.infrastructure.LedgerAccountRepository;
 import com.payledger.platform.shared.error.ResourceNotFoundException;
 import com.payledger.platform.wallet.domain.Wallet;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import java.util.Locale;
 import java.util.UUID;
 
 @Service
@@ -68,4 +70,20 @@ public LedgerAccount getForMerchantPayable(
                                 + merchantId
                 ));
     }
+
+    @Transactional
+    public LedgerAccount getOrCreateSettlementClearing(String currency) {
+        String normalizedCurrency = currency.trim().toUpperCase(Locale.ROOT);
+        String accountCode = "SETTLEMENT_CLEARING_" + normalizedCurrency;
+
+        return ledgerAccountRepository
+                .findByAccountCode(accountCode)
+                .orElseGet(() -> ledgerAccountRepository.saveAndFlush(
+                        LedgerAccount.createPlatformAccount(
+                                accountCode,
+                                LedgerAccountType.ASSET,
+                                normalizedCurrency
+                        )
+                ));
+    }
 }

backend/src/main/java/com/payledger/platform/ledger/infrastructure/LedgerAccountRepository.java

@@ -14,6 +14,8 @@ public interface LedgerAccountRepository extends JpaRepository<LedgerAccount, UU
 
     Optional<LedgerAccount> findByWalletId(UUID walletId);
 
+    Optional<LedgerAccount> findByAccountCode(String accountCode);
+
     Optional<LedgerAccount> findByMerchantIdAndCurrency(
             UUID merchantId,
             String currency

backend/src/main/java/com/payledger/platform/operations/api/OperationsSettlementController.java

@@ -0,0 +1,81 @@
+package com.payledger.platform.operations.api;
+
+import com.payledger.platform.operations.application.CurrentOperationActorService;
+import com.payledger.platform.operations.application.OperationActor;
+import com.payledger.platform.settlement.api.CreateSettlementBatchRequest;
+import com.payledger.platform.settlement.api.ReconcileSettlementRequest;
+import com.payledger.platform.settlement.api.ReconciliationCaseResponse;
+import com.payledger.platform.settlement.api.SettlementBatchResponse;
+import com.payledger.platform.settlement.application.CreateSettlementBatchCommand;
+import com.payledger.platform.settlement.application.ReconcileSettlementCommand;
+import com.payledger.platform.settlement.application.ReconciliationCaseDetails;
+import com.payledger.platform.settlement.application.SettlementBatchDetails;
+import com.payledger.platform.settlement.application.SettlementService;
+import jakarta.validation.Valid;
+import org.springframework.http.HttpStatus;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.ResponseStatus;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.UUID;
+
+@RestController
+@RequestMapping("/api/v1/operations/settlements")
+@PreAuthorize("hasRole('OPERATIONS')")
+public class OperationsSettlementController {
+
+    private final SettlementService settlementService;
+    private final CurrentOperationActorService currentActorService;
+
+    public OperationsSettlementController(
+            SettlementService settlementService,
+            CurrentOperationActorService currentActorService
+    ) {
+        this.settlementService = settlementService;
+        this.currentActorService = currentActorService;
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public SettlementBatchResponse createBatch(
+            @RequestHeader("Idempotency-Key") String idempotencyKey,
+            @Valid @RequestBody CreateSettlementBatchRequest request
+    ) {
+        OperationActor actor = currentActorService.getCurrentActor();
+        SettlementBatchDetails details = settlementService.createBatch(
+                new CreateSettlementBatchCommand(
+                        request.merchantId(),
+                        request.currency(),
+                        idempotencyKey,
+                        actor.externalSubject(),
+                        request.reason()
+                )
+        );
+
+        return SettlementBatchResponse.from(details);
+    }
+
+    @PostMapping("/{settlementBatchId}/reconcile")
+    public ReconciliationCaseResponse reconcile(
+            @PathVariable UUID settlementBatchId,
+            @Valid @RequestBody ReconcileSettlementRequest request
+    ) {
+        OperationActor actor = currentActorService.getCurrentActor();
+        ReconciliationCaseDetails details = settlementService.reconcile(
+                new ReconcileSettlementCommand(
+                        settlementBatchId,
+                        request.providerReference(),
+                        request.actualAmountMinor(),
+                        request.actualCurrency(),
+                        actor.externalSubject()
+                )
+        );
+
+        return ReconciliationCaseResponse.from(details);
+    }
+}

backend/src/main/java/com/payledger/platform/payment/infrastructure/PaymentIntentRepository.java

@@ -1,12 +1,14 @@
 package com.payledger.platform.payment.infrastructure;
 
 import com.payledger.platform.payment.domain.PaymentIntent;
+import com.payledger.platform.payment.domain.PaymentIntentStatus;
 import jakarta.persistence.LockModeType;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.Lock;
 import org.springframework.data.jpa.repository.Query;
 import org.springframework.data.repository.query.Param;
 
+import java.util.List;
 import java.util.Optional;
 import java.util.UUID;
 
@@ -27,4 +29,25 @@ Optional<PaymentIntent> findByCustomerIdAndIdempotencyKey(
     Optional<PaymentIntent> findByIdForUpdate(
             @Param("paymentIntentId") UUID paymentIntentId
     );
+
+    @Lock(LockModeType.PESSIMISTIC_WRITE)
+    @Query("""
+            SELECT intent
+            FROM PaymentIntent intent
+            WHERE intent.merchantId = :merchantId
+              AND intent.currency = :currency
+              AND intent.status = :status
+              AND intent.captureJournalEntryId IS NOT NULL
+              AND NOT EXISTS (
+                    SELECT line.id
+                    FROM SettlementLine line
+                    WHERE line.paymentIntentId = intent.id
+              )
+            ORDER BY intent.capturedAt ASC, intent.id ASC
+            """)
+    List<PaymentIntent> findUnsettledCapturedForUpdate(
+            @Param("merchantId") UUID merchantId,
+            @Param("currency") String currency,
+            @Param("status") PaymentIntentStatus status
+    );
 }

backend/src/main/java/com/payledger/platform/settlement/api/CreateSettlementBatchRequest.java

@@ -0,0 +1,14 @@
+package com.payledger.platform.settlement.api;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+
+import java.util.UUID;
+
+public record CreateSettlementBatchRequest(
+        @NotNull UUID merchantId,
+        @NotBlank @Size(min = 3, max = 3) String currency,
+        @NotBlank @Size(max = 500) String reason
+) {
+}

backend/src/main/java/com/payledger/platform/settlement/api/ReconcileSettlementRequest.java

@@ -0,0 +1,12 @@
+package com.payledger.platform.settlement.api;
+
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+
+public record ReconcileSettlementRequest(
+        @NotBlank @Size(max = 120) String providerReference,
+        @Min(0) long actualAmountMinor,
+        @NotBlank @Size(min = 3, max = 3) String actualCurrency
+) {
+}

backend/src/main/java/com/payledger/platform/settlement/api/ReconciliationCaseResponse.java

@@ -0,0 +1,30 @@
+package com.payledger.platform.settlement.api;
+
+import com.payledger.platform.settlement.application.ReconciliationCaseDetails;
+
+import java.util.UUID;
+
+public record ReconciliationCaseResponse(
+        UUID id,
+        String status,
+        long expectedAmountMinor,
+        long actualAmountMinor,
+        String expectedCurrency,
+        String actualCurrency,
+        String discrepancyReason
+) {
+
+    public static ReconciliationCaseResponse from(
+            ReconciliationCaseDetails details
+    ) {
+        return new ReconciliationCaseResponse(
+                details.id(),
+                details.status(),
+                details.expectedAmountMinor(),
+                details.actualAmountMinor(),
+                details.expectedCurrency(),
+                details.actualCurrency(),
+                details.discrepancyReason()
+        );
+    }
+}

backend/src/main/java/com/payledger/platform/settlement/api/SettlementBatchResponse.java

@@ -0,0 +1,28 @@
+package com.payledger.platform.settlement.api;
+
+import com.payledger.platform.settlement.application.SettlementBatchDetails;
+
+import java.util.UUID;
+
+public record SettlementBatchResponse(
+        UUID id,
+        UUID merchantId,
+        String currency,
+        String status,
+        long totalAmountMinor,
+        UUID journalEntryId
+) {
+
+    public static SettlementBatchResponse from(
+            SettlementBatchDetails details
+    ) {
+        return new SettlementBatchResponse(
+                details.id(),
+                details.merchantId(),
+                details.currency(),
+                details.status(),
+                details.totalAmountMinor(),
+                details.journalEntryId()
+        );
+    }
+}

backend/src/main/java/com/payledger/platform/settlement/application/CreateSettlementBatchCommand.java

@@ -0,0 +1,12 @@
+package com.payledger.platform.settlement.application;
+
+import java.util.UUID;
+
+public record CreateSettlementBatchCommand(
+        UUID merchantId,
+        String currency,
+        String idempotencyKey,
+        String actorExternalSubject,
+        String reason
+) {
+}

backend/src/main/java/com/payledger/platform/settlement/application/ReconcileSettlementCommand.java

@@ -0,0 +1,12 @@
+package com.payledger.platform.settlement.application;
+
+import java.util.UUID;
+
+public record ReconcileSettlementCommand(
+        UUID settlementBatchId,
+        String providerReference,
+        long actualAmountMinor,
+        String actualCurrency,
+        String actorExternalSubject
+) {
+}