English Version

Zurück zur Übersicht

Riverty Payments: Technische Details

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

Ablauf einer Zahlung

graph TD
    A["Storefront Twig Hook"] --> D["Payment Request Command Bus"]
    B["Shop API Request"] --> D
    D --> E["Command Provider des Plugins"]
    E --> F["Handler: Autorisierung oder Status"]
    F --> G["Riverty Client"]
    G --> H["Riverty API"]
    F --> I["Payment Request und Payment State Machine"]
    I --> J["HTTP Response Provider nur im Storefront"]
    J --> K["Weiterleitung zu Riverty oder zur Bestellung"]

1. Storefront und Shop API lösen beide einen Payment Request aus, den Sylius über seinen Command Bus verarbeitet.
2. Der Command Provider des Plugins (Gateway riverty) wählt den Command für Autorisierung oder Status.
3. Die Handler fragen über den Riverty Client die Riverty-API und führen die State Machine des Payment Requests und die der Zahlung gemeinsam weiter. Der Core verknüpft die beiden nicht, das Plugin übernimmt das.
4. Nur der Storefront nutzt den HTTP Response Provider: Er leitet zum Hosted Checkout oder zurück zur Bestellung. Ein Headless-Client liest redirect_url aus den Antwortdaten.

Capture, Void und Refund

Die Admin-Aktionen laufen über POST-Routen mit CSRF-Token pro Operation (capture, void, refund, jeweils für die ganze Bestellung oder für gewählte Positionen), dazu create-methods und check-contract für die Einstellungen. Die Buchführung über erfasste, stornierte und erstattete Positionen liegt an der Transaktion.

Datenmodell

erDiagram
    SETTINGS ||--o{ CREDENTIAL : "hat"
    SETTINGS {
        string channel_code
        bool show_installment_teaser
        bool capture_on_shipment
        int expiry_warning_days
        datetime last_expiry_digest_at
        string existing_customer_data_mode
    }
    CREDENTIAL {
        string country_code
        bool sandbox
        string encrypted_test_key
        string encrypted_live_key
    }
    TRANSACTION {
        string order_reference
        string status
        int captured_amount
        int voided_amount
        int refunded_amount
        datetime expiry_notified_at
    }
    PAYMENT ||--o| TRANSACTION : "gehoert zu"
    API_CALL {
        datetime created_at
        string request_type
        string order_reference
    }

Beträge liegen als ganze Zahlen in der kleinsten Einheit, dazu laufende Summen für erfasst, storniert und erstattet. Die Positionen stehen als JSON an der Transaktion. Der Status ist ein Enum. Das Ablaufdatum ist der Rohwert von Riverty, die 30-Tage-Grenze wird getrennt aus der Erstellzeit berechnet.

Migrationen

Plugin-Struktur

src/
  Api/             Riverty-Client, Anfragen und Antworten
  ApiLog/          Recorder, Sanitizer, Purger
  Availability/    Abfrage der verfügbaren Zahlarten
  Command/         mmd:riverty:setup, mmd:riverty:reconcile
  Controller/Admin Transaktions- und Einstellungsaktionen
  Entity/          Einstellungen, Zugangsdaten, Transaktion, API-Aufruf
  EventListener/   Capture beim Versand, Sperren der Sylius-Buttons
  Expiry/          30-Tage-Überwachung und Digest
  Form/            Einstellungen, Zugangsdaten, Gateway, Checkout-Feld
  Mapping/         Aufbau der Anfrage an Riverty
  Migrations/
  Payment/         Autorisierung, Status, Operationen
  PaymentRequest/  Anbindung an Sylius Payment Requests
  Provisioning/    Zahlarten anlegen, Vertrag prüfen
  RiskData/        Bestellhistorie des Kunden für Riverty
  Security/        Verschlüsselung
  Twig/            Funktionen für Admin und Storefront
config/            grids, routes, twig_hooks, services
templates/         admin und shop
translations/      Deutsch und Englisch

Sicherheit

• API-Keys und Identifikationsnummern werden mit einem aus APP_SECRET abgeleiteten Schlüssel verschlüsselt (OpenSSL).
• Der API-Log wird über eine eigene Datenbankverbindung am ORM vorbei geschrieben und maskiert personenbezogene Daten.
• Alle Admin-Aktionen laufen als POST mit CSRF-Token.

Tests

Die Prüfungen laufen im Docker-Stack des Repositories:

make phpunit
make phpstan
make ecs
make behat

Behat hat drei Suites: checkout, settings und order. Riverty antwortet dabei aus einem Skript, nichts verlässt den Rechner und es braucht keinen API-Key.