wallee Zahlungs-Plugin für Shopware 6

Documentation

1Übersicht

Das wallee 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 wallee 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 oder 6.6.x (see Kompatibilitätstabelle).

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

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

3Kompatibilität

Shopware Version

Plugin Version

PHP Version

Support Until

6.6.x

6.x.x

PHP 8.2 and 8.3

Ongoing

6.5.x - Deprecated

5.x.x

PHP 8.2 and 8.3

October 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.

    plugin installation

  4. Aktivieren Sie das wallee Zahlungs-Plugin im Plugin-Manager.

4.2Via Composer (Recommended)

  1. Navigieren Sie zu Ihrem Shopware-Stammverzeichnis.

  2. Führen Sie Folgendes aus:

    composer require wallee/shopware-6
php bin/console plugin:refresh
php bin/console plugin:install --activate --clearCache WalleePayment

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 WalleePayment

5Portal-Startanleitung

Gehen Sie zu wallee 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

    application users

  2. Klicken Sie auf Applikationsbenutzer erstellen

    user

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

    api key

  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

    token

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

    roles

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

    assign role

  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.
    loading roles

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

    save role

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.

    payment settings

  2. Klicken Sie auf Verarbeiter einrichten.

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

    bogus processor

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

    name processor

  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.
    connectors

Zahlungsmethoden sind nun im Portal verfügbar.

6Shop-Startanleitung

  1. API-Zugangsdaten

    1. Navigieren Sie zu Shopware Admin → Einstellungen → Erweiterungen → wallee 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.

        plugin configuration

  2. Zahlungsmethoden

    Die an der Kasse verfügbaren Zahlungsmethoden werden vom wallee 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

      payment methods

    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.

      cc enable
      cc disable
      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.

      order confirmation email

7Transaktionszustandsdiagramm

Der Zahlungsprozess von wallee 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 wallee finden Sie in de Zahlungsdokumentation.

Im folgenden Abschnitt geben wir Ihnen einen Überblick darüber, wie die wallee-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

shopware 6 stage graph order

  1. Wenn die Transaktion in wallee 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 wallee 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

shopware 6 stage graph delivery

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

  2. Wenn die Transaktion in wallee 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 wallee 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 wallee ausstehend ist, bleibt die Bestellung im Status "Ausstehend".
capture transaction

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 wallee 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 wallee 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 wallee 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.
void transaction

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.

refund transaction

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 wallee 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 wallee 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 wallee und Shopware

Bitte beachten Sie, dass Erfassungen, Stornierungen und Rückerstattungen, die in wallee durchgeführt werden, synchronisiert werden. Es gibt jedoch einige Einschränkungen. In wallee 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 wallee 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 wallee 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.7Hauptfunktionen

  • 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 wallee Portal aus.

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

  • Automatic Updates: Zahlungsmethoden werden dynamisch über die wallee API synchronisiert.

8.8Fehlerbehebung

  • Logs: Überprüfen Sie Zahlungslogs mit:

    COPY
tail -f var/log/whitelabelname_payment*.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 wallee-Konto übereinstimmen.

8.9FAQs

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.

webhooks
webhook listeners

F: Unterstützt dieses Plugin One-Click-Zahlungen? A: Ja, über die Tokenisierung im wallee 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.