Inhaltsverzeichnis
SYSTEMVORAUSSETZUNGEN
Das heidelpay/magento2-merchant-gateway
Plugin ist für die Magento Versionen ab 2.3 vorgesehen.
Sobald ein Update von Magento bereitgestellt wird, prüfen wir die Kompatibilität des heidelpay Magento 2 Plugins. Sollte es zu Störungen kommen, wird schnellstmöglich ein Update des Plugins von uns bereitgestellt. Dies teilen wir über Twitter mit.
@devHeidelpay
Die aktuell unterstützten PHP-Versionen können in der README.md auf GitHub und Packagist eingesehen werden.
Darüber hinaus müssen auf Ihrem System die Bedingungen erfüllt sein, welche Magento vorschreibt. Beispielhaft die Anforderungen für Magento 2.3:
https://devdocs.magento.com/guides/v2.3/install-gde/system-requirements-tech.html
Zusätzlich sollten die Anforderungen unseres SDKs beachtet werden.
Informationen hierzu finden Sie unter https://docs.heidelpay.com/docs/system-requirements f.f.
Es wird ausschließlich der Magento eigene Checkout unterstützt, eine Unterstützung für den Magento Multishipping Checkout ist nicht vorgesehen.
Fremdplugins und Fremdtemplates können die Nutzbarkeit unseres Plugins beeinflussen und sogar dazu führen, dass dieses nicht mehr funktioniert. Prüfen Sie daher vor der Nutzung und jedem Update, am besten auf einem Testsystem, ob es zu Beeinflussungen kommt.
INSTALLATION UND UPDATE
Die heidelpay Payment-Extension für Magento2 steht Ihnen in unserem GitHub Repository zum Download zur Verfügung: https://github.com/heidelpay/magento2-merchant-gateway
Wir empfehlen Ihnen jedoch die Installation des Plugins über Composer:
composer require heidelpay/magento2-merchant-gateway
Hat Composer die Abhängigkeiten und das Plugin installiert, müssen Sie es noch mit folgendem Befehl aktivieren:
php bin/magento module:enable Heidelpay_MGW --clear-static-content
Danach führen Sie bitte den setup:upgrade
Befehl über die Konsole durch, damit die Schemata des Plugins in Ihre Datenbank eingespielt werden können:
php bin/magento setup:upgrade
Mit folgenden Befehlen wird der Cache geleert und abschließende Schritte für die Plugininstallation durchgeführt: die Generation der Dependency Injection und das Deployment statischer Dateien für das Frontend.
php bin/magento cache:flush
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
Danach ist die Installation abgeschlossen und das Plugin kann im Backend konfiguriert werden.
KONFIGURATION
Wechseln Sie im Backend des Shops zu Shops → Konfiguration
und dort in die Seitennavigation unter Verkäufe → Zahlungsarten
.
Hinweis:
Die Konfiguration ist nicht auf die Standardkonfiguration
des Shops begrenzt und kann bis zur Store View unterschiedlich vorgenommen werden.
Stellen Sie hierfür einfach die Ebene, für die Sie die Konfiguration vornehmen wollen oben Links ein.
Die Allgemeinen Einstellungen des Moduls lassen sich allerdings nur in der Standardkonfiguration
vornehmen. Das heißt, pro Magentoinstallation kann aktuell nur ein Keypair verwendet werden.
Allgemeine Einstellungen
Klappen Sie den Eintrag heidelpay Merchant Gateway (MGW)
auf und starten Sie mit den allgemeinen Einstellungen, öffnen Sie hierfür den Eintrag Einstellungen
Öffentlicher und privater Schlüssel
Das Plugin wird standardmäßig mit Zugangsdaten für das heidelpay Testsystem ausgeliefert (Sandbox-Modus). Mit diesem Modus sind KEINE Geldtransaktionen möglich. Er dient ausschließlich zum Testen.
Testdaten finden Sie unter: https://docs.heidelpay.com/docs/testdata
Nutzen Sie bitte für den Live Betrieb, die Zugangsdaten, die Sie nach Vertragsabschluss von uns erhalten haben. Der erste Buchstabe der beiden Schlüssel bestimmt in welchem Modus die Transaktionen durchgeführt werden.
p = Live-Modus (production)
s = Sandbox-Modus
Webhooks
Bitte speichern Sie vor diesem Schritt die Konfiguration, damit die Registrierung mit dem richtigen Keypair geschieht.
Webhooks benachrichtigen den Shop über Änderungen des Zahlung-Status unabhängig vom Checkout-Process des Kunden. Das ist vor allem bei Zahlungsarten wichtig, bei denen es erst zu einem späteren Zeitpunkt zum eigentlichen Zahlungseingang kommt (z.B. Rechnungskauf).
Um die Webhooks zu aktivieren klicken Sie auf den Button Register webhooks
.
Unregister webhooks
, deaktiviert alle Webhooks, die für die aktuelle Shop-URL eingerichtet sind.
Nähere Informationen zu Webhooks finden Sie hier: https://docs.heidelpay.com/docs/webhook-overview
Logging und Debugging
Diese Option kann aktiviert werden, um Debug-Informationen des Moduls loggen zu lassen, diese werden in die Datei var/log/hpmgw_debug.log
geschrieben. Es werden sämtliche Anfragen an unsere Paymentschnittstelle sowie deren Antworten im JSON-Format geloggt.
Diese Option ist nur für die Fehlersuche vorgesehen und sollte für den Live-Betrieb deaktiviert werden, um Speicherplatz einzusparen.
Einstellungen der einzelnen Zahlungsart
Nun können Sie die einzelnen Zahlungsarten, konfigurieren. Klappen Sie dafür die zu konfigurierende Zahlungsart z.B. Kredit- & Debitkarten auf.
Die Einstellmöglichkeiten können von Zahlungsart zu Zahlungsart unterschiedlich sein.
Titel
Der Titel ist der Name der Zahlungsart, wie er im Shop und in E-Mails angezeigt wird. Achten Sie bei der Bearbeitung bitte darauf, dass wenn Sie mehrere Sprachen unterstützen, diesen pro Store einzurichten oder eine Übersetzung in den Sprachdateien einzutragen.
Wenn Sie in diesem Feld den Standardwert belassen erfolgt automatisch die Übersetzung ins Deutsche, sollte Ihr Shop auf deutsch eingestellt sein.
Aktiviert
Hiermit schalten Sie die jeweilige Zahlungsart in Shop aktiv, sodass Sie Ihren Kunden an der „Kasse“ angeboten wird.
Buchungsmodus
Bei den Zahlungsart Kredit- & Debitkarten sowie PayPal besteht die Möglichkeit, den Buchungsmodus zu konfigurieren. Zur Wahl stehen die Modi Debit
(direkte Buchung) und Autorisieren
(Vorautorisierung, bei der die Buchung erst mit Erstellung der Rechnung erfolgt).
Sortierreihenfolge
Hiermit legen Sie die Anzeigereihenfolge der Zahlungsarten im Shop fest.
Mindest-/Maximalwert für Gesamtbestellung
Die Zahlart ist für Ihre Kunden nur auswählbar, wenn die Bestellsumme zwischen diesen beiden Werten liegt. Um die Limitierung zu deaktivieren muss der entsprechende Wert auf 0 gesetzt werden.
Händlername
Hiermit bestimmen Sie den Händlernamen, der im Lastschriftmandat der jeweiligen Zahlart angezeigt werden soll.
Sonstiges
Verwendung von Shops ohne SSL
Das Plugin generiert für die Rückleitungen in den Shop und Webhooks URLs, damit Ihr Shop über den Status der Zahlung informiert werden kann. Diese URLs werden im sicheren Kontext forciert. Das bedeutet: Die Shop-URLs werden immer mit https://
an das Payment geschickt.
Sollte Ihr Shop nun kein SSL verwenden, kann eine Antwort vom Payment nicht an Ihren Shop weitergeleitet werden.
Wenn Sie aber z.B. auf einem Testsystem Zahlungen durchführen wollen, so können Sie die https URLs umschreiben, sodass den URLs immer http:// vorangestellt wird.
Wechseln Sie im Backend des Shops zu Shops → Konfiguration
und dort in die Seitennavigation unter Allgemein → Web
.
Klicken Sie nun auf den Reiter Basis-URLs (Gesichert)
und ändern Sie in der Einstellung Gesicherte Basis-URL
das https
zu einem http
. Das Magento 2 Backend wird Sie anschließend auffordern, den Cache zu leeren. Gehen Sie dieser Aufforderung nach.
Nun können Sie das heidelpay Plugin auch im http Kontext verwenden.
Wir empfehlen diese Maßnahme jedoch nicht im Livebetrieb und raten zu der Einbindung von SSL/HTTPS!
Anrede
Für gesicherte Zahlungsarten empfiehlt es sich die Anrede für die Kundendaten als Pflichtfeld einzustellen. Dies kann zu einer höheren Erfolgs-Quote führen.
Dies können Sie hier einstellen:
Shops → Konfiguration → Kunden → Kundenkonfiguration → Namens- und Adressoptionen → Geschlecht anzeigen
BESTELLUNGEN
Die Bestellnummer im Shop stimmt mit der auf der heidelpay Intelligence Platform (hIP) überein und kann darüber zugeordnet werden.
In der Bestellübersicht können Sie nachvollziehen, wie der Bezahl-Prozess vorangeschritten ist. Hier als Beispiel eine Kreditkarten Zahlung.
Die Bestellung wurde angelegt und danach auf den Status Ready to Capture
gesetzt, da die Bestellung als Autorisierung durchgeführt wurde. Mit dem erstellen der Rechnung wird der reservierte Betrag abgebucht und die Bestellung auf Processing
gesetzt.
Für die initialen Transaktionen werden hier UniqueId und ShortId aufgelistet.
Bitte leiten Sie diese Zwecks Zuordnung in unserem System im Supportfall an uns weiter.
Bestellstatus
Der Bestellstatus bildet den Verarbeitungsprozess der Bestellung ab. Wir haben uns hier an Magento2 orientiert und zusätzlich den Status Ready to Capture
(s.u.) ergänzt, der bei der Installation des Moduls automatisch hinzugefügt wird.
Da der Bestellstatus in Magento2 nicht dazu geeignet ist den Bezahlstatus abzubilden achten Sie darauf, ob die Rechnung zu einer Bestellung als bezahlt markiert ist um zu erfahren ob die Zahlung erfolgreich war.
Unter Verkäufe → Rechnungen
haben Sie auch die Möglichkeit nach allen Rechnungen mit den Status „offen“ zu filtern.
Hinweis:
In der Übersicht der Bestellsumme werden Teilzahlungen (z.B. bei Rechnungskauf) nicht erfasst. Diese finden Sie in Ihrem hIP-Konto.
Im Folgenden haben wir die einzelnen Status und deren Bedeutung für Sie aufgelistet.
Pending
… ist der initiale Status einer Bestellung. Kommt es beim Abgleich der Status zwischen heidelpay und Zahlungsanbieter (z.B. PayPal) zu Verzögerungen kann es vorkommen, dass Bestellungen zunächst in diesem Zustand verbleiben und die Meldung über Erfolg oder Fehler bei der Bezahlung erst später im Shop eintrifft.
Payment Review
… wird im Falle von Rechnungskauf nach Versandt der Ware verwendet. Die Bestellung bleibt in dem Status bis die Zahlung vollständig ist. Dies wird dem Shop per Webhook mitgeteilt wird. Dieser Status wird ebenfalls gesetzt wenn der Kunde zu viel bezahlt hat.
Ready to Capture
… signalisiert, dass die Autorisierung erfolgreich war und der Betrag eingezogen werden kann. Hierzu muss manuell eine Rechnung mit Online erfassen
zur entsprechenden Bestellung angelegt werden. Details hierzu finden Sie im Abschnitt Online Capture einer Autorisierung.
Processing
… zeigt an, dass der Versand der Ware eingeleitet werden kann.
Canceled
… bedeutet, dass die Bezahlung nach der Anlage der Bestellung als storniert wurde. Dies kann z.B. der Fall sein wenn eine Bestellung erst mit dem Status „Pending Payment“ angelegt wird und dann ein Drittsystem wie PayPal, Sofort etc. meldet, dass die Bezahlung nicht erfolgreich war.
Complete
… signalisiert, dass die Zahlung eingegangen ist und die Bestellung versandt wurde.
Closed
… zeigt an, dass eine Bestellung vollständig gutgeschrieben wurde.
Workflows
Online Capture einer Autorisierung
Mit einem Capture wird ein zuvor autorisierter Betrag eingezogen. Dies ist bei den Zahlungsarten Kredit- & Debitkarte sowie PayPal möglich, sofern der Buchungsmodus Autorisieren
konfiguriert ist. Derzeit wird nur ein kompletter Capture einer Bestellung unterstützt.
- Öffnen Sie die betreffende Buchung im Händler-Frontend, sie befindet sich im Zustand
Ready to Capture
.
- Wählen Sie im oberen Menü den Punkt Rechnung aus und scrollen Sie dort ganz nach unten.
- Wählen Sie im Dropdown-Menü
Online erfassen
und klicken Sie abschließend aufRechnung erstellen
Daraufhin erzeugt Magento2 eine Rechnung, die Sie nun unter Rechnungen
wiederfinden. Die Rechnung ist als „bezahlt“ markiert und die Buchung befindet sich im Zustand Processing
. Die Bestellung ist jetzt bereit für den Versand.
Im hIP finden Sie zu der Bestellung nun eine Belastung der Kreditkarte.
Finalisierung einer gesicherten Zahlungsart
Um die Versicherung einer gesicherten Zahlungsart zu aktivieren ist es nötig die Zahlung zu finalisieren. Dies erfolgt durch den Versand der Ware.
Hierzu befolgen Sie bitte folgende Schritte:
- Öffnen Sie die betreffende Buchung, sie befindet sich im Zustand
Processing
.
- Wählen Sie nun im oberen Menü den Punkt
Versand
aus. - Scrollen Sie nach unten und klicken Sie auf
Lieferschein erstellen
Magento generiert einen Lieferschein für die Buchung und versetzt sie in den Zustand Payment Review
. Im hIP finden Sie nun eine Finalisierung zu der vorherigen Reservierung.
Gutschrift einer Bestellung (online)
Die Gutschrift einer Zahlung ist nur über die Rechnung möglich. Wenn die Gutschrift direkt auf der Bestellung ausgeführt wird, findet diese nur „offline“ statt, das heißt dabei wird keine Transaktion ausgelöst und es wird kein Geld erstattet.
Um eine Gutschrift mit Erstattung durchzuführen gehen Sie bitte wie folgt vor:
- Öffnen Sie die Bestellung und gehen dort auf den Reiter
Rechnungen
- Wählen Sie die bezahlte Rechnung und klicken Sie hier nun auf
Gutschrift
- Hier kann nun eingestellt werden welche Produkte erstattet werden sollen
(Zu erstattende Menge
). Mit einem Klick aufMenge aktualisieren
berechnet Magento daraus den zu erstattenden Betrag.
4. Ein Klick auf Erstatten
löst die Gutschrift aus und schließt den Vorgang ab.
Reversal
Reversal von Restbeträgen
Wenn im Falle Rechnungskauf nur teilweise bezahlt wurde, wird dies in der Magento-Rechnung nicht angezeigt. Diese wird erst dann als bezahlt markiert, wenn die Zahlung komplett ist. Erfolgt eine Retoure über einen Teil der Bestellung, dann muss der Restbetrag über das hIP storniert werden. Dadurch wechselt der Status der Bestellung im hIP auf bezahlt
und der Shop wird informiert, woraufhin die Rechnung im Shop auf bezahlt gesetzt wird.
Nun können Sie im Shop eine Rückerstattung offline
durchführen, um die Bestellung entsprechend zu korrigieren. Da hier nicht eindeutig zugeordnet werden kann, welcher Artikel zurück geschickt wurde, passiert dies nicht automatisch.
Hinweis:
Ein Reversal von Teilbeträgen wird bei Autorisierungen derzeit nicht unterstützt.
Vollstorno
Offene reservierte Beträge werden durch Aufhebung der Bestellung automatisch freigegeben.
Hiermit wird die komplette Zahlung sowie die Bestellung storniert. Diese Funktion steht nur vor dem Versand zur Verfügung wenn zwar ein Betrag reserviert wurde aber die Rechnung noch nicht bezahlt ist.
- Wählen sie die jeweilige Bestellung aus und klicken dann auf „Aufheben“.
- Es erscheint ein Abfrage die mit „OK“ bestätigt werden kann.
Übersetzungen
Magento üblich werden die Texte und Übersetzungen in den Sprachdateien im Ordner i18n
vorgenommen, diesen finden Sie im Plugin Ordner. Die Dateien können von Ihnen angepasst werden, achten Sie vor einem Update darauf, dass Sie eine Sicherung dieser Dateien besitzen.
ZUGANGS- UND ZAHLDATEN FÜR UNSER TESTSYSTEM
Zugangsdaten für unser Testsystem finden Sie auf der Seite Testumgebung
Technische Besonderheiten
- Bis Version 1.0.1 unterstützt der Checkout nicht das updaten der Rechnungsadresse von der Zahlartenseite aus. Die Einstellung
Shops → Konfiguration → Verkäufe → Kasse → Rechnungsadresse anzeigen auf
sollte daher auf dem StandardwertZahlungsart
verbleiben.