Handbuch Shopware ab 6.2 (Version 0.0.1.2)

image_pdf

Inhaltsverzeichnis

Systemvoraussetzungen

Ergänzend zu den von Shopware vorgegebenen Systemrequirements (siehe zu den Shopware 6 Systemvoraussetzungen) benötigt das Plugin zum Betrieb Folgendes:

  • Sie benötigen einen heidelpay-Public-Key, sowie einen heidelpay-Private-Key (Anforderung über support@heidelpay.com oder vertrieb@heidelpay.com )
  • Mindestens PHP-Version 7.2
  • Mindestens Shopware-Version 6.2.0
  • Maximal Shopware-Version 6.3.1.0
  • Ihr Shopsystem muss für die IP-Adressen 3.120.66.194 sowie 35.158.69.58 erreichbar sein. Geben Sie diese bitte in Ihrer .htaccess-Datei oder sonstigen Zugriffskontrollen frei

Bitte beachten Sie, dass es sich beim heidelpay Plugin für Shopware 6.2 um Software im Beta-Status handelt. Bereits bekannte Verhaltensweisen finden Sie im FAQ aufgeführt und sind in den Standard-Workflows von Shopware 6.2 begründet.

direkt zum FAQ

Installation

Download aus dem Community Store

Aktuell kann das heidelpay-Plugin für Shopware 6 noch nicht über den Community Store bezogen werden.

Installation via Composer

Das heidelpay Plugin ab Shopware 6 finden Sie auf Github unter https://github.com/heidelpay/shopware-6. Nachdem der Downloadprozess abgeschlossen ist, finden Sie das Plugin im Verzeichnis „custom/plugins/HeidelPayment6“ und ist über den Plugin-Manager im Backend installierbar.

Siehe auch Shopware requiring plugins

Download als Zip von github / Installation via Plugin-Manager

  • Laden Sie das entpackte Zip in das Verzeichnis „/custom/plugins“
  • führen Sie folgende Console-Anweisung innerhalb des Verzeichnisses “ /custom/plugins/HeidelPayment6″ aus
    • composer install --no-dev
  •  Wechseln Sie nun ins Backend in den Plugin-Manager und installieren und aktivieren Sie das Plugin
  • Um Zahlungsstatus-Updates zu erhalten registrieren Sie die Webhooks siehe Punkt 3 der Basiskonfiguration

Basiskonfiguration

Die Basiskonfiguration des Plugins können Sie über den Plugin-Manager vornehmen.

Bitte beachten Sie nach Abschluss oder Änderungen Ihrer Konfigurationen die Shopware Caches zu leeren.

  1. Speichern Sie Ihre getätigten Einstellungen
  2. Testen Sie Ihre eingetragenen Zugangsdaten / Ihr heidelpay KeyPair
  3. Registrieren Sie die „Webhooks“ um Updates für Ihre Zahlungen zu erhalten und den Bezahlstatus der Bestellung automatisch zu ändern
  4. Wählen Sie den Verkaufskanal für den die Konfiguration angewendet werden soll
  5. Tragen Sie hier Ihren PublicKey ein
  6. Tragen Sie hier Ihren PrivateKey ein
  7. Bei aktivem TestModus werden Ihre Transaktionen gegen das heidelpay-Testsystem durchgeführt. Um Live-Transaktionen durchführen zu können deaktivieren Sie den Schalter.
  8. Entscheiden Sie ob Sie zu jeder Transaktion im Shopware-Log einen Eintrag wünschen. Die Aktivierung dieser Funktion dient hauptsächlich zu Analysezwecken
  9. Entscheiden Sie, in welchem Buchungsmodus Sie die Zahlart Kreditkarte / Debitkarte nutzen wollen.
  10. Entscheiden Sie ob die Kreditkartendaten als Referenz im Shop gespeichert werden sollen und Ihren Endkunden, ohne erneute Eingabe, beim nächsten Einkauf zur Verfügung stehen sollen.
  11. Entscheiden Sie, in welchem Buchungsmodus Sie die Zahlart PayPal nutzen wollen.
  12. Entscheiden Sie ob die PayPal-E-Mail als Referenz im Shop gespeichert werden sollen und Ihren Endkunden, ohne erneute Eingabe, beim nächsten Einkauf zur Verfügung stehen sollen.
  13. Legen Sie den effektiven Jahreszinssatz für den Flexipay® Ratenkauf fest (aktuell nicht verfügbar)
  14. Entscheiden Sie ob Lastschriftdaten des Endkunden als Referenz im Shop gespeichert werden sollen und Ihren Endkunden, ohne erneute Eingabe, beim nächsten Einkauf zur Verfügung stehen sollen.
  15. Stellen Sie hier Ihren Versandstatus ein, für den eine Versandmeldung an heidelpay automatisch generiert und verschickt wird. (siehe auch Meldung des Versands)

Weitere Konfigurationen

Zahlarten aktivieren

  1. Wechseln Sie in den Sales Channel für den Sie die Zahlarten aktivieren möchten
  2. Wählen Sie Ihre gebuchten Zahlarten aus
  3. Wählen Sie ggf. Ihre Standard-Bezahlart aus (optional)

Zahlart-Namen ändern

  1. Um Namen einer Zahlart zu ändern, wechseln Sie auf „Einstellungen->Shop->Zahlungsarten“
  2. Wählen Sie die zu bearbeitende Zahlart aus
  3. Bearbeiten Sie die Bezahlart

  1. Hier können Sie den in der Storefront angezeigten Namen der Zahlart ändern
  2. Bestimmen Sie die Anzeige-Reihenfolge für den Endkunden
  3. Fügen Sie ggf. einen zusätzlichen Beschreibungstext hinzu
  4. Fügen Sie ggf. ein Logo für die Zahlart hinzu
  5. Bestimmen Sie über die „Verfügbarkeitsregeln“ (Rulebuilder) wann die Bezahlart für den Endkunden verfügbar sein soll (Länderbeschränkungen, Kundengruppen etc.)
  6. Aktivieren Sie die Zahlart oder deaktivieren Sie sie
  7. Soll die Zahlart nach Abbruch oder Ablehnung der Zahlung weiterhin für den Endkunden auswählbar sein?
  8. Speichern Sie Ihre Einstellungen

Spezielle Zahlart-Beschränkungen

Für einzelne Zahlarten des Plugins gelten Beschränkungen der Nutzung. Diese können Sie bequem über den „Shopware Rulebuilder“ erstellen und nahezu Systemweit verwenden.

iDEAL

Stellen Sie für die Zahlart iDEAL sicher, dass ausschließlich Endkunden mit Rechnungsadresse aus den Niederlanden die Zahlart nutzen können.

EPS

Stellen Sie für die Zahlart EPS sicher, dass ausschließlich Endkunden mit Rechnungsadresse aus Österreich die Zahlart nutzen können.

PostFinance

Stellen Sie für die Zahlart PostFinance sicher, dass ausschließlich Endkunden mit Rechnungsadresse aus der Schweiz die Zahlart nutzen können.

Stellen Sie für die Zahlart PostFinance ebenfalls sicher, dass ausschließlich die Währung Schweizer Franken (CHF) für die Zahlart genutzt wird.

Przelewy24

Stellen Sie für die Zahlart Przelewy24 sicher, dass ausschließlich Endkunden mit Rechnungsadresse aus Polen die Zahlart nutzen können.

Stellen Sie für die Zahlart Przelewy24 ebenfalls sicher, dass ausschließlich die Währung Zloty (PLN) für die Zahlart genutzt wird.

Flexipay® Lastschrift

Stellen Sie für die Zahlart Flexipay® Lastschrift sicher, dass ausschließlich Endkunden mit Rechnungsadresse aus den Ländern Deutschland, Österreich und Schweiz die Zahlart nutzen können.

Stellen Sie für die Zahlart Flexipay® Lastschrift ebenfalls sicher, dass ausschließlich die Währung Euro (EUR) und Schweizer Franken (CHF) für die Zahlart genutzt werden können.

Flexipay® Rechnungskauf (gesichert / factoring)

Stellen Sie für die Zahlart Flexipay® Rechnungskauf sicher, dass ausschließlich Endkunden mit Rechnungsadresse aus den Ländern Deutschland und Österreich die Zahlart nutzen können.

Stellen Sie für die Zahlart Flexipay® Rechnungskauf weiterhin sicher, dass ausschließlich die Währung Euro (EUR) für die Zahlart genutzt werden können.

Stellen Sie für die Zahlart Flexipay® Rechnungskauf ebenfalls sicher, dass die Zahlart nur in den mit heidelpay vertraglich vereinbarten Min-/Max-Beträgen genutzt werden kann.

Nachfolge-Transaktionen

Geldeinzug / Charge / Captures nach Reservierung

  1. Navigieren Sie im Adminbereich zu den „Bestellungen“ und wählen Sie dort die Bestellung aus, für die ein Geldeinzug / Charge / Capture durchgeführt werden soll über den „Anzeigen“-Button (1)
  2. In der Detailansicht der Bestellung wechseln Sie in den Heidelpay-Reiter (1). Betätigen Sie das 3-Punkt-Menü (2) neben der „Reservierung“-Transaktion und öffnen Sie damit die Eingabeoberfläche (3). Geben Sie den Betrag ein, den Sie einziehen wollen und betätigen Sie „Einziehen“.

Storno / Reduzierung von Rechnungsbeträgen

  1. Navigieren Sie im Adminbereich zu den „Bestellungen“ und wählen Sie dort die Bestellung aus, für die ein Storno / Rückerstattung durchgeführt werden soll über den „Anzeigen“-Button.
  2. In der Detailansicht der Bestellung wechseln Sie in den Heidelpay-Reiter (1). Betätigen Sie das 3-Punkt-Menü (2) eines „Einzuges“, der den Geldfluss zu Ihnen darstellt, und öffnen Sie damit die Eingabeoberfläche (3). Geben Sie den Betrag ein, den Sie einziehen wollen und betätigen Sie „Rückerstatten“.

Meldung des Versands / Shipping / Finalize

Eine Versandmeldung kann nur dann an das heidelpay-System gemeldet werden, wenn zu der Bestellung auch eine Rechnungsnummer in der dafür vorgesehenen Shopware-Tabelle vorhanden ist.

Automatische Versandmeldung

Stellen Sie in den Plugin-Einstellungen „Versandstatus für die Versandmeldung“ den gewünschten Versand-Status ein, bei dem eine automatische Versandmeldung generiert werden soll. Siehe hierzu auch Basiskonfiguration Punkt 15

Sobald sich der Versandstatus auf den von Ihnen eingestellten Wert ändert, und eine Rechnungsnummer im System vorliegt, wird die automatische Versandmeldung in Höhe des ursprünglichen Bestellwertes generiert. Teilbeträge sind aktuell noch nicht möglich.

Versandmeldung über Bestelldetails

Sobald für die Bestellung eine Rechnung über das Backend erzeugt wurde, wird ein Button „Versandmitteilung“ im Heidelpay-Reiter der Bestelldetail-Ansicht angezeigt. Durch Betätigen des Buttons wird der Versand an heidelpay gemeldet / die Versicherung aktiviert. Auch bei dieser Versandmeldung ist aktuell nur der gesamte ursprüngliche Rechnungsbetrag als Shipping-Meldung möglich.

Abläufe bei Nutzung spezieller Zahlungsarten

Flexipay® Rechnung (gesichert, factoring)

Für die Zahlarten „Flexipay® Invoice guaranteed“ sowie „Flexipay® Invoice factoring“ müssen sog. Shippment-/Versand- Meldungen generiert werden, um die Zahlungsgarantie zu aktivieren. Siehe hierzu Meldung des Versands / Shipping / Finalize

Darstellung der Kontodaten zur Überweisung

Bei Post-Paid-Zahlungsarten wie Rechnungskäufen und Vorkasse müssen dem Endkunden Daten zur Zahlung angezeigt angezeigt werden.

Bestellbestätigungsseite (jeder Kunde)

Nach Bestellabschluss wird der Endkunde auf die „Vielen Dank für Ihre Bestellung“-Seite geleitet. Hier werden ihm die Daten zur Überweisung wie folgt dargestellt:

Bestellbestätigungs-E-Mail (jeder Kunde)

Aktuell bietet Shopware 6.2 noch keine Möglichkeit via Plugin die Bestellbestätigungs-E-Mail zu beeinflussen, da die Bestellbestätigungs-E-Mail zu einem Zeitpunkt verschickt wird, bei dem die Zahlung noch nicht abgeschlossen ist.

Rechnungsdokument

Wenn ein Rechnungsdokument innerhalb des Shopware-Backends generiert wird, so werden automatisch die Daten zur Überweisung auf das Rechnungs-PDF hinzugefügt.Content-/ Footer-Bereich

Aktuell bietet Shopware 6.2 noch keine Möglichkeit via Plugin den Footer-Bereich der Rechnung zu beeinflussen. heidelpay wird dieses Feature nachziehen, sobald die Möglichkeit besteht.

Referenz auf Bestellungen im heidelpay-System (Merchant-hIP)

Innerhalb der Bestellungen-Detailansicht, im heidelpay-Reiter, finden Sie mehrere Referenz-Ids. Unter anderem die „Zahlungs-ID“ im Format „s-pay-X“ oder „p-pay-X“, sowie die „Short-Id“ im Format „xxxx.xxxx.xxxx“. Beide Referenzen sind auch im Merchant-hIP suchbar

Developer / Entwickler Info

Textbausteine

Das heidelpay Plugin für Shopware 6.2 liefert im Standard die Textbausteine in DE und EN. Diese sind im Namespace „HeidelPayment“ abgelegt. Sie können über die Suche jeden Textbaustein einfach finden und individuell bearbeiten.

Registrierte Zahlungsdaten

Die Referenzen auf gespeicherte Bezahldaten der Endkunden finden Sie in der Tabelle „heidelpay_payment_device“. Die Payment-Type-Ids (Spalte „type_id“) können Ihnen für beispielsweise Abo-Transaktionen zur Verfügung stehen. Aus Sicherheitsgründen wird bei Verwendung von anderen Kunden-Adressen ein „Adress-Hash“ erzeugt, der allerdings ausschließlich im Plugin zur Validierung herangezogen wird. Die Spalte „customer_id“ ist als Referenzierung zum Kundenkonto in Shopware zu betrachten.

Darstellung Zahlungsstatus

Das heidelpay-Plugin ab Shopware 6.2 stellt den aktuellen Zahlungsstatus wie folgt dar

Kreditkarte

Buchungsmodus Aktion Zahlungsstatus
Direkte Belastung Bezahlung erfolgreich bezahlt
Kunde ist bei 3D-Secure (via Webhook) offen
Bezahlung abgebrochen /
Fehler bei Zahlung
abgebrochen
Chargeback fehlgeschlagen
Reservierung Bezahlung erfolgreich offen
Kunde ist bei 3D-Secure (via Webhook) offen
Geldeinzug erfolgt (charged) bezahlt
Bezahlung abgebrochen /
Fehler bei Zahlung
abgebrochen
Chargeback fehlgeschlagen

PayPal

Buchungsmodus Aktion Zahlungsstatus
Direkte Belastung Bezahlung erfolgreich bezahlt
Kunde ist bei PayPal offen
Bezahlung abgebrochen /
Fehler bei Zahlung
abgebrochen
Chargeback fehlgeschlagen
Reservierung Bezahlung erfolgreich offen
Kunde ist bei PayPal offen
Geldeinzug erfolgt (charged) bezahlt
Bezahlung abgebrochen /
Fehler bei Zahlung
abgebrochen
Chargeback fehlgeschlagen

SEPA Lastschrift / Flexipay® Lastschrift

Aktion Zahlungsstatus
Bezahlung erfolgreich bezahlt
Bezahlung abgebrochen / Fehler bei Bezahlung fehlgeschlagen
Chargeback (Rücklastschrift) fehlgeschlagen

Online Transafer

Sofort / Flexipay® direct / giropay / Przelewy24 / iDEAL / EPS / WeChat Pay / AliPay

Aktion Zahlungsstatus
Bezahlung erfolgreich bezahlt
Kunde ist in externem System offen
Bezahlung abgebrochen / Fehler bei Bezahlung abgebrochen
Chargeback (Rücklastschrift) fehlgeschlagen

Vorkasse

Aktion Zahlungsstatus
Kaufabschluss erfolgreich offen
Geldeingang (Gesamtbetrag) via Webhook bezahlt
Geldeingang (Teilbetrag) via Webhook teilweise bezahlt
Geldeingang (Überzahlung) via Webhook bezahlt
Fehler fehlgeschlagen

Rechnungskäufe

Zahlart Aktion Zahlungsstatus
Rechnung Kaufabschluss erfolgreich offen
Geldeingang (Gesamtbetrag) via Webhook bezahlt
Geldeingang (Teilbetrag) via Webhook teilweise bezahlt
Geldeingang (Überzahlung) via Webhook bezahlt
Fehler fehlgeschlagen
Flexipay® Rechnung (gesichert) Kaufabschluss erfolgreich offen
erfolgreiche Versandmeldung (Shipment) Gesamtbetrag bezahlt
Geldeingang (Gesamtbetrag) via Webhook bezahlt
Geldeingang (Teilbetrag) via Webhook teilweise bezahlt
Geldeingang (Überzahlung) via Webhook bezahlt
Fehler / Ablehnung fehlgeschlagen
Flexipay® Rechnung (factoring) Kaufabschluss erfolgreich bezahlt
erfolgreiche Versandmeldung (Shipment) Gesamtbetrag bezahlt
Geldeingang (Gesamtbetrag) via Webhook bezahlt
Geldeingang (Teilbetrag) via Webhook bezahlt
Geldeingang (Überzahlung) via Webhook bezahlt
Fehler / Ablehnung fehlgeschlagen

FAQ

Known issues

Änderung Zahlungsstatus / Anlegen des Zahlungsstatus

Bei „Flexipay® Invoice guranteed“ wird nach Teilzahlungen der Bezahlstatus mit „teilweise bezahlt“ angelegt. Auch bei weiteren Zahlungen ändert sich der Zahlungsstatus nicht mehr. Wir arbeiten hier an einer Lösung für eine nächste Version des Plugins.

Bei „Flexipay® Invoice factoring“ wird nach erfolgreicher Bestellung der Zahlungsstatus mit „bezahlt“ angelegt, obwohl noch keine Zahlung stattgefunden hat. Wir arbeiten hier an einer Lösung für eine nächste Version des Plugins.

Anlegen von Bestellungen im Admin

Aktuell ist es nicht möglich bei aktivem heidelpay-Plugin eine Bestellung via Admin anzulegen

Verhalten von Shopware 6.2 bei Bestellabschluss

Zum aktuellen Zeitpunkt, in den Shopware-Versionen 6.2 – 6.2.3, wird eine Bestellung im Shop-Admin angelegt, sobald der Endkunde den „Zahlungspflichtig bestellen“-Button betätigt. Zu diesem Zeitpunkt wird auch eine Bestellbestätigungs-E-Mail vom System versendet. Es ist hierbei egal, ob eine Zahlung zu dieser Bestellung stattgefunden hat, diese erfolgreich war oder abgelehnt wurde. Der Shopware-6.2-Workflow sieht bei abgelehnten oder abgebrochen Zahlungen vor, dass der Endkunde die „Vielen Dank für Ihre Bestellung“-Seite sieht mit einem Hinweis „Leider ist die Zahlung fehlgeschlagen. Bitte ändere die Zahlart um die Bestellung abzuschließen. Zahlung ändern„. Weiterhin erhält der Endkunde eine Bestellbestätigungs-E-Mail, als hätte er die Zahlung erfolgreich durchgeführt.Der Endkunde kann jetzt über den blauen Link im roten Kasten seine „Zahlung ändern“ (Zahlungsmittel). Hierzu muss allerdings eine Zahlart für den Wechsel im Admin in den „Einstellungen->Zahlungsarten“ freigeschaltet sein, oder bei Klick an eine andere Shopseite wird der Warenkorb geleert und der Kunde teilweise ausgelogged.