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

@@ -139,6 +139,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/VPP/HIVPPv1.php

@@ -14,6 +14,15 @@
  */
 class HIVPPv1 extends BaseSegment
 {
+    public const VOP_RESULT_CODES = [
+        'RCVC' => 'ReceivedVerificationCompleted',
+        'RVNA' => 'ReceivedVerificationCompletedNotApplicable',
+        'RVNM' => 'ReceivedVerificationCompletedNoMatch',
+        'RVMC' => 'ReceivedVerificationCompletedMatchClosely',
+        'RVNC' => 'ReceivedVerificationNotCompleted',
+        'RVCM' => 'ReceivedVerificationCompletedWithMismatches'
+    ];
+
     public ?Bin $vopId = null;
 
     public ?Tsp $vopIdGueltigBis = null;
@@ -30,4 +39,14 @@ class HIVPPv1 extends BaseSegment
 
     // This value is in seconds
     public ?int $wartezeitVorNaechsterAbfrage = null;
+
+    public function getVopResultCode(): ?string
+    {
+        if ($this->paymentStatusReport) {
+            $report = simplexml_load_string($this->paymentStatusReport->getData());
+            return $report->CstmrPmtStsRpt->OrgnlGrpInfAndSts->GrpSts;
+        } else {
+            return $this->ergebnisVopPruefungEinzeltransaktion?->vopPruefergebnis;
+        }
+    }
 }