From fb58bede78f38083a93fb8a8cd46e409f3ef08c6 Mon Sep 17 00:00:00 2001
From: Tim Rasche <rasche@mamisch.de>
Date: Thu, 11 Dec 2025 10:09:29 +0100
Subject: [PATCH] Add singleBookingRequested option to SendSEPATransfer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add support for the 'einzelbuchungGewuenscht' parameter in SEPA batch
transfers (Sammelüberweisungen). This allows callers to request that
each transaction appears as a separate entry on the bank statement
instead of being grouped as a single batch booking.

Changes:
- Add singleBookingRequested property and setSingleBookingRequested()
  setter to SendSEPATransfer action
- Set einzelbuchungGewuenscht on HKCCM/HKCME segments when the bank
  supports it (einzelbuchungErlaubt = true in BPD)
- Add missing getParameter() method with return type to HICMESv1
- Add return type to getParameter() in HICCMSv1

Usage:
  $action = SendSEPATransfer::create($account, $painXml)
      ->setSingleBookingRequested(true);
  $fints->execute($action);
---
 lib/Fhp/Action/SendSEPATransfer.php | 29 +++++++++++++++++++++++++++--
 lib/Fhp/Segment/CCM/HICCMSv1.php    |  2 +-
 lib/Fhp/Segment/CME/HICMESv1.php    |  5 +++++
 3 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/lib/Fhp/Action/SendSEPATransfer.php b/lib/Fhp/Action/SendSEPATransfer.php
index 6c119d37..a7ce104e 100644
--- a/lib/Fhp/Action/SendSEPATransfer.php
+++ b/lib/Fhp/Action/SendSEPATransfer.php
@@ -26,6 +26,8 @@ class SendSEPATransfer extends BaseAction
     private $painMessage;
     /** @var string */
     private $xmlSchema;
+    /** @var bool */
+    private $singleBookingRequested = false;
 
     // There are no result fields. This action is simply marked as done to indicate that the transfer was executed.
 
@@ -47,6 +49,19 @@ public static function create(SEPAAccount $account, string $painMessage): SendSE
         return $result;
     }
 
+    /**
+     * Request individual bookings instead of a batch booking on the bank statement.
+     * Only applicable for batch transfers (Sammelüberweisung).
+     *
+     * @param bool $singleBookingRequested If true, each transaction appears separately on the statement.
+     * @return $this
+     */
+    public function setSingleBookingRequested(bool $singleBookingRequested): self
+    {
+        $this->singleBookingRequested = $singleBookingRequested;
+        return $this;
+    }
+
     /**
      * @deprecated Beginning from PHP7.4 __unserialize is used for new generated strings, then this method is only used for previously generated strings - remove after May 2023
      */
@@ -59,7 +74,7 @@ public function __serialize(): array
     {
         return [
             parent::__serialize(),
-            $this->account, $this->painMessage, $this->xmlSchema,
+            $this->account, $this->painMessage, $this->xmlSchema, $this->singleBookingRequested,
         ];
     }
 
@@ -78,7 +93,7 @@ public function __unserialize(array $serialized): void
     {
         list(
             $parentSerialized,
-            $this->account, $this->painMessage, $this->xmlSchema,
+            $this->account, $this->painMessage, $this->xmlSchema, $this->singleBookingRequested,
         ) = $serialized;
 
         is_array($parentSerialized) ?
@@ -144,6 +159,16 @@ protected function createRequest(BPD $bpd, ?UPD $upd)
         $segment->kontoverbindungInternational = Kti::fromAccount($this->account);
         $segment->sepaDescriptor = $this->xmlSchema;
         $segment->sepaPainMessage = new Bin($this->painMessage);
+
+        // For batch transfers: set einzelbuchungGewuenscht if bank allows it
+        if ($numberOfTransactions > 1) {
+            $paramSegmentId = $hasReqdExDates ? 'HICMES' : 'HICCMS';
+            $paramSegment = $bpd->getLatestSupportedParameters($paramSegmentId);
+            if ($paramSegment !== null && $paramSegment->getParameter()->einzelbuchungErlaubt) {
+                $segment->einzelbuchungGewuenscht = $this->singleBookingRequested;
+            }
+        }
+
         return $segment;
     }
 
diff --git a/lib/Fhp/Segment/CCM/HICCMSv1.php b/lib/Fhp/Segment/CCM/HICCMSv1.php
index f3d23be9..3b2c460f 100644
--- a/lib/Fhp/Segment/CCM/HICCMSv1.php
+++ b/lib/Fhp/Segment/CCM/HICCMSv1.php
@@ -14,7 +14,7 @@ class HICCMSv1 extends BaseGeschaeftsvorfallparameter
 {
     public ParameterSEPASammelueberweisungV1 $parameter;
 
-    public function getParameter()
+    public function getParameter(): ParameterSEPASammelueberweisungV1
     {
         return $this->parameter;
     }
diff --git a/lib/Fhp/Segment/CME/HICMESv1.php b/lib/Fhp/Segment/CME/HICMESv1.php
index 833d18b4..582afd0c 100644
--- a/lib/Fhp/Segment/CME/HICMESv1.php
+++ b/lib/Fhp/Segment/CME/HICMESv1.php
@@ -13,4 +13,9 @@
 class HICMESv1 extends BaseGeschaeftsvorfallparameter
 {
     public ParameterTerminierteSEPASammelueberweisungEinreichenV1 $parameter;
+
+    public function getParameter(): ParameterTerminierteSEPASammelueberweisungEinreichenV1
+    {
+        return $this->parameter;
+    }
 }