Handbuch Shopware ab 5.6

Systemvoraussetzungen

Ergänzend zu den von Shopware vorgegebenen Systemrequirements (siehe https://docs.shopware.com/de/shopware-5-de/tutorials-und-faq/systemanforderungen-hosting) benötigt das Plugin zum Betrieb folgendes:

Achtung: Wichtig für Bestandskunden bzw Anwender die bereits das bestehenden Plugin im Einsatz haben.

Für Anwender die bereits das bestehenden Plugin (heidelpay – Payment Plugin für Zahlungen per Kreditkarte, Rechnungskauf, Ratenkauf, SOFORT, …) verwenden, ist es notwendig beiden Shop-Plugins parallel im Shopware einzubinden bzw. zu konfigurieren.
Vorzugsweise sollten Sie im neuen Plugin die benötigten Zahlungsarten (z.B. Kreditkarte/Debitkarte) aktivieren, da diese auch nur dann im Checkout verwenden werden → zugleich muss im alten Plugin die „entsprechende“ Zahlungsart deaktiviert werden.
Das alte Plugin muss für die darüber getätigten Bestellung übergangsweise weiterhin konfiguriert und aktiviert sein, um die Kommunikation zwischen einer alten Bestellungen und der Heidelpay-Schnittstelle (NGW) aufrecht zu erhalten → z.B. bei einer Retoure / Refund.
Das neue Plugin kann nicht auf alte Bestellungen/Transaktionen referenzieren. Gleiches gilt auch für vorhandene Kreditkarten Registrierungen.  Die Endkunden müssen ihre Bezahldaten neu registrieren.

Installation

Download aus dem Community Store

Das heidelpay Plugin ab Shopware 5.6 finden Sie im Community Store, indem Sie innerhalb Ihres Shop-Backends in der Suche „heidelpay“ eingeben. Der Download erfolgt ganz einfach über den „Kostenlos“-Button. Nach dem Download befindet sich das Plugin im Verzeichnis „…/custom/plugins/HeidelPayment“ und ist über den Plugin-Manager über den „Installieren“-Button installierbar.

Installation via Composer

Das heidelpay Plugin ab Shopware 5.6 finden Sie auf Github unter https://github.com/heidelpay/shopware-5.git. Nachdem der Installationsprozess abgeschlossen ist finden Sie das Plugin im Verzeichnis „…/plugins/HeidelPayment“ und ist über den Plugin-Manager im Backend installierbar.

Download aus dem Community Store /

Installation via Composer

Nachdem das Plugin innerhalb Ihres Filesystems existent ist, können Sie es über den Plugin-Manager installieren und aktivieren. Die Installation funktioniert ebenfalls via bekannten Consolenbefehlen.

Basis Konfiguration

Die Basiskonfiguration des Plugins können Sie sowohl über den Plugin-Manager als auch über das Menü „Einstellungen→Grundeinstellungen→Zahlungsarten→Heidelpay“ vornehmen.

Bitte beachten Sie nach Abschluss Ihrer Konfigurationen die Shopware Caches zu leeren und die Themes neu zu kompilieren.

  1. Tragen Sie hier Ihren „Public Key“ ein. Um das Plugin im Test-Modus (Sandbox) zu betreiben achten Sie bitte darauf, dass dem Key ein „s-“ voran steht. Für den Live-Modus muss im Key ein „p-“ Präfix voran stehen. Die Zugangs-Keys erhalten Sie unter support@heidelpay.com
  2. Tragen Sie hier Ihren „Private Key“ ein. Um das Plugin im Test-Modus (Sandbox) zu betreiben achten Sie bitte darauf, dass dem Key ein „s-“ voran steht. Für den Live-Modus muss im Key ein „p-“ Präfix voran stehen. Die Zugangs-Keys erhalten Sie unter support@heidelpay.com
  3. Im „Test Modus“ werden im Frontend Test-Bezahldaten angezeigt bei verschiedenen Bezahlverfahren. Für den „Live Modus“ werden keine Test-Bezahldaten angezeigt.
  4. Buchungsmodus Kreditkarte / Debitkarte:
    1. „direkte Buchung“ = sofortige Belastung auf der Karte des Endkunden
    2. „Reservierung“ = Reservierung des Rechnungsbetrages auf der Kreditkarte. Ein späterer Charge (ehemals Capture) ist notwendig.
    3. „Registrierung mit…“ = Die Zahlungsdaten des Endkunden werden als Referenz PCI-konform im Shopsystem hinterlegt. Der Kunde muss diese bis zum Ablauf des etwaigen Gültigkeitsdatums nicht mehr eingeben
  5. Buchungsmodus Paypal:
    1. „direkte Buchung“ = sofortige Belastung auf Paypal-Konto des Endkunden
    2. „Reservierung“ = Reservierung des Rechnungsbetrages auf dem Paypal-Konto. Ein späterer Charge (ehemals Capture) ist notwendig.
  6. Buchungsmodus Lastschrift:
    1. „direkte Buchung“ = sofortige Belastung auf Paypal-Konto des Endkunden
    2. „Reservierung“ = Reservierung des Rechnungsbetrages auf dem Paypal-Konto. Ein späterer Charge (ehemals Capture) ist notwendig.
  7. Wünschen Sie, dass die von Shopware generierte Rechnung bei Rechnungskäufen über heidelpay mit den Überweisungsdaten versehen wird? So stellen Sie die Option auf „Ja“
  8. Wünschen Sie, dass die von Shopware generierte Rechnung bei Vorkasse über heidelpay mit den Überweisungsdaten versehen wird? So stellen Sie die Option auf „Ja“
  9. Aktivieren Sie das erweiterte Logging um alle Aufrufe der Heidelpay-Schnittstelle (Merchant Gateway) zu protokollieren. Sie finden das Log unter „Einstellungen->Logfile->System-Log->plugin_production-JJJJ-MM-TT“.
  10. Bei Aktivierung dieser Option werden die Bezahl-Status an den Bestellungen automatisch angepasst je nach Zustand der Bezahlung / Bestellung. Beispiel: Rechnungskauf versichert →Zahlstatus „Reserviert“ → Zahlungseingang vom Endkunden an heidelpay → Zahlstatus „komplett bezahlt“
  11. Wünschen Sie, dass eine automatische Versandmeldung (nur für Rechnungskauf versichert und factoring) an heidelpay gesendet wird? So stellen Sie hier den Status ein bei dem automatisch die Versandmitteilung versendet werden soll.
  12. Um Aktualisierungen der Bezahlungen empfangen zu können müssen sog. Webhooks auf Ihr System registriert werden. Diese Webhook-Registrierung können Sie über den Button tätigen (ehemals Push-Benachrichtigungen). Ohne Aktivierung der Webhooks kann die heidelpay-Schnittstelle keine Benachrichtigungen an Ihr Shopsystem senden. Bitte achten Sie darauf, dass Ihr System für die heidelpay-Systeme erreichbar ist

Weitere Konfigurationen

Zahlarten aktivieren

Über den Menüpunkt „Einstellungen→Zahlarten“ gelangen Sie zu den durch das Plugin installierten Bezahlmethoden. Hier können Sie die Zahlmethoden über die verschiedenen Reiter sowohl für bestimmte Subshops als auch Länder aktivieren oder verbieten. Im Reiter „Generell“ können Sie:

  1. Bezeichnung änder den im Frontend dargestellten Namen der Bezahlmethode
  2. Zusätzliche Beschreibung wird unterhalb des Namens der Bezahlmethode angezeigt
  3. Bei Aufschlag / Abschlag können Sie einen Aufschlag für die Verwendung dieser Bezahlmethode bestimmen
  4. Über die Position legen Sie die Reihenfolge der Anzeige der Bezahlmethoden fest
  5. Aktivieren Sie die Bezahlmethode, Sie können ebenfalls für ESD Produkte aktivieren oder für Smartphones deaktivieren
  1. Bezeichnung änder den im Frontend dargestellten Namen der Bezahlmethode
  2. Zusätzliche Beschreibung wird unterhalb des Namens der Bezahlmethode angezeigt
  3. Bei Aufschlag / Abschlag können Sie einen Aufschlag für die Verwendung dieser Bezahlmethode bestimmen
  4. Über die Position legen Sie die Reihenfolge der Anzeige der Bezahlmethoden fest
  5. Aktivieren Sie die Bezahlmethode, Sie können ebenfalls für ESD Produkte aktivieren oder für Smartphones deaktivieren

Verändern Sie nicht:

  • Name
  • URL für iFrame

Riskmanagement

ber „Einstellungen→Riskmanagement“ gelangen Sie zu den Optionen die Bezahlarten nur anzuzeigen wenn bestimmte Bedingungen erfüllt sind. Anhand des Beispiels „Rechnungskauf (gesichert, heidelpay) soll eine Beispiel-Konfiguration dargestellt werden.

Unter Zahlungsart wählen wählen Sie „Rechnung (gesichert, heidelpay)“ oder den von Ihnen für diese Zahlart vergebenen Namen

Im Bereich Sperre Zahlungsart WENN definieren Sie folgende Bedingungen:

  • Bestellwert >= → Der Wert den Sie als Maximalbetrag für den gesicherten Rechnungskauf mit heidelpay vertraglich vereinbart haben
  • Bestellwert <= → Der Wert den Sie als Minimalbetrag für den gesicherten Rechnungskauf mit heidelpay vertraglich vereinbart haben
  • Lieferadresse != Rechnungsadresse → Um Betrugsversuche zu verhindern
  • Kundengruppe IST → Das Kürzel für die Kundengruppe, die B2C-Kunden / Shopkunden in Ihrem Shop darstellen
  • weitere eigene Konfigurationen möglich

Konfigurationen für spezielle Zahlarten

iDeal

  • Stellen Sie entweder über „Einstellungen→Riskmanagement“ oder über „Zahlungsarten→ Länder-Auswahl“ sicher, dass die Zahlart nur Kunden mit Niederländischen Rechnungs- / Lieferadressen zur Auswahl steht

EPS

  • Stellen Sie entweder über „Einstellungen→Riskmanagement“ oder über „Zahlungsarten->Länder-Auswahl“ sicher, dass die Zahlart nur Kunden mit Österreichischen Rechnungs- / Lieferadressen zur Auswahl steht

PostFinance

  • Stellen Sie entweder über „Einstellungen→Riskmanagement“ oder über „Zahlungsarten->Länder-Auswahl“ sicher, dass die Zahlart nur Kunden mit Rechnungs- / Lieferadressen aus der Schweiz zur Auswahl steht
  • Stellen Sie entweder über „Einstellungen→Riskmanagement“ sicher, dass die Zahlart nur mit der Währung CHF (Schweizer Franken) zur Auswahl steht

Prezlewy24

  • Stellen Sie entweder über „Einstellungen→Riskmanagement“ oder über „Zahlungsarten->Länder-Auswahl“ sicher, dass die Zahlart nur Kunden polnischen mit Rechnungs- / Lieferadressen zur Auswahl steht
  • Stellen Sie entweder über „Einstellungen→Riskmanagement“ sicher, dass die Zahlart nur mit der Währung PLN (Zloty) zur Auswahl steht

SEPA Lastschrift (gesichert, heidelpay)

  • Stellen Sie entweder über „Einstellungen→Riskmanagement“ oder über „Zahlungsarten->Länder-Auswahl“ sicher, dass die Zahlart nur Kunden mit Rechnungs- / Lieferadressen aus DE, AT und CH zur Auswahl steht
  • Stellen Sie über „Einstellungen→Riskmanagement“ sicher, dass die Zahlart nur Endkunden mit den Währungen EUR (Euro), CHF (schweizer Franken) zur Auswahl steht
  • Stellen Sie über „Einstellungen→Riskmanagement“ sicher, dass die Zahlart nur Endkunden mit der Kundengruppe Shopkunden / B2C-Kundengruppe zur Auswahl steht
  • Stellen Sie über „Einstellungen→Riskmanagement“ sicher, dass die Zahlart bei Endkunden bei denen Lieferadresse != Rechnungsadresse ist ausgeblendet wird um kostenpflichtige Ablehnungen zu verhindern

Rechnung (gesichert, heidelpay) / Rechnung (factoring, heidelpay)

  • Stellen Sie entweder über „Einstellungen→Riskmanagement“ oder über „Zahlungsarten->Länder-Auswahl“ sicher, dass die Zahlart nur Kunden mit Rechnungs- / Lieferadressen aus DE, AT zur Auswahl steht
  • Stellen Sie über „Einstellungen→Riskmanagement“ sicher, dass die Zahlart nur Endkunden mit der Währung EUR (Euro) zur Auswahl steht
  • Stellen Sie über „Einstellungen→Riskmanagement“ sicher, dass die Zahlart nur Endkunden mit der Kundengruppe Shopkunden / B2C-Kundengruppe zur Auswahl steht
  • Stellen Sie über „Einstellungen→Riskmanagement“ sicher, dass die Zahlart bei Endkunden bei denen Lieferadresse != Rechnungsadresse ist ausgeblendet wird um kostenpflichtige Ablehnungen zu verhindern

Versandmethoden

Über Einstellungen→ Versandkosten gelangen Sie zum Versandkosten-Modul von Shopware. Über den „Stift“ können Sie die einzelne Versandmethode bearbeiten und wechseln in den Tab „Zahlart Auswahl.

Markieren Sie die von Ihnen gewünschten Zahlarten mit einfachem Linksklick in verfügbar und verschieben Sie die Zahlarten in den ausgewählt-Tab über den angezeigten Button-Pfeil nach rechts.

Nachfolge-Transaktionen

Der Endkunde führt die Zahlungen durch. Bei einigen Zahlmethoden und Einstellungen müssen Nachfolge-Transaktionen initiiert werden um Geldfluss zu erzeugen.

Charges / Captures nach Reservierung

Bei Verwendung des Buchungsmodus „Reservierung“ entstehen reservierte Bestellungen. Die Rechnungsbeträge werden auf dem gewählten Zahlungsmittel reserviert. Um den Rechnungsbetrag zu belasten gehen Sie wie folgt vor:

 

Wechseln Sie von der Bestellübersicht (Kunden→Bestellungen) in die Detailansicht der Bestellung über den „Stift“.

  1. Wechseln Sie in den Heidelpay-Tab und wählen Sie die Reservierungs-Transaktion an
  2. Geben Sie den Betrag ein, den Sie belasten möchten (es kann maximal der reservierte Betrag belastet werden)
  3. Betätigen Sie den „Einziehen“-Button

Nach Erfolgreicher Buchung erscheint in der Tabelle ein neuer Eintrag „Einzug / Betrag / Datum“

Sie können maximal den Betrag belasten, der reserviert wurde.

Storno / Reduzierung von Rechnungsbeträgen

Um Teil- oder Vollstornos durchzuführen gehen Sie wie folgt vor:

  1. Wählen Sie die Transaktion „Einzug“ aus, deren Betrag Sie stornieren wollen 1
  2. Geben Sie den Betrag ein, den Sie stornieren möchten
  3. Betätigen Sie den „Rückerstatten“-Button

1 Im Falle von Rechnung- und Vorkasse-Transaktionen können mehrere „Einzüge“ aufgelistet sein. Wählen Sie hier diejenigen mit dem aktuellsten Datum.

Sie können maximal den Betrag rückerstatten / stornieren, der bezahlt / reserviert  wurde.

Meldung des Versands / Shipping / Finalize

Für Rechnung (versichert, heidelpay) und Rechnung (factoring, heidelpay) muss eine Versandmeldung an heidelpay übermittelt werden um die Versicherung zu aktivieren.  Sie haben die Möglichkeit bei Umstellung des Bestellstatus automatisch eine Versandmitteilung generieren und verschicken zu lassen oder es kann innerhalb der Bestelldetailansicht eine Versandmitteilung generiert werden.

Automatische Versandmeldung

Stellen Sie hierzu innerhalb der Plugin-Einstellungen (Einstellungen→ Grundeinstellungen→ Zahlarten→Heidelpay) im Konfigurationspunkt „Bestellstatus für Versandnachricht“ den Bestell-Status ein, bei dem automatisch eine Versandmeldung generiert werden soll.

Versandmeldung über Bestelldetails

siehe Meldung des Versands/Shipping/Finalize

Abläufe bei Nutzung spezieller Zahlungsarten

Rechnung (gesichert, heidelpay), Rechnung (factoring, heidelpay)

Nach der Kaufentscheidung des Endkunden müssen Sie den Versand der Ware an heidelpay melden um die Versicherung der Beträge zu aktivieren. gehen Sie hierzu wie folgt vor:

  1. Wechseln Sie in die Detailansicht der Bestellung in den Reiter „Dokumente“ und generieren Sie das Rechnungsdokument. (Auf dem von Shopware generierten Rechnungsdokument werden auch die Daten zur Überweisung aufgedruckt, sobald sie die entsprechende Plugin-Einstellung aktiviert haben)
  2. Wechseln Sie in den Tab „Heidelpay“ und betätigen Sie den „Versandmitteilung“-Button (1). Nach einer erfolgreichen Versandmitteilung erscheint ein neuer Eintrag in der tabellarischen Übersicht „Versandmitteilung“ (2) 
  3. Eine Zahlung des Endkunden wird mit einem neuen „Einzug“-Eintrag in der tabellarischen Übersicht dargestellt

Darstellung der Kontodaten zur Überweisung

Die Kontodaten (IBAN, BIC, Verwendungszweck) werden den Endkunden mehrfach dargestellt.

Bestellbestätigungsseite

Bestellbestätigungs-E-Mail

Um die Kontodaten zur Überweisung auf das E-Mail-Template „Einstellungen-> E-Mail-Vorlagen->System-E-Mails->sOrder“ zu bringen, müssen Sie folgenden Text-Block an der Stelle in die Vorlage einsetzen, an der Sie die Kontodaten platzieren wollen.

{if $additional.heidelpay.bankData}
    Bitte überweisen Sie den Betrag auf das nachfolgende Bankkonto:
    
    <table>
        <tr>
            <td><strong>IBAN</strong></td>
            <td>{$additional.heidelpay.bankData.iban}</td>
        </tr>     
        <tr>
            <td><strong>BIC</strong></td>
            <td>{$additional.heidelpay.bankData.bic}</td>
        </tr>
        <tr>
            <td><strong>Holder</strong></td>
            <td>{$additional.heidelpay.bankData.holder}</td>
        </tr>   
        <tr>
            <td><strong>Descriptor</strong></td>
            <td>{$additional.heidelpay.bankData.descriptor}</td>
        </tr> 
        <tr>
            <td><strong>Amount</strong></td>
            <td>{$additional.heidelpay.bankData.amount|currency}</td>
        </tr>   
    </table>
{/if}

Rechnungsdokument

Developer / Entwickler Info

Textbausteine

Das heidelpay-Plugin nutzt Textbausteine gem. der Shopware-Richtlinien. Die Textbausteine sind im Verzeichnis „…/HeidelPayment/Resources/snippets/“ abgelegt und können bequem über das Shopware Backend (Einstellungen→ Textbausteine) geändert werden.

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

Innerhalb der Tabelle „s_order“ finden Sie in der Spalte „temporaryID“ die sog. „paymentId“ als Referenz zur Zahlung im heidelpay-System zur Bestellung sobald die Bestellung erfolgreich abgeschlossen wurde.

Registrierte Zahlungsdaten

Innerhalb der Tabelle „s_plugin_heidel_payment_vault“ finden Sie im Feld „type_id“ die Referenz auf die Registrierung im heidelpay-System

Anpassung von Templates und Styles

Zahlart-Templates

Die Template-Dateien für die einzelnen Zahlungsarten finden Sie im Verzeichnis „…/HeidelPayment/Resources/views/frontend/heidelpay/frames/“

Checkout / Finish

Die Template-Dateien für die checkout/finish-Seite / Bestellbestätigungsseite finden Sie im Verzeichnis „…/HeidelPayment/Resources/views/frontend/heidelpay/behaviors/“ für die Zahlungsarten, die eine Anzeige auf der checkout/finish-Seite inkludieren.

Account / Payment

Die Template-Dateien für die account/payment-Seite / Zahlartauswahl Kundenbereich finden Sie im Verzeichnis „…/HeidelPayment/Resources/views/frontend/heidelpay/account/“

PDF-Rechnungsdruck

Die Template-Dateien für die Rechnungs-Druck-Vorlagen finden Sie im Verzeichnis „…/HeidelPayment/Resources/views/frontend/heidelpay/behaviors/“ für die Zahlarten, die das Rechnungsdokument erweitern für jede Zahlungsart. Sie tragen den namen „document.tpl“

CSS allgemein

Die CSS-Dateien finden Sie im Verzeichnis „…/HeidelPayment/Resources/views/frontend/_public/src/less/“

FAQ

Es werden keine Eingabefelder für Kreditkarte / Bezahl-Daten angezeigt

Bitte leeren Sie alle Caches und kompilieren Sie die Themes erneut. Laden Sie danach die Seite neu ohne Cache, damit Ihr Browser sich die aktuellsten Daten herunterladen kann. Es kann passieren, dass das Shopware-System Änderungen erst dann übernimmt.