nemiah#477 Add support for awaiting and then confirming VOP

This initial version only supports confirming VOP requests (not canceling them). And for now we only extract the top-level status code from the VOP response, ignoring all the per-transfer details and additional information (like actual payee name) that the bank delivers.

This is based on the draft implementation of @ampaze in nemiah#499.

Author: Philipp91

lib/Fhp/BaseAction.php

@@ -4,7 +4,9 @@
 
 namespace Fhp;
 
+use Fhp\Model\PollingInfo;
 use Fhp\Model\TanRequest;
+use Fhp\Model\VopConfirmationRequest;
 use Fhp\Protocol\ActionIncompleteException;
 use Fhp\Protocol\BPD;
 use Fhp\Protocol\Message;
@@ -48,6 +50,12 @@ abstract class BaseAction implements \Serializable
     /** If set, the last response from the server regarding this action asked for a TAN from the user. */
     protected ?TanRequest $tanRequest = null;
 
+    /** If set, this action is currently waiting for a long-running operation on the server to complete. */
+    protected ?PollingInfo $pollingInfo = null;
+
+    /** If set, this action needs the user's confirmation to be completed. */
+    protected ?VopConfirmationRequest $vopConfirmationRequest = null;
+
     protected bool $isDone = false;
 
     /**
@@ -72,15 +80,15 @@ public function serialize(): string
     }
 
     /**
-     * An action can only be serialized *after* it has been executed in case it needs a TAN, i.e. when the result is not
-     * present yet.
+     * An action can only be serialized *after* it has been executed and *if* it wasn't completed yet (e.g. because it
+     * still requires a TAN or VOP confirmation).
      * If a sub-class overrides this, it should call the parent function and include it in its result.
      *
      * @return array The serialized action, e.g. for storage in a database. This will not contain sensitive user data.
      */
     public function __serialize(): array
     {
-        if (!$this->needsTan()) {
+        if (!$this->needsTan() && !$this->needsPollingWait() && !$this->needsVopConfirmation()) {
             throw new \RuntimeException('Cannot serialize this action, because it is not waiting for a TAN.');
         }
         return [
@@ -139,6 +147,26 @@ public function getTanRequest(): ?TanRequest
         return $this->tanRequest;
     }
 
+    public function needsPollingWait(): bool
+    {
+        return !$this->isDone() && $this->pollingInfo !== null;
+    }
+
+    public function getPollingInfo(): ?PollingInfo
+    {
+        return $this->pollingInfo;
+    }
+
+    public function needsVopConfirmation(): bool
+    {
+        return !$this->isDone() && $this->vopConfirmationRequest !== null;
+    }
+
+    public function getVopConfirmationRequest(): ?VopConfirmationRequest
+    {
+        return $this->vopConfirmationRequest;
+    }
+
     /**
      * 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
@@ -248,4 +276,16 @@ final public function setTanRequest(?TanRequest $tanRequest): void
     {
         $this->tanRequest = $tanRequest;
     }
+
+    /** To be called only by the FinTs instance that executes this action. */
+    final public function setPollingInfo(?PollingInfo $pollingInfo): void
+    {
+        $this->pollingInfo = $pollingInfo;
+    }
+
+    /** To be called only by the FinTs instance that executes this action. */
+    final public function setVopConfirmationRequest(?VopConfirmationRequest $vopConfirmationRequest): void
+    {
+        $this->vopConfirmationRequest = $vopConfirmationRequest;
+    }
 }

lib/Fhp/FinTs.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Fhp\Model;
+
+/**
+ * Provides information that the client application should use to poll for the completion of a long-running operation on
+ * the server.
+ */
+interface PollingInfo
+{
+    /**
+     * @return ?int The number of seconds (measured from the time when the client received this {@link PollingInfo})
+     *     after which the client is allowed to contact the server again regarding this action. If this returns null,
+     *     there is no restriction.
+     */
+    public function getNextAttemptInSeconds(): ?int;
+
+    /**
+     * @return ?string An HTML-formatted text (either in the bank's language or in English!) that the application may
+     *     display to the user to inform them (on a very high level) about why they have to wait.
+     */
+    public function getInformationForUser(): ?string;
+}

lib/Fhp/Model/PollingInfo.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Fhp\Model;
+
+/**
+ * Provides information (about the payee) that the client application should present to the user and then ask for their
+ * confirmation that the transfer (to this payee) should be executed.
+ */
+interface VopConfirmationRequest
+{
+    /** An HTML-formatted text that (if present) the application must show to the user when asking for confirmation. */
+    public function getInformationForUser(): ?string;
+
+    /** If this returns a non-null value, the confirmation request is only valid up to that time. */
+    public function getExpiration(): ?\DateTime;
+
+    /** The main outcome of the payee verification. See {@link VopVerificationResult} for possible values. */
+    public function getVerificationResult(): ?string;
+
+    /**
+     * If {@link getVerificationResult()} returns {@link VopVerificationResult::NotApplicable}, then this function MAY
+     * return an additional explanation (in the user's language or in English), but it may also return null.
+     */
+    public function getVerificationNotApplicableReason(): ?string;
+}

lib/Fhp/Model/VopConfirmationRequest.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Fhp\Model;
+
+use Fhp\Syntax\Bin;
+
+/** Application code should not interact directly with this type, see {@link VopConfirmationRequest instead}. */
+class VopConfirmationRequestImpl implements VopConfirmationRequest
+{
+    private Bin $vopId;
+    private ?\DateTime $expiration;
+    private ?string $informationForUser;
+    private ?string $verificationResult;
+    private ?string $verificationNotApplicableReason;
+
+    public function __construct(
+        Bin $vopId,
+        ?\DateTime $expiration,
+        ?string $informationForUser,
+        ?string $verificationResult,
+        ?string $verificationNotApplicableReason,
+    ) {
+        $this->vopId = $vopId;
+        $this->expiration = $expiration;
+        $this->informationForUser = $informationForUser;
+        $this->verificationResult = $verificationResult;
+        $this->verificationNotApplicableReason = $verificationNotApplicableReason;
+    }
+
+    public function getVopId(): Bin
+    {
+        return $this->vopId;
+    }
+
+    public function getExpiration(): ?\DateTime
+    {
+        return $this->expiration;
+    }
+
+    public function getInformationForUser(): ?string
+    {
+        return $this->informationForUser;
+    }
+
+    public function getVerificationResult(): ?string
+    {
+        return $this->verificationResult;
+    }
+
+    public function getVerificationNotApplicableReason(): ?string
+    {
+        return $this->verificationNotApplicableReason;
+    }
+}

lib/Fhp/Model/VopConfirmationRequestImpl.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Fhp\Model;
+
+use Fhp\Syntax\Bin;
+
+/**
+ * Application code should not interact directly with this type, see {@link PollingInfo instead}.
+ *
+ * When we send a request to the bank that requires a Verification of Payee, this means that the bank server has to
+ * contact another bank's server and compare payee names. Especially for larger requests (e.g. bulk transfers), this can
+ * take some time. During this time, the server asks the client to poll regularly in order to find out when the process
+ * is done. This class contains the state that the client needs to do this polling.
+ */
+class VopPollingInfo implements PollingInfo
+{
+    // Both of these are effectively opaque tokens that only the server understands. Our job is to relay them back to
+    // the server when polling. And for some reason there's two of them.
+    private string $aufsetzpunkt;
+    private ?Bin $pollingId;
+
+    private ?int $nextAttemptInSeconds = null;
+
+    public function __construct(string $aufsetzpunkt, ?Bin $pollingId, ?int $nextAttemptInSeconds)
+    {
+        $this->aufsetzpunkt = $aufsetzpunkt;
+        $this->pollingId = $pollingId;
+        $this->nextAttemptInSeconds = $nextAttemptInSeconds;
+    }
+
+    public function getAufsetzpunkt(): string
+    {
+        return $this->aufsetzpunkt;
+    }
+
+    public function getPollingId(): ?Bin
+    {
+        return $this->pollingId;
+    }
+
+    public function getNextAttemptInSeconds(): ?int
+    {
+        return $this->nextAttemptInSeconds;
+    }
+
+    public function getInformationForUser(): string
+    {
+        return 'The bank is verifying payee information...';
+    }
+}

lib/Fhp/Model/VopPollingInfo.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Fhp\Model;
+
+use Fhp\Protocol\UnexpectedResponseException;
+
+/**
+ * Possible outcomes of the Verification of Payee check that the bank did on a transfer we want to execute.
+ * TODO Once we have PHP8.1, turn this into an enum. That's why we use UpperCamelCase below (Symfony style for enums).
+ * @see FinTS_3.0_Messages_Geschaeftsvorfaelle_VOP_1.01_2025_06_27_FV.pdf (chapter D under "VOP-Prüfergebnis")
+ * @see https://febelfin.be/media/pages/publicaties/2023/febelfin-standaarden-voor-online-bankieren/971728b297-1746523070/febelfin-standard-payment-status-report-xml-2025-v1.0-en_final.pdf
+ */
+class VopVerificationResult
+{
+    /** The verification completed and successfully matched the payee information. */
+    public const CompletedFullMatch = 'CompletedFullMatch';
+    /** The verification completed and only partially matched the payee information. */
+    public const CompletedCloseMatch = 'CompletedCloseMatch';
+    /** The verification completed but could not match the payee information. */
+    public const CompletedNoMatch = 'CompletedNoMatch';
+    /** The verification completed but not all included transfers were successfully matched. */
+    public const CompletedPartialMatch = 'CompletedPartialMatch';
+    /**
+     * The verification was attempted but could not be completed. More information MAY be available from
+     * {@link VopConfirmationRequest::getVerificationNotApplicableReason()}.
+     */
+    public const NotApplicable = 'NotApplicable';
+
+    public function __construct()
+    {
+        // Disallow instantiation, because we'll turn this into an enum.
+        throw new \AssertionError('There should be no instances of VopVerificationResult');
+    }
+
+    /**
+     * @param string $codeFromBank The verification status code received from the bank.
+     * @return ?string One of the constants defined above, or null if the code could not be recognized.
+     */
+    public static function parse(string $codeFromBank): ?string
+    {
+        return match ($codeFromBank) {
+            'RCVC' => self::CompletedFullMatch,
+            'RVMC' => self::CompletedCloseMatch,
+            'RVNM' => self::CompletedNoMatch,
+            'RVCM' => self::CompletedPartialMatch,
+            'RVNA' => self::NotApplicable,
+            default => throw new UnexpectedResponseException("Unexpected VOP result code: $codeFromBank"),
+        };
+    }
+}

lib/Fhp/Model/VopVerificationResult.php

@@ -10,6 +10,7 @@
 use Fhp\Segment\HIPINS\HIPINSv1;
 use Fhp\Segment\SegmentInterface;
 use Fhp\Segment\TAN\HITANS;
+use Fhp\Segment\VPP\HIVPPSv1;
 
 /**
  * Segmentfolge: Bankparameterdaten (Version 3)
@@ -152,6 +153,28 @@ public function tanRequiredForRequest(array $requestSegments): ?string
         return null;
     }
 
+    /**
+     * @param SegmentInterface[] $requestSegments The segments that shall be sent to the bank.
+     * @return string|null Identifier of the (first) segment that requires Verification of Payee according to HIPINS, or
+     *     null if none of the segments require verification.
+     */
+    public function vopRequiredForRequest(array $requestSegments): ?string
+    {
+        /** @var HIVPPSv1 $hivpps */
+        $hivpps = $this->getLatestSupportedParameters('HIVPPS');
+        $vopRequiredTypes = $hivpps?->parameter?->vopPflichtigerZahlungsverkehrsauftrag;
+        if ($vopRequiredTypes === null) {
+            return null;
+        }
+
+        foreach ($requestSegments as $segment) {
+            if (in_array($segment->getName(), $vopRequiredTypes)) {
+                return $segment->getName();
+            }
+        }
+        return null;
+    }
+
     /**
      * @return bool Whether the BPD indicates that the bank supports PSD2.
      */

lib/Fhp/Protocol/BPD.php

@@ -190,12 +190,17 @@ public function filterByReferenceSegments(array $referenceNumbers): Message
 
     /**
      * @param int $code The response code to search for.
+     * @param ?int $requestSegmentNumber If set, only consider Rueckmeldungen that pertain to this request segment.
      * @return Rueckmeldung|null The corresponding Rueckmeldung instance, or null if not found.
      */
-    public function findRueckmeldung(int $code): ?Rueckmeldung
+    public function findRueckmeldung(int $code, ?int $requestSegmentNumber = null): ?Rueckmeldung
     {
         foreach ($this->plainSegments as $segment) {
-            if ($segment instanceof RueckmeldungContainer) {
+            if (
+                $segment instanceof RueckmeldungContainer && (
+                    $requestSegmentNumber === null || $segment->segmentkopf->bezugselement === $requestSegmentNumber
+                )
+            ) {
                 $rueckmeldung = $segment->findRueckmeldung($code);
                 if ($rueckmeldung !== null) {
                     return $rueckmeldung;