103 lines
4.3 KiB
PHP
103 lines
4.3 KiB
PHP
<?php
|
|
declare(strict_types=1);
|
|
|
|
namespace Payments;
|
|
|
|
/**
|
|
* Vertrag fuer Zahlungsanbieter mit Weiterleitung (PayPal v2, spaeter Amazon Pay,
|
|
* Mollie, Klarna Payments ...).
|
|
*
|
|
* Lebenszyklus einer Zahlung:
|
|
* 1. Cashdesk legt die Shop-Bestellung an (Zahlstatus offen).
|
|
* 2. start() -> Zahlung beim Anbieter anlegen, Kunde per 302 weiterleiten.
|
|
* 3. onReturn() -> Kunde kommt zurueck: Zahlung abschliessen, Bestellung bezahlt setzen.
|
|
* onCancel() -> Kunde hat abgebrochen: Bestellung stornieren, Warenkorb bleibt.
|
|
* 4. onWebhook() -> Anbieter meldet serverseitig (unabhaengig vom Kunden).
|
|
* 5. reconcile() -> Cron: haengende Vorgaenge beim Anbieter nachfragen.
|
|
*
|
|
* Alles, was fuer alle Anbieter gleich ist (Mail erst nach Zahlung, Warenkorb erst
|
|
* nach Zahlung, Ereignisprotokoll, Betragsabgleich), lebt in AbstractProvider.
|
|
*/
|
|
interface ProviderInterface
|
|
{
|
|
/** Technischer Name = payment_methods.module = Konfigurationsgruppe, z.B. 'paypal_v2'. */
|
|
public function module(): string;
|
|
|
|
/** Anzeigename fuers Backend und Protokoll. */
|
|
public function label(): string;
|
|
|
|
/** true: die Bestellung ist erst nach Rueckkehr vom Anbieter bezahlt (Mail/Warenkorb warten). */
|
|
public function paysAfterRedirect(): bool;
|
|
|
|
/**
|
|
* Zahlung anlegen und Weiterleitungs-URL liefern.
|
|
*
|
|
* @param int $orderId Shop-Bestellung (orders.id)
|
|
* @param float $amount zu zahlender Bruttobetrag (nach Gutschein)
|
|
* @return string URL, zu der der Kunde geschickt wird
|
|
* @throws \RuntimeException wenn der Anbieter nicht erreichbar ist oder ablehnt
|
|
*/
|
|
public function start(int $orderId, float $amount): string;
|
|
|
|
/**
|
|
* Rueckkehr des Kunden vom Anbieter.
|
|
* @param array<string,mixed> $query $_GET der Rueckkehr-URL
|
|
*/
|
|
public function onReturn(array $query): Result;
|
|
|
|
/** @param array<string,mixed> $query */
|
|
public function onCancel(array $query): Result;
|
|
|
|
/**
|
|
* Server-zu-Server-Nachricht des Anbieters.
|
|
* @param array<string,string> $headers Request-Header, Schluessel kleingeschrieben
|
|
* @return int HTTP-Status, den der Endpunkt zurueckgeben soll (2xx = angenommen)
|
|
*/
|
|
public function onWebhook(array $headers, string $rawBody): int;
|
|
|
|
/**
|
|
* Haengende Vorgaenge nachziehen (Cron). Liefert eine kurze Zusammenfassung je Vorgang.
|
|
* @return list<string>
|
|
*/
|
|
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.
|
|
* @return array<string,string>
|
|
*/
|
|
public function secretFields(): array;
|
|
}
|