¶ Riverty Buy-Now-Pay-Later Payment für OXID eShop 7
Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version. Für ältere Versionen siehe das CHANGELOG.
Screenshots zeigen die englische Benutzeroberfläche, unabhängig von der Seitensprache.
¶ Überblick
Riverty Buy-Now-Pay-Later-Integration für OXID eShop 7: Rechnungskauf, Lastschrift, Ratenzahlung (Fixed Instalments) und Pay in 3 über Riverty's Hosted Checkout (Redirect-Flow, kein PCI-Scope im eigenen Shop). Für OXID-Shopbetreiber (CE/PE/EE) mit Riverty-Händlervertrag, die in DE, AT, CH, NL, BE, NO, SE, DK oder FI verkaufen.
Riverty Buy-Now-Pay-Later ist bei Kunden beliebt, aber die Integration ist komplex: Multi-Country-API-Keys, Order-Lifecycle-Tracking, Redirect-Flow, Capture/Void/Refund-Logik. Dieses Modul übernimmt die komplette Integration — Konfiguration und Bestellverwaltung erledigst du komplett über den OXID-Admin, ganz ohne eigenen Code.
Abbildung: Zahlartenauswahl im Checkout
¶ Features
| Feature | Beschreibung |
|---|---|
| Hosted Checkout | Sicherer Redirect-Zahlungsprozess über Riverty, kein PCI-Scope im eigenen Shop |
| Multi-Country | Eigenes API-Key-Paar (Test/Live) pro Land — DE, AT, CH, NL, BE, NO, SE, DK, FI |
| Zahlarten-Abgleich per Klick | Ein Button gleicht die Zahlarten mit deinem Riverty-Vertrag ab — kein manuelles Anlegen einzelner Zahlarten nötig |
| Order-Management | Capture, Teil-/Voll-Void, Teil-/Voll-Refund direkt im OXID-Admin |
| API-Logging | Jeder Riverty-API-Call wird protokolliert und im Admin durchsuchbar |
| Integration API | Externe Systeme (ERP/WMS) können Capture/Void/Refund per REST auslösen (optional, vom Entwickler eingerichtet) |
| Sandbox-Modus | Pro Land unabhängig testbar |
| Risiko-Datenanreicherung | Optional Bestandskundenhistorie für besseres Riverty-Scoring |
| Ratenzahlungs-Teaser | PAngV-§6a-konforme Repräsentativbeispiel-Anzeige im Checkout (opt-in) |
| Automatische Datenpflege | Cronjob räumt alte Logs und abgelaufene Transaktionen auf (Einrichtung durch den Entwickler) |
¶ Anforderungen
| Anforderung | Version | Hinweis |
|---|---|---|
| OXID eShop | 7.3+ | CE, PE oder EE |
| PHP | 8.3+ | |
| Riverty | Merchant-Account | Vertrag mit Riverty erforderlich |
| Lizenz | Kommerziell | CE/PE: eine Installation; EE: eine Installation inkl. aller Subshops |
Konfiguration — Pfad im Admin: Extensions > Modules > Riverty > Settings. Alles hier beschriebene machst du selbst im Admin — dein Entwickler wird nur für Installation, optionale Integration-API-Anbindung und Cron-Einrichtung gebraucht (siehe Für Entwickler).
¶ API-Einstellungen pro Land
Für jedes Land (DE, AT, CH, NL, BE, NO, SE, DK, FI) drei Einstellungen:
| Einstellung | Typ | Default | Bedeutung |
|---|---|---|---|
Test-API-Key (mmdRivertyApiKeyTest{CC}) |
Passwort | leer | Sandbox-API-Key für dieses Land |
Live-API-Key (mmdRivertyApiKeyLive{CC}) |
Passwort | leer | Live-API-Key für dieses Land |
Sandbox-Modus für dieses Land (mmdRivertySandbox{CC}) |
Bool | true | true = Test-Key aktiv, false = Live-Key aktiv |
Die API-Keys erhältst du von Riverty im Rahmen deines Händlervertrags.
Reihenfolge beim Umstellen auf Live wichtig: erst den Live-Key eintragen, DANN den Sandbox-Schalter auf false stellen. Andersherum bleibt das Land inaktiv, weil der zum Schalter passende Key noch leer ist.
Abbildung: API-Einstellungen pro Land
Abbildung: API-Keys pro Land testen
¶ Zahlarten abrufen (Pflichtschritt nach jeder Key-Änderung)
Nach dem Speichern eines API-Keys erscheinen die Riverty-Zahlarten NICHT automatisch im Checkout. Erst nach einem Klick auf "Fetch Payment Methods" werden die für dein Land freigeschalteten Zahlarten abgerufen und angelegt. Das gilt bei der Ersteinrichtung genauso wie bei jeder späteren Key-Änderung (z.B. Umstellung von Sandbox auf Live).
Abbildung: Zahlarten vom Riverty-Vertrag abgleichen ("Fetch Payment Methods")
Abbildung: Aktuell konfigurierte Riverty-Zahlarten
¶ Zahlungseinstellungen
| Einstellung | Typ | Default | Bedeutung |
|---|---|---|---|
Bestellung nach Capture als bezahlt markieren (mmdRivertyMarkPaidOnCapture) |
Bool | true | Setzt die Bestellung nach erfolgreicher Capture automatisch auf "bezahlt" |
Bestellordner nach Capture wechseln (mmdRivertyFolderAfterCapture) |
Auswahl | leer | Verschiebt die Bestellung nach Capture in einen anderen Ordner (z.B. "Fertig") |
Bestellordner nach vollständigem Storno wechseln (mmdRivertyFolderAfterVoid) |
Auswahl | leer | Verschiebt die Bestellung nach vollständigem Void in einen anderen Ordner |
Ratenzahlungs-Preisvorschau im Checkout anzeigen (mmdRivertyShowInstallmentTeaser) |
Bool | false | "ab X€/Monat"-Teaser mit PAngV-§6a-Repräsentativbeispiel im Checkout |
Abbildung: Zahlungseinstellungen
¶ Risiko-Datenanreicherung
| Einstellung | Typ | Default | Bedeutung |
|---|---|---|---|
Bestandskundendaten an Riverty übermitteln (mmdRivertyExistingCustomerData) |
Auswahl | Deaktiviert | Steuert, welche Bestandskundendaten Riverty für die Risikoprüfung erhält |
Optionen: Deaktiviert (nur IP-Adresse) · Nur Flag (zusätzlich ein "ist Bestandskunde"-Merkmal) · Vollständig, inkl. Bestellhistorie (zusätzlich Kundenseit-Datum sowie Anzahl und Betrag der Transaktionen der letzten 12 Monate).
Abbildung: Risiko-Datenanreicherung
¶ Debug-Modus
| Einstellung | Typ | Default |
|---|---|---|
Debug-Protokollierung aktivieren (mmdRivertyDebugLog) |
Bool | false |
Schreibt bei Aktivierung nach source/log/riverty.log. Das API-Log im Admin (siehe unten) läuft davon unabhängig immer.
Abbildung: Debug-Modus
¶ Automatische Datenpflege
| Einstellung | Typ | Default | Bedeutung |
|---|---|---|---|
API-Logs aufbewahren für (Tage) (mmdRivertyApiLogRetentionDays) |
Zahl | 90 | Löscht API-Log-Zeilen älter als N Tage |
Abgebrochene Zahlungsversuche aufbewahren für (Tage, 1-30) (mmdRivertyPendingTransactionRetentionDays) |
Zahl | 7 | Muss zwischen 1 und 30 liegen |
Diese Werte steuern, wie lange Daten aufbewahrt werden — der Cronjob, der sie umsetzt, wird von deinem Entwickler eingerichtet (siehe Für Entwickler).
Abbildung: Aufbewahrungsfristen für Logs und Transaktionen
¶ Integration API freischalten (optional)
Nur relevant, wenn ein externes System (ERP/WMS) Bestellungen automatisiert capturen/stornieren soll — dein Entwickler übernimmt dafür die technische Anbindung.
| Einstellung | Typ | Default | Bedeutung |
|---|---|---|---|
Externe Integration API aktivieren (mmdRivertyIntegrationApiEnabled) |
Bool | false | Schaltet den externen API-Endpunkt frei |
Shared Secret (mmdRivertyIntegrationApiSecret) |
Passwort | leer | Per Button generiert — wird nur einmalig angezeigt |
Abbildung: Externe Integration API aktivieren und Secret generieren
¶ Frontend-Ansicht je Zahlart
So erscheinen die einzelnen Zahlarten im Checkout deines Shops.
Beim Aufruf der Zahlartenauswahl fragt das Modul bei Riverty ab, welche Zahlarten für den aktuellen Warenkorbbetrag verfügbar sind. Liegt der Warenkorb z.B. unter dem Mindestbetrag für Ratenzahlung, wird diese Zahlart für den Kunden gar nicht erst angezeigt — das ist kein Konfigurationsfehler. Bei dieser Abfrage werden KEINE Kundendaten an Riverty übertragen, nur die Höhe des Warenkorbbetrags.
Abbildung: Lastschrift
Abbildung: Rechnungskauf
Abbildung: Ratenzahlung ohne Repräsentativbeispiel-Teaser
Abbildung: Ratenzahlung mit aktivierter Repräsentativbeispiel-Preisvorschau
Abbildung: Danke-Seite mit Riverty-Infobox
¶ Admin-Bestellverwaltung
Riverty-Tab in der Bestellansicht (Admin → Bestellungen → [Bestellung] → Riverty):
| Aktion | Beschreibung |
|---|---|
| Versenden + Capture | Erst Capture der Restmenge, dann Versanddatum setzen — Bestellung bleibt unversandt bei API-Fehler |
| Capture (Teilmenge) | Ausgewählte Positionen capturen |
| Void (Rest) | Restliche autorisierte Menge stornieren |
| Void (Teilmenge) | Ausgewählte Positionen stornieren |
| Refund (voll) | Alle capturten Positionen zurückerstatten |
| Refund (Teilmenge) | Ausgewählte Positionen zurückerstatten |
Aktions-Buttons erscheinen nur, wenn der Transaktionsstatus die jeweilige Aktion erlaubt: Capture/Void nur bei authorized/partially_captured, Refund nur bei captured/partially_captured/partially_refunded.
Abbildung: Riverty-Tab in der Bestellansicht
Abbildung: Capture/Void-Beispiel mit Teilmengen
¶ API-Logs
Jeder Riverty-API-Call wird unabhängig vom Debug-Modus protokolliert und ist hier durchsuchbar/filterbar — der erste Anlaufpunkt, wenn eine Zahlung nicht wie erwartet läuft.
Abbildung: API-Log-Interface im Admin
¶ FAQ
Unterstützt das Modul alle Riverty-Zahlarten?
Ja: Rechnungskauf, Lastschrift, Ratenzahlung (Fixed Instalments) und Pay in 3 (aktuell nur in den Niederlanden, gemäß Riverty-Vertragsstruktur).
Funktioniert das Modul mit allen OXID-Editionen?
Ja, Community Edition, Professional Edition und Enterprise Edition werden unterstützt.
Brauche ich für jedes Land einen eigenen Riverty-Vertrag?
Ja — das Modul selbst verwaltet aber beliebig viele Länder parallel, ohne Mehraufwand.
Kann ich das Modul erst im Sandbox-Modus testen?
Ja, der Sandbox-Modus ist pro Land unabhängig schaltbar — Live-Betrieb in einem Land, Test in einem anderen ist möglich.
Brauche ich einen Entwickler, um das Modul zu konfigurieren?
Nein. Installation und optionale Integration-API-/Cron-Einrichtung übernimmt ein Entwickler einmalig — die eigentliche Konfiguration (API-Keys, Zahlarten, Einstellungen) machst du danach selbst im Admin.
Warum sehen Kunden nicht immer alle konfigurierten Zahlarten im Checkout?
Riverty prüft bei jedem Aufruf der Zahlartenauswahl, welche Zahlarten für den aktuellen Warenkorbbetrag verfügbar sind — z.B. wird Ratenzahlung erst ab einem Mindestbetrag angezeigt. Das ist normales Verhalten, kein Fehler. An Riverty werden dabei nur der Warenkorbbetrag übermittelt, keine Kundendaten.
¶ Fehlerbehebung
| Symptom | Prüfung | Lösung |
|---|---|---|
| Land erscheint nicht im Checkout trotz Konfiguration | Passt der hinterlegte API-Key zum aktuellen Sandbox-Schalter (Test-Key bei Sandbox an, Live-Key bei Sandbox aus)? Wurden die Zahlarten schon per "Fetch Payment Methods" abgeglichen? | Fehlenden/falschen Key ergänzen, danach erneut auf "Fetch Payment Methods" klicken |
| Signatur-Fehler bei Rückkehr von Riverty | Stimmt der API-Key des zurückkommenden Landes mit dem bei Authorize verwendeten überein? | Sandbox/Live-Verwechslung für das jeweilige Land ausschließen |
| Zahlung nach Rückkehr abgelehnt, obwohl bei Riverty erfolgreich | API-Logs für den lookup-Request-Type prüfen (siehe API-Logs oben) |
Bei API-Fehler beim Status-Abgleich lehnt das Modul sicherheitshalber ab |
¶ Lizenz
Kommerzielle Lizenz. CE/PE-Lizenz: eine Installation. EE-Lizenz: eine Installation inklusive aller Subshops.
¶ Support
E-Mail: support@markus-michalski.net
¶ Hinweis zu Riverty
Dieses Modul ist eine unabhängige Integration und steht in keiner geschäftlichen oder vertraglichen Beziehung zu Riverty. Es wurde nicht von Riverty beauftragt, autorisiert oder geprüft. Bei Fragen oder Problemen wenden Sie sich ausschließlich an den Modul-Support (support@markus-michalski.net) — Riverty selbst übernimmt hierfür keinerlei Verantwortung oder Support. "Riverty" ist eine Marke der jeweiligen Rechteinhaberin.
¶ Changelog
Vollständige Versionshistorie im CHANGELOG.
¶ Installation
Private Composer-Repository zum Shop hinzufügen (composer.json des Shops):
{
"repositories": [
{
"type": "composer",
"url": "https://packeton.markus-michalski.net"
}
]
}
Die Zugangsdaten für das private Repository werden nach dem Lizenzkauf bereitgestellt, verwaltet über Packeton.
composer require mmd/oxid7-riverty
vendor/bin/oe-console oe:module:activate mmd_riverty
vendor/bin/oe-console oe:cache:clear
Bei der Aktivierung werden automatisch die Tabellen mmd_riverty_transactions, mmd_riverty_api_logs und mmd_riverty_idempotency_keys angelegt. Zahlarten selbst werden NICHT automatisch angelegt — das macht der Kunde anschließend selbst über "Fetch Payment Methods" (siehe Für Kunden → Konfiguration).
¶ Update
composer update mmd/oxid7-riverty
vendor/bin/oe-console oe:cache:clear
Nach Updates mit neuen Einstellungen (z.B. den Cleanup-Settings) das Modul reaktivieren oder
vendor/bin/oe-console oe:module:apply-configurationausführen — sonst wirft der naechste Cronjob-Lauf eine Exception ("module setting ... is not configured yet").
¶ REST-/Integration-API (optional)
Externer Endpunkt für ERP-/WMS-/Middleware-Systeme, um Capture/Void/Refund auszulösen, ohne den OXID-Admin zu nutzen. Das Freischalten und die Secret-Generierung selbst macht der Kunde im Admin (siehe Für Kunden → Konfiguration) — hier die technische Schnittstellen-Referenz für die Anbindung.
Endpunkt: POST index.php?cl=mmd_riverty_integration_api
Auth: Header X-Riverty-Integration-Secret gegen das im Admin konfigurierte Secret (timing-safe Vergleich).
Request-Body:
{
"type": "capture",
"orderNumber": "2026070001",
"mode": "partial",
"items": [{"sku": "ART-001", "quantity": 1}],
"idempotencyKey": "erp-job-48213"
}
type: capture, void oder refund (Aliase cancel/cancellation für void). orderId ODER orderNumber erforderlich. mode: full oder partial (Default: partial). idempotencyKey: optional, verhindert Doppel-Ausführung bei Retries.
Response-Codes:
| Code | Bedeutung |
|---|---|
| 200 | Erfolg |
| 400 | Ungültiges JSON oder Validierungsfehler |
| 401 | Secret fehlt oder falsch |
| 403 | Integration API deaktiviert |
| 409 | Idempotency-Key wird gerade verarbeitet |
| 422 | Idempotency-Key mit abweichendem Request-Body wiederverwendet |
| 503 | Secret nicht konfiguriert |
| 500 | Unerwarteter Fehler |
Void hat über die Integration API keine Teilmengen-Variante — nur vollständiges Void. Capture und Refund unterstützen
mode: "partial".
¶ Console Commands / Cronjob-Einrichtung
| Command | Beschreibung |
|---|---|
oe-console oe:riverty:cleanup |
Räumt abgelaufene API-Logs, verwaiste Idempotency-Keys und abgelaufene Pending-Transaktionen auf (Aufbewahrungsfristen werden vom Kunden im Admin konfiguriert, siehe Für Kunden → Konfiguration) |
Option --dry-run zeigt betroffene Zeilenzahlen, ohne zu löschen.
Empfohlener Cronjob:
0 3 * * * cd /var/www/html && vendor/bin/oe-console oe:riverty:cleanup >> /var/log/riverty-cleanup.log 2>&1
¶ Praxis-Beispiele
Beispiel 1 — Teil-Refund per Integration API:
curl -X POST "https://shop.example.com/index.php?cl=mmd_riverty_integration_api" \
-H "X-Riverty-Integration-Secret: <secret>" \
-H "Content-Type: application/json" \
-d '{
"type": "refund",
"orderNumber": "2026070001",
"mode": "partial",
"items": [{"sku": "ART-001", "quantity": 1}],
"captureNumber": "CAP-123",
"idempotencyKey": "erp-refund-9911"
}'
Beispiel 2 — Cronjob im Dry-Run testen, bevor er scharf geschaltet wird:
vendor/bin/oe-console oe:riverty:cleanup --dry-run
¶ Fehlerbehebung
| Symptom | Prüfung | Lösung |
|---|---|---|
| Cronjob bricht mit "setting not found" ab | Neue Settings nach Update in der DB vorhanden? | oe:module:apply-configuration ausführen oder Modul reaktivieren |
| Integration API liefert 503 | Ist ein Secret generiert? | Kunde erzeugt es über den "Generate Secret"-Button im Admin (wird nur einmalig angezeigt) |
| Integration API liefert dauerhaft 409 | Hängt eine Idempotency-Key-Reservierung? | mmd_riverty_idempotency_keys-Tabelle prüfen, betroffene Zeile ggf. löschen |
¶ Technische Details
Flow 1 — Checkout / Redirect:
Flow 2 — Order Management (Admin oder Integration API):
Modul-Struktur:
src/
├── Core/
├── Controller/
│ ├── Admin/
│ └── Api/
├── Api/
│ ├── Request/
│ └── Response/
├── Payment/
├── Console/
├── Exception/
├── Config/
├── Service/
│ └── IntegrationApi/
├── Repository/
├── Model/
│ └── IntegrationApi/
└── Extension/
├── Controller/
└── Model/
Chain Extending:
| Klasse | Erweitert | Warum |
|---|---|---|
OrderControllerExtension |
OrderController |
Greift vor finalizeOrder() ein, um bei Redirect-Zahlarten auf die Riverty-Autorisierung zu warten — OXID hat keinen nativen Hook dafür |
PaymentControllerExtension |
PaymentController |
Filtert die Zahlartenliste zur Laufzeit gegen die Riverty Available-Payment-Methods-API (Vertrag + Betragsgrenzen) |
ThankYouControllerExtension |
ThankYouController |
Zeigt die Riverty-Infobox auf der Danke-Seite (rein additiv) |
OrderOverviewExtension |
Admin\OrderOverview |
Hookt sendorder() für optionales Auto-Capture beim Versand |
ModuleConfigurationExtension |
Admin\ModuleConfiguration |
Stellt die AJAX-Actions für Secret-Generierung, Zahlarten-Fetch und API-Key-Test bereit — "Fetch Payment Methods" ruft denselben Available-Payment-Methods-Endpoint auf wie PaymentControllerExtension zur Checkout-Laufzeit, hier aber vertragsweit ohne Betragsfilter |
ExtendedPaymentGateway |
PaymentGateway |
Gibt bei bereits autorisierter Riverty-Zahlung true zurück, damit OXID die Order nicht faelschlich verwirft |
Alle Extension-Klassen deklarieren bewusst keinen Return-Type auf überschriebenen Methoden — PHP's Chain-Extending-Mechanismus verlangt exakte Signatur-Kompatibilität mit der jeweiligen OXID-Core-Klasse.