Support for Verification of Payee

lib/Fhp/Action/SendSEPATransfer.php

@@ -32,12 +32,12 @@ class SendSEPATransfer extends BaseAction
      *     to create this.
      * @return SendSEPATransfer A new action for executing this the given PAIN message.
      */
-    public static function create(SEPAAccount $account, string $painMessage): SendSEPATransfer
+    public static function create(SEPAAccount $account, string $painMessage): static
     {
         if (preg_match('/xmlns="(.*?)"/', $painMessage, $match) === false) {
             throw new \InvalidArgumentException('xmlns not found in the PAIN message');
         }
-        $result = new SendSEPATransfer();
+        $result = new static();
         $result->account = $account;
         $result->painMessage = $painMessage;
         $result->xmlSchema = $match[1];

lib/Fhp/Action/SendSEPATransferVoP.php

@@ -0,0 +1,151 @@
+<?php
+
+namespace Fhp\Action;
+
+use Fhp\Protocol\BPD;
+use Fhp\Protocol\Message;
+use Fhp\Protocol\UPD;
+use Fhp\Segment\HIRMS\Rueckmeldungscode;
+use Fhp\Segment\VPP\HIVPPSv1;
+use Fhp\Segment\VPP\HIVPPv1;
+use Fhp\Segment\VPP\HKVPAv1;
+use Fhp\Segment\VPP\HKVPPv1;
+use Fhp\UnsupportedException;
+
+/**
+ * Initiates an outgoing wire transfer in SEPA format (PAIN XML) with VoP.
+ * @see FinTS_3.0_Messages_Geschaeftsvorfaelle_VOP_1.01_2025_06_27_FV.pdf
+ */
+class SendSEPATransferVoP extends SendSEPATransfer
+{
+    protected $vopRequired = false;
+    protected $vopIsPending = false;
+    protected $vopNeedsConfirmation = false;
+
+    protected $vopConfirmed = false;
+
+    /**
+     * If set, the last response from the server regarding this action indicated that there are more results to be
+     * fetched using this pagination token. This is called "Aufsetzpunkt" in the specification.
+     * Pagination is used in VoP to poll for the result of the name check.
+     */
+    protected ?string $paginationToken = null;
+
+    public ?HKVPPv1 $hkvpp = null;
+    public ?HIVPPv1 $hivpp = null;
+
+    protected function createRequest(BPD $bpd, ?UPD $upd)
+    {
+        // Do we need to ask for the VoP result?
+        if ($this->vopIsPending) {
+            $this->hkvpp->pollingId = $this->hivpp->pollingId;
+            $this->hkvpp->aufsetzpunkt = $this->paginationToken;
+            return $this->hkvpp;
+        }
+
+        $requestSegment = parent::createRequest($bpd, $upd);
+        $requestSegments = [$requestSegment];
+
+        if ($this->vopNeedsConfirmation && $this->vopConfirmed) {
+
+            $hkvpa = HKVPAv1::createEmpty();
+            $hkvpa->vopId = $this->hivpp->vopId;
+            return [$hkvpa, $requestSegment];
+        }
+
+        // Check if VoP is supported by the bank
+
+        /** @var HIVPPSv1 $hivpps */
+        if ($hivpps = $bpd->getLatestSupportedParameters('HIVPPS')) {
+            // Check if the request segment is in the list of VoP-supported segments
+            if (in_array($requestSegment->getName(), $hivpps->parameter->vopPflichtigerZahlungsverkehrsauftrag)) {
+
+                $this->vopRequired = true;
+
+                // Send VoP confirmation
+                if ($this->needsConfirmation() && $this->hivpp?->vopId) {
+                    $hkvpp = HKVPAv1::createEmpty();
+                    $hkvpp->vopId = $this->hivpp->vopId;
+                    $requestSegments = [$hkvpp, $requestSegment];
+                } else {
+                    // Ask for VoP
+                    $this->hkvpp = $hkvpp = HKVPPv1::createEmpty();
+
+                    // For now just pretend we support all formats
+                    $supportedFormats = explode(';', $hivpps->parameter->unterstuetztePaymentStatusReportDatenformate);
+                    $hkvpp->unterstuetztePaymentStatusReports->paymentStatusReportDescriptor = $supportedFormats;
+
+                    // VoP before the transfer request
+                    $requestSegments = [$hkvpp, $requestSegment];
+                }
+            }
+        }
+
+        return $requestSegments;
+    }
+
+    public function processResponse(Message $response)
+    {
+        $this->vopIsPending = false;
+        $this->hivpp = $response->findSegment(HIVPPv1::class);
+
+        // The Bank does not want a separate HKVPA ("VoP Ausführungsauftrag").
+        if ($response->findRueckmeldung(Rueckmeldungscode::VOP_AUSFUEHRUNGSAUFTRAG_NICHT_BENOETIGT) !== null) {
+            $this->vopRequired = false;
+            $this->vopNeedsConfirmation = false;
+            parent::processResponse($response);
+            return;
+        }
+
+        if ($response->findRueckmeldung(Rueckmeldungscode::VOP_NAMENSABGLEICH_IST_NOCH_IN_BEARBEITUNG) !== null) {
+            $this->vopIsPending = true;
+            $this->vopNeedsConfirmation = false;
+            return;
+        }
+
+        if (($pagination = $response->findRueckmeldung(Rueckmeldungscode::PAGINATION)) !== null) {
+            $this->paginationToken = $pagination->rueckmeldungsparameter[0];
+        }
+
+        if (
+            $response->findRueckmeldung(Rueckmeldungscode::VOP_KEINE_NAMENSABWEICHUNG) !== null
+            // The bank has discarded the request, and wants us to resend it with a HKVPA
+            // This can happen even if the name matches.
+            || $response->findRueckmeldung(Rueckmeldungscode::FREIGABE_KANN_NICHT_ERTEILT_WERDEN) !== null
+            // The user needs to check the result of the name check.
+            // This can be sent by the bank even if the name matches.
+            || $response->findRueckmeldung(Rueckmeldungscode::VOP_ERGEBNIS_NAMENSABGLEICH_PRUEFEN) !== null
+        ) {
+            $this->vopNeedsConfirmation = true;
+            // Is the result already available?
+            if (!$this->hivpp->vopId) {
+                $this->vopIsPending = true;
+            }
+            return;
+        }
+
+        // The bank accepted the request as is.
+        if ($response->findRueckmeldung(Rueckmeldungscode::ENTGEGENGENOMMEN) !== null || $response->findRueckmeldung(Rueckmeldungscode::AUSGEFUEHRT) !== null) {
+            $this->vopRequired = false;
+            parent::processResponse($response);
+            return;
+        }
+
+        throw new UnsupportedException('Unexpected state in VoP process');
+    }
+
+    public function needsTime()
+    {
+        return $this->vopIsPending;
+    }
+
+    public function needsConfirmation()
+    {
+        return $this->vopNeedsConfirmation;
+    }
+
+    public function setConfirmed()
+    {
+        $this->vopConfirmed = true;
+    }
+}

lib/Fhp/BaseAction.php

@@ -144,6 +144,16 @@ public function getTanRequest(): ?TanRequest
         return $this->tanRequest;
     }
 
+    public function needsConfirmation()
+    {
+        return false;
+    }
+
+    public function needsTime()
+    {
+        return false;
+    }
+
     /**
      * Throws an exception unless this action has been successfully executed, i.e. in the following cases:
      *  - the action has not been {@link FinTs::execute()}-d at all or the {@link FinTs::execute()} call for it threw an

lib/Fhp/FinTs.php

@@ -320,8 +320,8 @@ public function execute(BaseAction $action)
         $message = MessageBuilder::create()->add($requestSegments); // This fills in the segment numbers.
         if (!($this->getSelectedTanMode() instanceof NoPsd2TanMode)) {
             if (($needTanForSegment = $action->getNeedTanForSegment()) !== null) {
-                $message->add(HKTANFactory::createProzessvariante2Step1(
-                    $this->requireTanMode(), $this->selectedTanMedium, $needTanForSegment));
+                $hktan = HKTANFactory::createProzessvariante2Step1($this->requireTanMode(), $this->selectedTanMedium, $needTanForSegment);
+                $message->add($hktan);
             }
         }
         $request = $this->buildMessage($message, $this->getSelectedTanMode());
@@ -354,7 +354,11 @@ public function execute(BaseAction $action)
         }
 
         // If no TAN is needed, process the response normally, and maybe keep going for more pages.
-        $this->processActionResponse($action, $response->filterByReferenceSegments($action->getRequestSegmentNumbers()));
+        $requestSegmentsNumbers = $action->getRequestSegmentNumbers();
+        if (isset($hktan)) {
+            $requestSegmentsNumbers[] = $hktan->getSegmentNumber();
+        }
+        $this->processActionResponse($action, $response->filterByReferenceSegments($requestSegmentsNumbers));
         if ($action instanceof PaginateableAction && $action->hasMorePages()) {
             $this->execute($action);
         }

lib/Fhp/Segment/HIRMS/Rueckmeldungscode.php

@@ -79,6 +79,16 @@ public static function isError(int $code): bool
      */
     public const PAGINATION = 3040;
 
+    public const VOP_KEINE_NAMENSABWEICHUNG = 25;
+
+    public const VOP_ERGEBNIS_NAMENSABGLEICH_PRUEFEN = 3090;
+
+    public const VOP_AUSFUEHRUNGSAUFTRAG_NICHT_BENOETIGT = 3091;
+
+    public const VOP_NAMENSABGLEICH_IST_NOCH_IN_BEARBEITUNG = 3093;
+
+    public const VOP_NAMENSABGLEICH_IST_KOMPLETT = 3094;
+
     /**
      * Zugelassene Ein- und Zwei-Schritt-Verfahren für den Benutzer (+ Rückmeldungsparameter).
      * The parameters reference the VerfahrensparameterZweiSchrittVerfahren.sicherheitsfunktion values (900..997) from
@@ -99,6 +109,14 @@ public static function isError(int $code): bool
      */
     public const ZUGANG_VORLAEUFIG_GESPERRT = 3938;
 
+    /**
+     * Der eingereichte HKTAN ist entwertet und der Auftrag (nach
+     * vollständiger Übermittlung des Prüfergebnisses) soll erneut mit einem neuen
+     * HKTAN in Verbindung mit einem HKVPA eingereicht werden, sofern der
+     * Kunde die Ausführung weiterhin wünscht.
+     */
+    public const FREIGABE_KANN_NICHT_ERTEILT_WERDEN = 3945;
+
     /**
      * Starke Kundenauthentifizierung noch ausstehend.
      * Indicates that the decoupled authentication is still outstanding.

lib/Fhp/Segment/VPP/ErgebnisVopPruefungEinzeltransaktion.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Fhp\Segment\VPP;
+
+use Fhp\Segment\BaseDeg;
+
+class ErgebnisVopPruefungEinzeltransaktion extends BaseDeg
+{
+    public string $ibanEmpfaenger;
+
+    public ?string $ibanZusatzinformationen = null;
+
+    public ?string $abweichenderEmpfaengername = null;
+
+    public ?string $anderesIdentifikationmerkmal = null;
+
+    /** Allowed values: RVMC, RCVC, RVNM, RVNA, PDNG */
+    public string $vopPruefergebnis;
+
+    public ?string $grundRVNA = null;
+}

lib/Fhp/Segment/VPP/HIVPPSv1.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Fhp\Segment\VPP;
+
+use Fhp\Segment\BaseGeschaeftsvorfallparameter;
+
+/**
+ * Segment: Namensabgleich Prüfauftrag Parameter
+ *
+ * @see FinTS_3.0_Messages_Geschaeftsvorfaelle_VOP_1.01_2025_06_27_FV.pdf
+ * Section: C.10.7.1 c)
+ */
+class HIVPPSv1 extends BaseGeschaeftsvorfallparameter
+{
+    public ParameterNamensabgleichPruefauftrag $parameter;
+}

lib/Fhp/Segment/VPP/HIVPPv1.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Fhp\Segment\VPP;
+
+use Fhp\Segment\BaseSegment;
+use Fhp\Segment\Common\Tsp;
+use Fhp\Syntax\Bin;
+
+/**
+ * Segment: Namensabgleich Prüfergebnis
+ *
+ * @see FinTS_3.0_Messages_Geschaeftsvorfaelle_VOP_1.01_2025_06_27_FV.pdf
+ * Section: C.10.7.1 b)
+ */
+class HIVPPv1 extends BaseSegment
+{
+    public ?Bin $vopId = null;
+
+    public ?Tsp $vopIdGueltigBis = null;
+
+    public ?Bin $pollingId = null;
+
+    public ?string $paymentStatusReportDescriptor = null;
+
+    public ?Bin $paymentStatusReport = null;
+
+    public ?ErgebnisVopPruefungEinzeltransaktion $ergebnisVopPruefungEinzeltransaktion = null;
+
+    public ?string $aufklaerungstextAutorisierungTrotzAbweichung = null;
+
+    // This value is in seconds
+    public ?int $wartezeitVorNaechsterAbfrage = null;
+}

lib/Fhp/Segment/VPP/HKVPAv1.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Fhp\Segment\VPP;
+
+use Fhp\Segment\BaseSegment;
+use Fhp\Syntax\Bin;
+
+/**
+ * Segment: Namensabgleich Ausführungsauftrag
+ *
+ * @see FinTS_3.0_Messages_Geschaeftsvorfaelle_VOP_1.01_2025_06_27_FV.pdf
+ * Section: C.10.7.1.2 a)
+ */
+class HKVPAv1 extends BaseSegment
+{
+    public Bin $vopId;
+}

lib/Fhp/Segment/VPP/HKVPPv1.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Fhp\Segment\VPP;
+
+use Fhp\Segment\BaseSegment;
+use Fhp\Syntax\Bin;
+
+/**
+ * Segment: Namensabgleich Prüfauftrag
+ *
+ * @see FinTS_3.0_Messages_Geschaeftsvorfaelle_VOP_1.01_2025_06_27_FV.pdf
+ * Section: C.10.7.1 a)
+ */
+class HKVPPv1 extends BaseSegment
+{
+    public UnterstuetztePaymentStatusReports $unterstuetztePaymentStatusReports;
+
+    public ?Bin $pollingId = null;
+
+    /** Only allowed if {@link ParameterNamensabgleichPruefauftrag::$eingabeAnzahlEintraegeErlaubt} says so. */
+    public ?int $maximaleAnzahlEintraege = null;
+
+    /** For pagination. Max length: 35 */
+    public ?string $aufsetzpunkt = null;
+
+    public static function createEmpty(): static
+    {
+        $hkvpp = parent::createEmpty();
+        $hkvpp->unterstuetztePaymentStatusReports = new UnterstuetztePaymentStatusReports();
+        return $hkvpp;
+    }
+}

lib/Fhp/Segment/VPP/ParameterNamensabgleichPruefauftrag.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Fhp\Segment\VPP;
+
+use Fhp\Segment\BaseDeg;
+
+class ParameterNamensabgleichPruefauftrag extends BaseDeg
+{
+    public int $maximaleAnzahlCreditTransferTransactionInformationOptIn;
+
+    public bool $aufklaerungstextStrukturiert;
+
+    /** Allowed values: V, S */
+    public string $artDerLieferungPaymentStatusReport;
+
+    public bool $sammelzahlungenMitEinemAuftragErlaubt;
+
+    public bool $eingabeAnzahlEintraegeErlaubt;
+
+    public string $unterstuetztePaymentStatusReportDatenformate;
+
+    /** @var string[] @Max(999999) Max length each: 6 */
+    public array $vopPflichtigerZahlungsverkehrsauftrag;
+}