Handbuch Magento 2 Merchant Gateway Plugin

Handbuch Magento 2 Merchant Gateway Plugin

Magento 2
image_pdf

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.

MAge2_Install_10

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.

MAge2_Install_09

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.

  1. Öffnen Sie die betreffende Buchung im Händler-Frontend, sie befindet sich im Zustand Ready to Capture.
  2. Wählen Sie im oberen Menü den Punkt Rechnung aus und scrollen Sie dort ganz nach unten.
  3. Wählen Sie im Dropdown-Menü Online erfassen und klicken Sie abschließend auf Rechnung 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:

  1. Öffnen Sie die betreffende Buchung, sie befindet sich im Zustand Processing.
  2. Wählen Sie nun im oberen Menü den Punkt Versand aus.
  3. 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:

  1. Öffnen Sie die Bestellung und gehen dort auf den Reiter Rechnungen
  2. Wählen Sie die  bezahlte Rechnung und klicken Sie hier nun auf Gutschrift
  3. Hier kann nun eingestellt werden welche Produkte erstattet werden sollen
    (Zu erstattende Menge). Mit einem Klick auf Menge 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.

  1.  Wählen sie die jeweilige Bestellung aus und klicken dann auf „Aufheben“.
  2. 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 Standardwert Zahlungsart verbleiben.