English Version

Zurück zur Übersicht

Riverty Payments: Shop API

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Das Plugin ist dual-mode: Storefront und Sylius Shop API nutzen denselben Zahlungsweg. Dafür bringt es keine eigenen Endpunkte mit.

Das Plugin fügt der Shop API keine Endpunkte hinzu. Es gibt keine eigenen Shop-Routen und keine API-Platform-Ressourcen. Stattdessen nimmt es an den Payment Requests teil, die Sylius ohnehin für Storefront und Shop API nutzt. Welche Endpunkte du aufrufst, um eine Zahlung zu starten und ihren Payment Request abzufragen, steht in der Sylius-Dokumentation und nicht hier.

Wie eine Riverty-Zahlung über die API läuft

graph TD
    A["Client startet die Zahlung über Sylius Payment Request"] --> B["Command Bus: Autorisierung"]
    B --> C["Riverty Plugin ruft Riverty auf"]
    C --> D{"Antwort?"}
    D -->|Angenommen| E["Zahlung autorisiert"]
    D -->|Weiterleitung nötig| F["redirect_url in den Antwortdaten des Payment Requests"]
    D -->|Abgelehnt| G["Payment Request und Zahlung schlagen fehl"]
    F --> H["Client öffnet den Hosted Checkout"]
    H --> I["Statusabfrage oder Abgleich setzt die Zahlung"]

1. Der Client löst über die Sylius-Payment-Request-Schnittstelle die Autorisierung der Zahlung aus. Das Plugin ist dafür im Payment-Request-Command-Bus von Sylius für das Gateway riverty registriert und unterstützt die Aktionen capture, authorize und status.
2. Das Plugin fragt Riverty und führt den Payment Request und die Zahlung gemeinsam weiter.
3. Braucht der Kunde den Hosted Checkout, steht die Adresse in den Antwortdaten des Payment Requests unter redirect_url. Ein reiner JSON-Client bekommt keinen HTTP-Redirect, er liest die Adresse und öffnet sie selbst, zum Beispiel in einem neuen Tab oder einer WebView.
4. Kehrt der Kunde zurück, setzt die Statusabfrage die Zahlung. Kehrt er nicht zurück, holt mmd:riverty:reconcile das nach.

Der Transport für Payment Requests muss synchron sein (sync://), sonst läuft die Autorisierung erst, wenn ein Worker die Queue abarbeitet, und der Kunde bekommt keine redirect_url. Siehe Installation.

Fehler

Das Plugin definiert kein eigenes Fehlerformat. Ein Fehlschlag erscheint als Fehlerzustand des Payment Requests und der Zahlung in Sylius, die Meldung steht in den Antwortdaten des Payment Requests und als Fehler der Zahlung. Das Format ist das von Sylius.

Grenze: Identifikationsnummer in den Nordics

Headless-Shops können die Identifikationsnummer nicht übergeben. Das Feld gehört zum Storefront-Checkout. Eine Bestellung nach Norwegen, Schweden, Dänemark oder Finnland, die über die API ohne Nummer aufgegeben wird, geht nicht an Riverty: Die Zahlung schlägt mit der klaren Meldung fehl, dass eine Identifikationsnummer fehlt (sichtbar am Payment Request und als Fehler der Zahlung). Ein Headless-Shop muss die Nummer selbst erfragen und kann sie diesem Plugin noch nicht übergeben.

Bestellungen in die Nordics brauchen außerdem die Währung, die Riverty dort erwartet (NOK, SEK, DKK, in Finnland EUR). Für Länder außerhalb der Nordics gibt es diese Grenze nicht.

Admin-Aktionen

Capture, Void und Refund sowie die Buttons der Einstellungen sind Admin-Aktionen mit CSRF-Token und kein Teil einer API. Wie du sie nutzt, steht unter Bestellverwaltung.