Unzer Zahlungsarten (JTL-Shop 4)

Owned by Pascal Kleindienst, created
Last updated: Jan 11, 2024
11 min read

Einleitung

Dieses Plugin integriert die folgenden Unzer-Zahlungsarten im JTL Shop:

  • Unzer Alipay

  • Unzer EPS

  • Unzer FlexiPay Direct (entspricht Unzer Direktüberweisung)

  • Unzer FlexiPay Instalments (Hire Purchase) (entspricht Unzer Ratenkauf)

  • Unzer Giropay

  • Unzer iDEAL

  • Unzer Kreditkarte

  • Unzer PayPal

  • Unzer Prepayment (entspricht Unzer Vorkasse)

  • Unzer Przelewy24

  • Unzer Rechnung

  • Unzer Rechnung (guaranteed) (entspricht Unzer Rechnung (secured))

  • Unzer SEPA-Lastschrift (entspricht Unzer Lastschrift)

  • Unzer SEPA-Lastschrift (guaranteed) (entspricht Unzer Lastschrift (secured))

  • Unzer SOFORT

  • Unzer WeChat Pay

Features

  • viele Zahlungsarten in einem Plugin

Installation / Update

Systemvoraussetzungen

  • JTL-Shop 4.06+ und dessen Vorraussetzungen

  • PHP 7.1 bis PHP 7.4

  • Die folgenden PHP Erweiterungen

    • ext-json

    • ext-curl

Um Rundungsfehler bei der Übertragung von Fließkommazahlen an die API zu vermeiden, empfehlen wir Ihnen, den folgenden Wert in Ihrer php.ini zu setzen, der einen verbesserten Algorithmus zur Rundung solcher Zahlen auswählt.

// php.ini ; When floats & doubles are serialized store serialize_precision significant ; digits after the floating point. The default value ensures that when floats ; are decoded with unserialize, the data will remain the same. serialize_precision = -1

Weitere Voraussetzungen

Sie müssen bei Unzer registriert sein.

Plugin-Installation

Die Installation des Plugins erfolgt im Standardverfahren für JTL-Shop 4, wie es hier beschrieben ist.

Plugin-Update

Für ein Update laden Sie das Plugin wie bei einer Installation in der neuesten Version hoch (und überschreiben ggf. alle vorhandenen Plugindateien).

Gehen Sie dann in die Pluginverwaltung und betätigen Sie den Update-Button.

Konfiguration

Shop

Zahlungsarten-Konfiguration

Die Konfiguration der einzelnen Zahlungsarten erfolgt über die Standard-Verwaltung im JTL-Shop Sie finden die Zahlungsarten unter Storefront → Zahlungsarten → Übersicht.

Unzer FlexiPay Instalment (Hire Purchase)

Option

Bedeutung

Option

Bedeutung

Effektiver Zinssatz (in %)

Gibt den effektiven Zinssatz der monatlichen Ratenzahlungen an. Der Wert ist an Ihre Händlerkonfiguration gebunden.

Beispiel: 5.99

Versandarten zuweisen

Weisen Sie die Zahlungsarten den gewünschten Versandarten/Ländern unter Storefront → Kaufabwicklung → Versandarten zu. Beachten Sie, dass nicht jede vom Plugin angebotene Zahlungsart in jedem Land zur Verfügung steht.

Plugin Konfiguration

Das Plugin-Backend erreichen Sie über Plugins → Solution 360 Unzer. Gehen Sie im Plugin-Backend auf den Reiter “Einstellungen”, um die allgemeine Konfiguration einzusehen oder zu ändern.

Option

Bedeutung

Option

Bedeutung

Privater Schlüssel (Private Key)

Geben Sie hier den privaten API Schlüssel ein, den Sie von Unzer erhalten haben.

Öffentlicher Schlüssel (Public Key)

Geben Sie hier den öffentlichen API Schlüssel ein, den Sie von Unzer erhalten haben.

Händler ID für das Insight Portal

Geben Sie hier Ihre Händler ID für das Insight Portal an. Diese wird benötigt, um die Bestellungen im Plugin-Backend zum Insight Portal zu verlinken.

Sie können Ihre Händler ID finden, wenn Sie das Insight Portal aufrufen und in der URL nachsehen: https://insights.unzer.com/merchant/{Händler-ID}/dashboard

Schriftgröße

Schriftgröße für das Kreditkarten-Formular

Schriftfarbe

Schriftfarbe für das Kreditkarten-Formular

Schriftart

Schriftart für das Kreditkarten-Formular

Selektor für den Submit-Button im Zahlungszwischenschritt

Der Selektor für den Submit-Button im Zahlungszwischenschritt.

PQ-Selector für "Zahlungsart ändern" Button im Zwischenschritt

Der PHP-Query-Selektor für das Einhängen des "Zahlungsart ändern"-Buttons auf der Zahlungszwischenschritt-Seite.

PQ-Einfügemethode für "Zahlungsart ändern" Button im Zwischenschritt

Die PHP-Query-Einfügemethode für das Einhängen des "Zahlungsart ändern"-Buttons auf der Zahlungszwischenschritt-Seite.

PQ-Selector für Fehlermeldungen

Der PHP-Query-Selektor für das Einhängen von Plugin-Fehlermeldungen auf der Versandart/Zahlungsart-Auswahl etc.

PQ-Einfügemethode für Fehlermeldungen

Die PHP-Query-Einfügemethode für das Einhängen von Plugin-Fehlermeldungen auf der Versandart/Zahlungsart-Auswahl.

PQ-Selector für Zahlungsart-Extras auf der "Bestellung überprüfen"-Seite

Der PHP-Query-Selektor für das Einhängen von Zahlungsart-Extras auf der "Bestellung überprüfen"-Seite.

PQ-Einfügemethode für "Bestellung überprüfen"-Seite

Die PHP-Query-Einfügemethode für das Einhängen von Zahlungsart-Extras auf der "Bestellung überprüfen"-Seite.

Webhooks neu registrieren

Mit diesem Button können die Webhooks URLs neu registriert werden. Dies ist zum Beispiel notwendig, falls sich Ihre Shop-Url geändert hat.

JTL-Wawi

Zahlungsarten einrichten

Öffnen Sie die Zahlungsartenverwaltung über Zahlungen → Zahlungsarten.

Legen Sie die Zahlungsarten, die Sie nutzen, mit folgenden Namen an:

  • Alipay

  • Unzer Direktüberweisung

  • EPS

  • Giropay

  • iDEAL

  • Kreditkarte

  • Unzer Lastschrift

  • PayPal

  • Przelewy24

  • Unzer Ratenkauf

  • Unzer Rechnung

  • SOFORT

  • Unzer Vorkasse

  • WeChat Pay

Beachten Sie, dass die Zahlungsarten dem Anzeigenamen im JTL-Shop entsprechenden müssen. Falls Sie also den angezeigten Namen ändern auch auch für andere Sprachen übersetzen, müssen Sie dies hier ebenfalls anpassen.

Markieren Sie bei den folgenden Zahlungsarten “Auslieferung vor Zahlungseingang möglich”:

  • Unzer Rechnung

Dies ist notwendig, weil die Aktivierung der Zahlung bei diesen Zahlungsarten erst beim Versand erfolgt.

Rechnungsdruckvorlage editieren

Dieser Schritt ist absolut notwendig für Rechnungen, da sonst Zahlungen des Kunden nicht zugeordnet werden können und/oder auf falschen Konten erfolgen! Die zu verwendende Bankverbindung und der Verwendungszweck, werden vom Plugin als Zahlungsinfo und Auftragsattribute übermittelt.

Fügen Sie bei Rechnungen folgenden DotLiquid Code für die Rechnungsdruckvolage ein.

Ihre Daten für die Überweisung: Empfänger: {{ Vorgang.Attribute | Replace: '^.*unzer_account_holder=(.*?)(\||$).*','$1' }} IBAN: {{ Vorgang.Attribute | Replace: '^.*unzer_iban=(.*?)(\||$).*','$1' }} BIC: {{ Vorgang.Attribute | Replace: '^.*unzer_bic=(.*?)(\||$).*','$1' }} Betrag: {{ Vorgang.Gesamtbetrag | Nummer: 'N2','de-de' }} {{Vorgang.Währung}} Verwendungszweck: {{ Vorgang.Attribute | Replace: '^.*unzer_transaction_descriptor=(.*?)(\||$).*','$1' }} Bitte beachten: Geben Sie bitte nur den Verwendungszweck an, andernfalls können wir Ihre Zahlung nicht zuordnen. Die Rechnung ist bei Erhalt und ohne Abzug fällig. Bitte überweisen Sie den Gesamtbetrag schuldbefreiend auf das oben genannte Konto.

 

Sollten Sie bereits die Vorlagen 2.0 der Wawi im Einsatz haben, so fügen Sie folgenden Inhalt in Ihre Rechnungsvorlage ein:

"Ihre Daten für die Überweisung:" + "¶ "+ "Empfänger: " + JTL_GetReportAttribute("unzer_account_holder",Report.InternalId) + "¶ "+ "IBAN: "+ JTL_GetReportAttribute("unzer_iban",Report.InternalId) + "¶ "+ "BIC: "+ JTL_GetReportAttribute("unzer_bic",Report.InternalId) + "¶ "+ "Betrag: "+ LocCurrL$(Report.OpenGrossPrice, JTL_GetCulture(Report.CountryISO, Report.LanguageISO, Report.CurrencyISO)) + "¶ "+ "Verwendungszweck: " + JTL_GetReportAttribute("unzer_transaction_descriptor",Report.InternalId) + "¶ "+ "Bitte beachten: Geben Sie bitte nur den Verwendungszweck an, andernfalls können wir Ihre Zahlung nicht zuordnen. Die Rechnung ist bei Erhalt und ohne Abzug fällig. Bitte überweisen Sie den Gesamtbetrag schuldbefreiend auf das oben genannte Konto."

 

Auftragsattribute anlegen

Das Plugin schreibt in die folgenden Attribute wichtige Informationen (sofern vorhanden) zu Transkationen:

  • unzer_iban

    • Die IBAN des Unzer Kontos, an welches der Kunde sein Geld überweisen muss.

  • unzer_bic

    • Die BIC des Unzer Kontos, an welches der Kunde sein Geld überweisen muss.

  • unzer_transaction_descriptor

    • Der Verwendungszweck von Unzer, den der Kunde auf Überweisungen angeben muss.

  • unzer_account_holder

    • Der Kontoinhaber des Unzer Kontos

  • unzer_short_id

    • Technische ID der Transaktion von Unzer, welche im Insight Portal genutzt werden kann, um die Transaktion zu finden

  • unzer_payment_id

    • Zahlungs ID von Unzer

  • unzer_payment_type_id

    • ID der Bezahlmethode

  • unzer_rate_pdf_link

    • Link zur PDF mit den Informationen zum Ratenplan für den Kunden.

  • unzer_rate_total_amount

    • Gesamtbetrag der Ratenzahlung

  • unzer_rate_total_purchase_amount

    • Bestellbetrag der Ratenzahlung

  • unzer_rate_total_interest_amount

    • Zinsbetrag der Ratenzahlung

  • unzer_card_number

    • Kartennummer (teilanonymisiert)

  • unzer_card_expiry_date

    • Ablaufdatum der Kreditkarte

  • unzer_card_cvc

    • CVC (anonymisiert)

  • unzer_card_type

    • Typ der Verwendeten Kreditkarte (z.B. MASTER, oder VISA)

Legen Sie diese Attribute unter Verkauf → Auftragsattribute an, damit Sie sie auch an Aufträgen einsehen können. In neueren WaWi Versionen kann die Auftragsattributverwaltung geöffnet werden, wenn man eine Bestellung öffnet. Dort können über den Button “Attribute …” → Attribute definieren → “Anlegen …” neue Attribute angelegt werden

 

Workflow anlegen

Die Zahlungsarten Unzer Rechnung und Unzer Ratenkauf benötigen die Rechnungsnummer, um die Bestellung beim Versand zu finalisieren. Die JTL-Wawi übermittelt die Rechnungsnummer allerdings nicht im Onlineshop-Abgleich. Daher wird mittels eines Workflows die Rechnungsnummer bei der Erstellung der Rechnung an das Plugin übermittelt.

Öffnen Sie die Workflowverwaltung unter Admin → JTL-Workflows. Legen Sie einen neuen Workflow für das auslösende Ereignis “Rechnungen Erstellt” an.

JTL Wawi Workflow

Workflow Bedingungen

Der Workflow muss die folgenden Bedingungen haben:

Option

Vergleich

Wert

Option

Vergleich

Wert

Auftrag.Zahlungsart.Name

gleich

Unzer Rechnung

Auftrag.Zahlungsart.Name

gleich

Unzer Ratenkauf

Stellen Sie sicher, dass bei Bedingungen die Option “Eine Bedingung erfüllt” aktiviert ist.

Workflow Aktionen

Legen Sie eine neue “Web-Request (POST)” Aktion für den Workflow mit den folgenden Optionen an:

Option

Wert

Option

Wert

Url

https://{IHRE_SHOP_URL}/unzer-sync-workflow

Parameter

attrs={{ Vorgang.Auftrag.Attribute }}&invoice_id={{ Vorgang.Rechnungsnummer }}&invoice_date={{ Datum.Gestartet }}

Betrieb

Dieser Bereich beschreibt den Umgang mit dem Plugin im Alltag.

Begriffsklärung / Glossar

Shop

Im Plugin-Backend können Sie im Reiter “Übersicht” die Bestellungen einsehen, die mit Unzer bezahlt wurden, sowie deren Status aus Sicht des Plugins.

Die Übersicht ist lediglich rein informativ - um manuell in Unzer Zahlungen einzugreifen, nutzen Sie bitte das Insight Portal.

ERP-System

Standardablauf

Das Plugin setzt den Zahlungseingang für die JTL-Wawi, sobald es von Unzer die Rückmeldung erhält, dass die Bestellung bezahlt worden ist. Mit Unzer bezahlte Bestellungen sollten also nur versendet werden, sofern diese im Status bezahlt sind.

Rechnung

Die Zahlungsart Rechnung ist hier die Ausnahme, da die Zahlung erst beim Versand finalisiert wird. Diese Bestellungen müssen Sie also versenden, bevor der Zahlungseingang in der JTL-Wawi gesetzt ist.

Stornos

Stornos von Bestellungen vor dem Versand werden vom Plugin automatisch erkannt und gegen Unzer weitergeleitet.

Retouren

JTL-Shop (und damit auch das Plugin) ist technisch nicht in der Lage, Retouren automatisch zu behandeln, da diese Information nicht im Shop ankommt.

Bei Retouren müssen Sie den Kunden das Geld daher auf anderem Weg zurückzahlen.

Individualisierung

Bestimmte Teile des Plugins lassen sich individualisieren.

Beachten Sie, dass Sie individualisierte Dateien bei Plugin-Updates jeweils in die aktuellste Pluginversion (includes/plugins/s360_unzer_shop4/version/<nummer>) kopieren müssen, damit die Änderungen greifen.

Templates

Das Template der Ratenplanzusammenfassung auf der Bestellübersichtsseite lässt sich ersetzen, indem Sie die Datei in frontend/templates/hire_purchase_direct_debit_custom.tpl anlegen. Diese ersetzt dann die im Plugin vorhandene Datei.

Troubleshooting

Sollten Sie Probleme mit dem Plugin beobachten, prüfen Sie zunächst die Logs und wenden Sie sich ggf. an unseren Support oder Ihren Service-Partner, wenn Sie das Problem nicht selbständig lösen können.

Je mehr Informationen Sie dem Support bei einem Problem geben können, desto eher sind wir in der Lage, Ihnen zu helfen. Nicht reproduzierbare Probleme sind dagegen auch nur schwer zu analysieren.

Logs prüfen

Um herauszufinden, wo ein Problem liegt, helfen Ihnen und uns die Logs. Je nach Fehlerbild ist eines der folgenden 3 Logs dafür mehr oder weniger relevant.

Browser-Log

Das Browser-Log ist meist relevant, wenn irgendwas im Frontend des Shops sich merkwürdig verhält oder nicht reagiert. (Beispiel: Sie klicken einen Button und augenscheinlich passiert gar nichts.)

Das Browser-Log sehen Sie, wenn Sie im Browser F12 drücken und dort dann auf Konsole (oder Console) wechseln.

Shop-Log

Das Shop-Log ist immer dann interessant, wenn im Frontend unerwartete Fehlermeldungen ausgegeben werden oder das Plugin zwar auf Eingaben im Frontend reagiert, aber nicht das Ergebnis liefert, was erwartet wurde. Manchmal ergibt sich auch durch das Browser-Log, dass die Informationen eher im Shop-Log zu suchen sind.

Das Shop-Log finden Sie im JTL-Adminbereich unter System → Wartung → Log.

Webserver-Log

Das Webserver-Log wird dann relevant, wenn Sie irgendwo auf einen Error 500 (= weiße Seite) stoßen.

Das Webserver-Log kann Ihnen Ihr Hoster zur Verfügung stellen.

FAQ

Warum werden keine Rechnungen finalisiert?

Dies ist meistens der Fall wenn der Workflow zum übertragen der Rechnungsnummer nicht bzw. nicht richtig angelegt wurde. Sollten sich die folgenden Nachrichten im Shop-Log wiederfinden, so ist der Parameter der Workflow Aktion nicht korrekt angelegt wurden

Hinweis-Log

[Unzer] Called SyncWorkflowController with the following data: Array ( attrs: {{ Vorgang.Auftrag.Attribute }} invoice_id: {{ Vorgang.Rechnungsnummer }} invoice_date: {{ Datum.Gestartet }} )

Fehler-Log

[Unzer] Plugins360_unzer_shop4ControllersSyncWorkflowController: Missing parameter payment_id or invoice_id Array ( {{Vorgang_Auftrag_Attribute}}: )

 

Warum erhalte ich die Nachricht, dass sich die URL des Webhook oder des Workflows geändert hat?

Durch ein Update des Plugins kann es, aufgrund eines Fehlers im JTL Shop, vorkommen, dass die URLs der eigenen Seiten des Plugins (Unzer WaWi Workflow-Verarbeitung und Unzer Webhook-Verarbeitung) geändert haben. Dies hat zur Folge, dass diese Seiten im Shop nicht mehr erreichbar sind. Dadurch ist die korrekte Funktionsweise des Plugins nicht mehr gegeben.

 

Um diesen Fehler zu beheben, müssen im Adminbereich unter “Inhalte” > “Seiten” in der Linkgruppe “hidden” die Seiten Unzer WaWi Workflow-Verarbeitung und Unzer Webhook-Verarbeitung wie folgt geändert werden.

 

Der “Name für Suchmaschinen” der Standardsprache muss zuerst mit einer “-1” gespeichert werden (also unzer-sync-workflow-1 bzw. unzer-webhook-1). Danach muss der "Name für Suchmaschinen" der Standardsprache wieder ohne eine “-1” gespeichert werden (also unzer-sync-workflow bzw. unzer-webhook).

Wenn diese Schritte korrekt ausgeführt wurden, sollte die Nachricht im Adminbereich des Plugins verschwunden sein und das Plugin wieder richtig funktionieren!

Changelog

v1.15 (Januar 2024)

  • Changed: Formatierung Metadaten bei API Request

v1.13 (Juli 2022)

  • Added: Firmeninfo zum Kundenobjekt hinzugefügt

  • Added: Überprüfung und Benachrichtigung hinzufügen, falls sich die Frontend-URLs aufgrund von JTL-/Plugin-Updates geändert haben und wie man sie korriegiert

  • Added: Hinzufügen des MwSt.-Betrags zum Warenkorb Objekt

  • Change: Unzer SDK Version auf 1.1.4.2 aktualisiert

  • Fixed: Problem mit Ratenzahlungen behoben, die falsche/temporäre Bestellnummern an Unzer übermitteln

  • Fixed: Behebung eines unbehandelten Fehlers beim Abrufen von Erstattungen im Backend

v1.12 (März 2022)

  • Added: Hinzufügen von Mindestangaben zum Kunden (Name und E-Mail) zu allen Zahlungen

  • Change: Short-ID als Transaktions-ID im Zahlungsverlauf verwenden (WaWi)

  • Fixed: Fehlerbehandlung hinzugefügt, um Probleme im Frontend zu vermeiden, wenn die API nicht aufrufbar ist (z.B. fehlende Schlüssel)

  • Fixed: Behebung des Problems, dass -0.0 in der Unzer-API als negativ interpretiert wird

  • Fixed: Behebung einer möglichen Fehlanpassung der Bestell-IDs zwischen dem Unzer Insight Portal und dem Shop

v1.11 (November 2021)

  • Added: JTL WaWi 1.6 Kompatibilität

  • Fixed: Schreibfehler in SQL Abfrage

  • Fixed: Anzeigefehler bei Stornierungen die die gleiche ID haben, obwohl sie in verschiedenen Transaktionen sind

  • Fixed: Problem bei der Validierung, wodurch Gutscheine auf der “Zusammenfassung”-Seite im Checkout nicht eingelöst werden können

v1.10 (Juli 2021)

  • Offizielles Release

v1.08 (Juli 2021)

  • Change: "Unzer Rechnungskauf" deaktiviert, da diese mit "Unzer Rechnung (secured)" zusammengelegt wurde

  • Change: Zahlungsinformationen für "Vorkasse" und "Rechnung" auf der Bestellabschluss-Seite hinzugefügt

  • Bugfix: Validierung im B2B Kundenformular funktioniert nicht und blockiert damit den “Weiter”-Button

v1.07 (Juni 2021)

  • Change: Zahlungsartennamen angepasst

  • Bugfix: Problem beim stornieren von Ratenkäufen

  • Bugfix: Transaktionen die bereits Geld eingezogen haben, können nicht storniert werden

  • Bugfix: Pending Charges werden nicht storniert

  • Bugfix: Probleme mit dem B2B Kundenformular

v1.06 (Mai 2021)

  • Bugfix: Konflikt zwischen Standard EVO styles und unzerUI form Labels (alles uppercase)

  • Bugfix: Firma vorausfüllen bei B2B Customer Formular

  • Bugfix: Beim erfolgreichen Verarbeiten einer Charge wird ein Eintrag ins Error-Log geschrieben

  • Bugfix: Im Webhook übergebene Charge enthält nicht immer alle nötigen Informationen was zu einer falschen oder gar keinen Verarbeitung der Zahlungseingänge führt

  • Bugfix: Standard PQ Selector für Easytemplate erweitert

  • Change: “guaranteed” in “secured” umbenannt wo möglich

  • Change: Vor- und Nachname bei B2B Customer Formular werden nicht mehr vorausgefüllt

  • Change: Beim registrieren der Webhooks werden bestehende Webhooks nicht vorher gelöscht

  • Change: Metadaten hinzugefügt

v1.05 (April 2021)

  • Bugfix: CVC Feld bei Kreditkarten im Firefox sichtbar, wenn eine Schriftart konfiguriert ist.

  • Bugfix: Falsche Warenkorb Berechnung bei “Ratenzahlung”, wenn Gutscheine benutzt werden.

v1.04 (April 2021)

  • Bugfix: Fehlenden PQ Selector für Fehlermeldungen auf der Bestellstatus Seite nach Bestellabschluss hinzugefügt.

v1.03 (März 2021)

  • Bugfix: API Fehler wenn Kupons genutzt werden bei Zahlungsarten die den Warenkorb übermitteln

  • Bugfix: Fehlendes Error Handling bei Zahlungsart-Zusatzschritt

  • Bugfix: E-Mail Adresse beim Customer-Object hinzugefügt (Pflicht bei Gast-Bestellungen)

  • Bugfix: B2B Kunden Daten werden nicht richtig abgefragt / an Unzer übermittelt

  • Bugfix: Stornieren von Bestellungen wird bei "Rechnung" nicht an Unzer übermittelt

v1.02 (März 2021)

  • Bugfix: Problem mit HTML Entities in Adressdaten erzeugt “unterschiedliche” Adressen (zB &uuml; != ü)

  • Bugfix: Sonderzeichen in der basketReferenceId entfernen

v1.01 (Februar 2021)

  • Bugfix: Plugin Session nach Fehler löschen, um Fehler durch alte Session Daten zu vermeiden.

  • Bugfix: Ungültige Zeichen (Leerzeichen) in der basketReferenceId ersetzen

v1.00 (Oktober 2020)

  • Initiales Release (Beta)

Support und Kontakt

siehe Support und Kontakt