# VR Payment Zahlungs-Plugin für Shopware 6

## Documentation

# 1Übersicht

Das VR Payment Zahlungs-Plugin integriert moderne Zahlungsabwicklung in Shopware 6 und bietet Funktionen wie iFrame-basierte Zahlungen, Rückerstattungen, Erfassungen und PCI-Konformität. Es unterstützt die nahtlose Integration mit dem VR Payment Portal zur Verwaltung von Transaktionen und Zahlungsmethoden.

Wichtig: Bitte beachten Sie, dass nur Major- (z.B. 6.x.0.0) und Minor-Updates (z.B. 6.0.x.0) innerhalb von 2 Wochen nach der Veröffentlichung auf Kompatibilität getestet werden.

# 2Anforderungen

- Shopware Version: 6.5.x, 6.6.x oder 6.7.x (see Kompatibilitätstabelle).

- PHP: Mindestversion, wie von Ihrer Shopware-Installation erforderlich (z.B. 7.4+).

- VR Payment Konto: Holen Sie sich die `Space ID`, `User ID` und den `API Key` vom VR Payment Portal (siehe Portal-Startanleitung).

# 3Kompatibilität

Shopware-Version | Plugin-Version | PHP-Version | Unterstützt bis
6.7.x | 7.x.x | PHP 8.2 und 8.3 | Laufend
6.6.x | 6.x.x | PHP 8.2 und 8.3 | Dezember 2025
6.5.x – Veraltet | 5.x.x | PHP 8.2 und 8.3 | Oktober 2024

# 4Installation

## 4.1Via Marketplace

1. Melden Sie sich im Backend Ihres Shopware-Shops an..

2. Navigieren Sie zu Einstellungen → System → Plugins.

3. Klicken Sie auf den Menü-Caret und wählen Sie den Link Installieren des Plugins, um es zu installieren.

4. Aktivieren Sie das VR Payment Zahlungs-Plugin im Plugin-Manager.

## 4.2Via Composer (Recommended)

1. Navigieren Sie zu Ihrem Shopware-Stammverzeichnis.

2. Führen Sie Folgendes aus:

       composer require vrpayment/shopware-6
       php bin/console plugin:refresh
       php bin/console plugin:install --activate --clearCache VRPayment

## 4.3Via Composer (Recommended)

1. Laden Sie die neueste Version herunter.

2. Entpacken Sie die ZIP-Datei nach `custom/plugins/`

3. Führen Sie Folgendes aus:

       php bin/console plugin:refresh
       php bin/console plugin:install --activate --clearCache VRPayment

## 4.4VRPayment erscheint nicht in den Einstellungen

Folgender Befehl muss ausgeführt werden

    bin/build-administration.sh

# 5Portal-Startanleitung

Gehen Sie zu VR Payment und erstellen Sie ein Konto, falls Sie noch keines haben.

Tip | Wählen Sie das passende Abo aus – es sollte E-Commerce-Transaktionen unterstützen.

## 5.1Erstellen Sie den API-Schlüssel:

1. Nach der Aktivierung Ihres Kontos navigieren Sie zu Account → Applikationsbenutzer

2. Klicken Sie auf Applikationsbenutzer erstellen

3. Geben Sie einen Namen für diesen API-Schlüssel an – ich werde Test Shop eingeben – und klicken Sie auf Applikationsbenutzer erstellen

4. Ihr Applikationsbenutzer wird dann erstellt. Kopieren Sie die User-ID und den Authentifizierungsschlüssel, da Sie diese benötigen, um Ihren Shop mit dem Portal zu verknüpfen

5. Abschliessend müssen Sie diesem Applikationsbenutzer bestimmte Berechtigungen erteilen, damit er mit Ihrem Space kommunizieren kann. Navigieren Sie dazu unter Rolle zu Verwalten.

6. Klicken Sie auf das + Zeichen neben Space-Roles.

7. Fügen Sie die Rolle “Space-Admin” hinzu und klicken Sie auf Rolle zuweisen.

   Tip | Bitte beachten Sie, dass das Laden der Rollen einige Sekunden dauern kann.

8. Klicken Sie abschließend auf Rollen speichern; Sie müssen Ihr Passwort zur Bestätigung eingeben.

## 5.2Zahlungsmethoden einrichten

Sie können nun die gewünschten Zahlungsmethoden einrichten. Für Testzwecke verwenden wir den Bogus-Verarbeiter. Bitte beachten Sie, dass Sie für Produktions Transaktionen entweder unser Payfac-Angebot nutzen oder sich direkt mit einem bestimmten PSP (Worldline; Nexi; …) verbinden können.

1. Navigieren Sie zu Space → Einstellungen und klicken Sie auf Verarbeiter.

2. Klicken Sie auf Verarbeiter einrichten.

3. Wählen Sie den gewünschten Verarbeiter aus und klicken Sie auf Weiter.

4. Richten Sie den Namen ein, den Sie Ihrem Verarbeiter geben möchten – z.B. Test Verarbeiter – und klicken Sie auf Erstellen.

5. Wählen Sie alle Konnektoren aus welche Sie nutzen möchten und klicken Sie auf Speichern.

   Tip | Bitte beachten Sie, dass die Konnektoren doppelt erscheinen, da einer für Zahlungen über physische Terminals und einer für E-Commerce-Zahlungen bestimmt ist.

Zahlungsmethoden sind nun im Portal verfügbar.

# 6Shop-Startanleitung

1. API-Zugangsdaten

   1. Navigieren Sie zu Shopware Admin → Einstellungen → Erweiterungen → VR Payment und klicken Sie auf Speichern.

   2. Geben Sie Ihre `Space ID`, `User ID`, und `API Key` ein.

      1. Die Space-ID finden Sie unter Space – z.B. Space-ID = 76231.

2. Zahlungsmethoden

   Die an der Kasse verfügbaren Zahlungsmethoden werden vom VR Payment Portal gesteuert. Wenn Sie eine Zahlungsmethode deaktivieren möchten, müssen Sie diese Zahlungsmethode im Portal deaktivieren.

   Note | Bitte beachten Sie, dass aufgrund der Synchronisierung zwischen Portal und Shop dasselbe auch im Shop unter Einstellungen → Zahlungsmethoden möglich ist.

   1. Gehen Sie zu Ihrem Space → Einstellungen → Zahlung → Zahlarten

   2. Wählen Sie die Zahlungsmethode aus, die Sie deaktivieren möchten. Klicken Sie auf den Schieberegler, um sie zu deaktivieren → sie sollte inaktiv werden.

      Tip | Wenn Sie nur einen Konnektor einer Zahlungsmethode deaktivieren möchten (z.B. Mastercard für eine Kreditkarte), gehen Sie zum Abschnitt Konnektor.

3. Optionen

   1. Space View Id: Dieses Feld ermöglicht es Ihnen, benutzerdefinierte Stile auf das Zahlungsformular und die Zahlungsseite anzuwenden. Die Stile werden in Ihren Space-Einstellungen im Portal definiert.

      Note | Bitte beachten Sie, dass diese Option leer bleiben sollte, wenn Sie die Space View Id nicht verwenden.

   2. Integration: Die Einstellung Integrationsoptionen bestimmt, wie das Zahlungsformular während des Checkout-Prozesses angezeigt wird. Die folgenden Optionen sind verfügbar:

      1. IFrame: Betten Sie das Zahlungsformular direkt in die Shopware-Checkout-Seite ein, um ein nahtloses Erlebnis zu gewährleisten.

      2. Lightbox: Öffnet ein sicheres Popup-Fenster, in dem Kunden ihre Zahlung abschließen können, ohne die Checkout-Seite zu verlassen.

      3. Payment Page: Leitet Kunden auf eine dedizierte Zahlungsseite weiter, die vom Zahlungsanbieter gehostet wird.

   3. Line Item Consistency: Shopware berechnet Steuern auf Ebene der Einzelpositionen, was zu geringfügigen Abweichungen (typischerweise einige Cent) zwischen der Gesamtsteuer der Bestellung und dem angezeigten Preis führen kann. Diese Abweichung tritt aufgrund von Rundungsdifferenzen bei der Berechnung einzelner Einzelpositionen auf. Wenn die Einstellung "Konsistenz erzwingen" aktiviert ist, lehnt das Portal automatisch Bestellungen mit solchen Abweichungen ab. Um Probleme bei der Zahlungsabwicklung zu vermeiden, empfehlen wir, diese Einstellung zu deaktivieren, es sei denn, eine strenge Validierung der Gesamtsteuer ist erforderlich.

   4. Bestellbestätigungs-E-Mail senden: Aktivieren Sie diese Option, um Bestellbestätigungs-E-Mails direkt von Shopware anstelle des Portals zu senden.

# 7Transaktionszustandsdiagramm

Der Zahlungsprozess von VR Payment ist für jede von Ihnen verarbeitbare Zahlungsmethode vollständig standardisiert. Dies gibt Ihnen die Möglichkeit, einfach eine Zahlungsmethode oder einen Prozessor hinzuzufügen, ohne Änderungen in Ihrer Shopware-Konfiguration vorzunehmen. Eine Übersicht über die Zustände und die Zahlungsprozesse von VR Payment finden Sie in de Zahlungsdokumentation.

Im folgenden Abschnitt geben wir Ihnen einen Überblick darüber, wie die VR Payment-Zustände in das Shopware-Zustandsdiagramm für Bestell- und Zahlungszustände abgebildet werden.

## 7.1Zustandsabbildung von Shopware-Bestellungen

Wir ändern derzeit nicht den Bestellstatus. Wir ändern nur den Zahlungsstatus und den Lieferstatus.

### 7.1.1Allgemeine Anmerkungen zu Bestellstatus

Wir empfehlen, dass Sie den Bestellstatus erst ändern, wenn der Zahlungsstatus einen Endzustand erreicht hat.

## 7.2Zustandsabbildung des Shopware-Zahlungsstatus

Nachfolgend finden Sie ein Diagramm, das den Zustandsprozess von Shopware für den Zahlungsstatus einschließlich zusätzlicher Informationen zu den Zustandsübergängen zeigt

1. Wenn die Transaktion in VR Payment `Authorized` ist, wird der Shopware-Bestellzahlungsstatus als `In Progress` markiert.

2. Wenn die Transaktion vor oder während des Autorisierungsprozesses fehlschlägt, wird der Shopware-Bestellzahlungsstatus als `Failed` markiert.

3. Wenn die Transaktion nach der `Authorized` fehlschlägt, wird der Shopware-Bestellzahlungsstatus als `Cancelled` markiert.

4. Wenn die Transaktionsrechnung in VR Payment als `Paid` oder `Not Applicable`, markiert ist, wird der Shopware-Bestellzahlungsstatus als `Paid` markiert.

### 7.2.1Allgemeine Anmerkungen zu Zahlungsstatus

Wir empfehlen, dass Sie den Zahlungsstatus nicht manuell ändern. Wenn Sie dies tun, kann er vom Plugin erneut geändert werden.

## 7.3Zustandsabbildung des Shopware-Lieferstatus

Nachfolgend finden Sie ein Diagramm, das den Zustandsprozess des Shopware-Lieferstatus einschließlich zusätzlicher Informationen zu den Zustandsübergängen zeigt

1. Wenn die Transaktion in VR Payment den Status `Confirmed` hat, wird der Shopware-Bestelllieferstatus als `Hold` markiert.

2. Wenn die Transaktion in VR Payment als `Fulfill` markiert ist, wird der Shopware-Bestelllieferstatus als `Open` markiert.

3. Wenn die Transaktion `Decline`, `Failed` oder `Voided`, wird der Shopware-Bestelllieferstatus als `Cancelled` markiert.

# 8Transaktionsverwaltung

Sie können Transaktionen direkt im Shopware-Backend erfassen, stornieren und erstatten. Bitte beachten Sie, dass Ereignisse in Shopware synchronisiert werden, wenn Sie Transaktionen in VR Payment erstatten, ungültig machen oder erfassen. Es gibt jedoch einige Einschränkungen (siehe unten).

## 8.1Bestellung abschließen (erfassen)

Sie haben die Möglichkeit, dass Ihre Transaktionen nach der Bestellung nur autorisiert werden. In der Konfiguration des Konnektors haben Sie die Möglichkeit, sofern die Zahlungsmethode dies unterstützt, festzulegen, ob die Zahlung sofort oder verzögert abgeschlossen werden soll. Um eine Transaktion zu erfassen, öffnen Sie die Bestellung und klicken Sie auf die Schaltfläche "Abschließen".

Note | Wenn der Abschluss in VR Payment ausstehend ist, bleibt die Bestellung im Status "Ausstehend".

Verzögerter Zahlungsabschluss

Händler haben oft den Fall, dass sie Transaktionen nur autorisieren und den Erfüllungsprozess erst starten möchten, wenn alle Artikel versandfähig sind. Dies ist auch mit VR Payment möglich. Es sollten jedoch bestimmte Prozesse befolgt werden. Wenn Sie den Zahlungsabschluss als verzögert konfiguriert haben, sollten Sie die Transaktion erfassen, bevor Sie den Versand einleiten, da ein Abschluss immer fehlschlagen kann. Wenn Sie sicherstellen möchten, dass Sie keine Artikel versenden, für die Sie nicht bezahlt wurden, sollten Sie den Versand verschieben, bis der Erfüllungsstatus erreicht ist. Anfangs befindet sich die Transaktion in VR Payment im Status `Authorized` und in Shopware im Status `In Progress`. Wenn Sie den Erfüllungsprozess starten möchten, stellen Sie sicher, dass Sie den Abschlussprozess wie oben beschrieben einleiten. Sobald der Abschluss erfolgreich war, wechselt die Bestellung in VR Payment in den Status `Fulfill` und in Shopware in den Status `Paid`. Sie können nun den Erfüllungsprozess starten.

## 8.2Transaktion stornieren

Um eine Transaktion zu stornieren machen, öffnen Sie die Bestellung und klicken Sie auf die Schaltfläche Cancel authorization.

Note | Sie können nur Transaktionen stornieren, die noch nicht abgeschlossen sind.

## 8.3Rückerstattung einer Transaktion

Sie haben die Möglichkeit, bereits abgeschlossene Transaktionen zurückzuerstatten. Öffnen Sie dazu die erfasste Bestellung. Indem Sie auf die 3 Punkte (…) in einer Einzelposition klicken, können Sie die Einzelposition teilweise (wenn sie eine höhere Menge als 1 hat) oder die gesamte Einzelposition zurückerstatten. Falls die Zahlungsmethode keine Rückerstattungen unterstützt, sehen Sie nicht die Möglichkeit, Online-Rückerstattungen auszustellen.

Sie können beliebig viele einzelne Rückerstattungen durchführen, bis Sie den Gesamtbetrag der ursprünglichen Bestellung erreicht haben. Der Status der Bestellung wechselt dann automatisch auf "abgeschlossen".

Note | Es kann einige Zeit dauern, bis Sie die Rückerstattung in Shopware sehen. Rückerstattungen sind erst sichtbar, wenn sie erfolgreich verarbeitet wurden.

## 8.4Bestellungen auf On Hold

Die Lieferung sollte nicht erfolgen, solange der Lieferstatus `Hold` ist. Dies tritt auf, wenn die Transaktion in VR Payment den Erfüllungsstatus nicht erreicht hat.

Dafür gibt es im Wesentlichen zwei Gründe:

- Die Transaktion ist nicht abgeschlossen. In diesem Fall müssen Sie die Transaktion wie oben beschrieben abschließen.

- Wir können nicht sagen, ob Sie die Bestellung erfüllen sollen. Die Lieferentscheidung erfolgt automatisch. Wenn dies nicht innerhalb des definierten Zeitrahmens erfolgt, generiert VR Payment eine manuelle Aufgabe, die Sie beachten und deren Anweisungen Sie befolgen sollten.

Weitere Informationen zu manuellen Aufgaben finden Sie in unserer Dokumentation zu manuellen Aufgaben..

## 8.5Einschränkungen der Synchronisierung zwischen VR Payment und Shopware

Bitte beachten Sie, dass Erfassungen, Stornierungen und Rückerstattungen, die in VR Payment durchgeführt werden, synchronisiert werden. Es gibt jedoch einige Einschränkungen. In VR Payment können Sie den Einzelpreis und die Menge gleichzeitig ändern. Dies ist im Shopware-Backend nicht möglich. Wir empfehlen daher, die Rückerstattungen immer im Shopware-Backend und nicht in VR Payment durchzuführen. Wenn eine Rückerstattung nicht synchronisiert werden kann, wird sie an den Prozessor gesendet, aber es kann sein, dass Sie sie nicht in Ihrem Shopware-Backend sehen.

Weitere Informationen zu Rückerstattungen in VR Payment finden Sie in unserer Dokumentation zu Rückerstattungen..

## 8.6Tokenisierung

Falls die Zahlungsmethode die Tokenisierung unterstützt, können Sie die Zahlungsdetails Ihrer Kunden für zukünftige Einkäufe speichern. Um diese Funktion zu nutzen, stellen Sie sicher, dass der One-Click-Zahlungsmodus in Ihrer Zahlungsmethodenkonfiguration auf `allow` oder `force` eingestellt ist.

Note | Die Tokenisierung ist für Gast-Checkouts nicht verfügbar

## 8.7Wiederkehrende Zahlungen

Shopware bietet das Paket "Shopware Commercial" mit zusätzlichen Funktionen, unter anderem Abonnements. Dieses Plugin unterstützt Zahlungen, die für Abonnements geeignet sind. Solange der Konnektor der Zahlungsmethode Tokenisierung unterstützt, kann er für Abonnements verwendet werden. Die wiederkehrende Zahlung wird vollständig vom Shopware Commercial Plugin verwaltet. Weitere Informationen finden Sie in deren Dokumentation.

## 8.8Hauptfunktionen

- iFrame Integration: Betten Sie Zahlungsformulare direkt in Ihren Checkout ein.

- Refunds & Captures: Lösen Sie vollständige/teilweise Rückerstattungen und Erfassungen von Shopware oder dem VR Payment Portal aus.

- Multi-Store Support: Verwalten Sie Konfigurationen über mehrere Stores hinweg.

- Automatic Updates: Zahlungsmethoden werden dynamisch über die VR Payment API synchronisiert.

- Wiederkehrende Zahlungen: Führen Sie wiederkehrende Zahlungen mit Abonnements (Shopware Commercial) und VRPayment durch.

## 8.9Fehlerbehebung

- Logs: Überprüfen Sie Zahlungslogs mit:

      COPY
      tail -f var/log/whitelabelname*.log

- Häufige Probleme:

  - Stellen Sie sicher, dass `composer update wallee/shopware-6` nach Updates ausgeführt wird.

  - Überprüfen Sie, ob die API-Zugangsdaten mit Ihrem VR Payment-Konto übereinstimmen.

## 8.10FAQs

F: Wie kann ich sicherstellen, dass die Verbindung zwischen Portal und Shop funktioniert?

A: Sie müssen überprüfen, ob die Webhooks korrekt erstellt wurden. Navigieren Sie dazu in Ihrem Space im Portal zu Einstellungen → Allgemein → Webhook-Listener.

F: Unterstützt dieses Plugin One-Click-Zahlungen? A: Ja, über die Tokenisierung im VR Payment Portal.

F: Wie handhabe ich die PCI-Konformität? A: Das Plugin verwendet die iFrame-Integration, wodurch die PCI-Anforderungen auf SAQ-A reduziert werden.

F: Unterstützt das Plugin Apple Pay? A: Ja, das Plugin unterstützt Wallets wie Apple Pay.

# 9Änderungsprotokoll

Versionsspezifische Updates finden Sie unter GitHub Releases.

# 10Mitwirken

Melden Sie Probleme über GitHub Issues.

Befolgen Sie den Shopware Shopware Plugin Base Guide für die Entwicklung.

# 11Support

Wenn Sie Hilfe benötigen, wenden Sie sich bitte an unseren support.