feat(payments): Express-Kauf aus dem Warenkorb (PayPal v2): Start ohne Bestellung, Adresse von PayPal, Kasse vorbelegt, Capture ohne zweiten Besuch

core/payments/ProviderInterface.php

@@ -61,6 +61,38 @@ interface ProviderInterface
      */
     public function reconcile(bool $dryRun = true): array;
 
+    // ------------------------------------------------------------ Express
+    // "Direkt bezahlen" aus dem Warenkorb: der Kunde geht OHNE Adresse zum Anbieter,
+    // der liefert Adresse + E-Mail, die Kasse ist damit vorbelegt, ein Klick auf
+    // "zahlungspflichtig bestellen" zieht das Geld ein -- kein zweiter Besuch beim Anbieter.
+
+    /** Bietet der Anbieter den Express-Weg an (und ist er eingeschaltet)? */
+    public function supportsExpress(): bool;
+
+    /**
+     * Express-Vorgang fuer den aktuellen Warenkorb anlegen (noch keine Bestellung!).
+     * @param  float $amount  Warenwert brutto ohne Versand (Land noch unbekannt)
+     * @return string         URL zum Anbieter
+     */
+    public function startExpress(float $amount): string;
+
+    /**
+     * Rueckkehr vom Anbieter im Express-Weg: Adresse und E-Mail des Kunden abholen.
+     * @param  array<string,mixed> $query  $_GET der Rueckkehr-URL
+     * @return array<string,mixed>|null    Kundendaten fuer die Kasse (Schluessel: reference,
+     *         email, firstname, surname, company, street, house_number, zip_code, city,
+     *         country_iso, approve_url) oder null, wenn der Vorgang nicht zugeordnet werden kann
+     */
+    public function onExpressReturn(array $query): ?array;
+
+    /**
+     * Express abschliessen, nachdem die Bestellung angelegt ist: Betrag beim Anbieter auf
+     * den Endbetrag (inkl. Versand) setzen und einziehen.
+     * @return string  '' = bezahlt; sonst eine URL, zu der der Kunde noch einmal muss
+     *                 (Anbieter verlangt erneute Freigabe, z.B. nach Betragsaenderung)
+     */
+    public function finishExpress(int $orderId, float $amount, string $reference): string;
+
     /**
      * Felder fuer den Zahlart-Editor im Backend, die NICHT in `configuration` liegen,
      * sondern verschluesselt (Secrets). name => Beschriftung.