Handbuch Magento 2 Unzer_PAPI Modul

Handbuch Magento 2 Unzer_PAPI Modul

image_pdf

SYSTEMVORAUSSETZUNGEN

Das unzerdev/magento2 Plugin ist für die Magento Versionen ab 2.3 vorgesehen.

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


Migration von einem bestehenen Plugins

Achtung: Wichtig für Bestandskunden bzw. Anwender, die bereits das bestehende Plugin im Einsatz haben (heidelpay/magento2 oder heidelpay/magento2-merchant-gateway).

Für Anwender, die bereits das bestehende Plugin verwenden, ist es notwendig für eine Übergangszeit beide Shop-Plugins parallel im Shop einzubinden bzw. konfiguriert und aktiv zu lassen. Das neue Plugin kann nicht auf alte Bestellungen/Transaktionen referenzieren.

Daher sollten Sie vorzugsweise im neuen Plugin die benötigten Zahlungsarten aktivieren und im alten Plugin die entsprechenden Zahlungsarten deaktivieren.
Das alte Plugin muss für die alten darüber getätigten Bestellungen übergangsweise weiterhin konfiguriert und aktiviert sein, um die Zahlungs-Verarbeitung von bestehenden Bestellungen weiter zu gewährleisten (z.B. bei einer Retoure / Refund).

INSTALLATION

Die Unzer Payment-Extension für Magento2 steht Ihnen in unserem GitHub Repository zum Download zur Verfügung: https://github.com/unzer/magento2

Wir empfehlen Ihnen jedoch die Installation des Plugins über Composer:

composer require unzerdev/magento2

Hat Composer die Abhängigkeiten und das Plugin installiert, müssen Sie es noch mit folgendem Befehl aktivieren:

php bin/magento module:enable Unzer_PAPI --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.

Allgemeine Einstellungen

Klappen Sie den Eintrag Unzer Payment (PAPI) auf und starten Sie mit den allgemeinen Einstellungen, öffnen Sie hierfür den Eintrag Einstellungen

Öffentlicher und privater Schlüssel

Sie benötigen einen Unzer-Public-Key, sowie einen Unzer-Private-Key (Anforderung über support@unzer.com)

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

Testdaten finden Sie unter: https://docs.unzer.com/docs/testdata

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.unzer.com/get-started/basics/notifications/

Logging und Debugging

Diese Option kann aktiviert werden, um Debug-Informationen des Moduls loggen zu lassen, diese werden in die Datei var/log/unzer_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. „Kreditkarte / Debitkarte“ 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 Unzer Plugin auch im http Kontext verwenden.
Wir empfehlen diese Maßnahme jedoch nicht im Livebetrieb und raten zu der Einbindung von SSL/HTTPS!


BESTELLUNGEN

Die Bestellnummer im Shop stimmt mit der auf der Unzer Insights ü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 Insights-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 Unzer 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 Versand der Ware verwendet. Die Bestellung bleibt in dem Status bis die Zahlung vollständig ist. Dies wird dem Shop per Webhook mitgeteilt. 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 Insights finden Sie zu der Bestellung nun eine Belastung der Kreditkarte.

Workflow – Rechnungskauf gesichert

Die Zahlart Rechnungskauf gesichert unterscheidet sich in einigen Punkten von den meisten anderen Zahlungsarten. Die wichtigsten Unterschiede sind beim Versand und bei Gutschriften, wie in den folgenden Abschnitten beschrieben.

Versand für Rechnungskauf gesichert

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 Complete. Die bestellung wird übergangsweise im Status Payment Review gesetzt bis der Status vom Webhook aktuallisiert wird. Im Insights finden Sie nun eine Finalisierung zu der vorherigen Reservierung.

Gutschrift bei Rechnungskauf gesicherten

Die Shop-Rechnung wird nach erfolgreichem Versand auf bezahlt gesetzt, da die Zahlung ab diesem Zeitpunkt durch Unzer sichergestellt ist.

Eine Gutschrift führt dann zu einer Stornierung, wenn der Kunde noch nicht gezahlt hat.
Hat der Kunde bereits den vollen Betrag bezahlt, erfolgt eine Rückerstattung wie gewohnt. Auf diese Weise ist auch eine Teil-Storno möglich.

Achtung! Bei einer Teil-Gutschrift über das Shop-Backend priorisiert das Plugin die Freigabe offener Beträge gegenüber der Erstattung von bezahlten Beträgen.

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 Insights storniert werden. Dadurch wechselt der Status der Bestellung im Insights 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.