Systemvoraussetzungen und Hinweise

Die Systemvoraussetzungen des Plugins beschränken sich im Wesentlichen auf dieselben Systemvoraussetzungen, die der JTL-Shop ab Version 5 mitbringt.

Systemvoraussetzungen:

• JTL Shop 5.0.0
• JTL Warenwirtschaft ab V.1.0
• PHP-Version mindestens 7.2
• jQuery Version mindestens 1.12.4
• Vorhandenes Klarna Online-Konto

Einleitung

Das Plugin wurde entsprechend der Konventionen von JTL-Software entwickelt und hält sich an die Shop-Standards. Die Konfiguration des Plugins ist größtenteils innerhalb des Plugins mit hilfreichen Hinweisen versehen. Bitte nehmen Sie sich beim Einstellen des Plugins kurz die Zeit, die Hinweise zu lesen.

Installation

Das Plugin installieren Sie wie jedes andere JTL-Shop 5 Plugin. Es werden keine besonderen Schritte benötigt.

Konfiguration (Shop)

Nach der Installation kann das Plugin konfiguriert werden. Die Konfiguration erfolgt wie gewohnt über den Admin-Bereich, welcher entweder direkt über die Sidebar oder über in der Plugin-Verwaltung über den "Einstellungen"-Button aufgerufen werden kann.

Das Plugin wird mit einer sinnvollen Standardkonfiguration ausgeliefert und weist auf wichtige oder noch fehlende Einstellungen hin, wenn das Plugin-Backend aufgerufen wird. Zu einer minimalen Konfiguration gehört:

• Eintragen der Klarna Zugangsdaten (Händler-ID und Passwort)
• Zuordnung der Klarna Zahlungsarten zu mindestens einer Versandart
• Zur Live-Schaltung: Den Sandbox-Modus deaktivieren

Zahlungsart konfigurieren (optional)

Neben der Konfiguration im Plugin-Backend können Standard-Einstellungen für die Zahlungsarten vorgenommen werden. Die Klarna-Zahlungsarten befinden sich im Admin-Bereich des Shops unter dem Menüpunkt "Zahlungsarten".

Angezeigter Name

Diese Werte haben keine Auswirkung auf die Klarna-Zahlunsart-Darstellung, da hier die von der Klarna-API zurückgegebenen Namen genutzt werden.

Bild-URL

Die Klarna-Zahlungsart-Logos werden ebenfalls nicht hier konfiguriert, sondern direkt im Template vom Klarna-Plugin eingebunden. Lassen Sie dieses Feld also leer.

Name der Gebühr

Name der jweiligen Rechnungsgebühr im Warenkorb des Kunden.

Erlaubte Kundengruppen

Kundengruppen für die die Zahlungsart zur Verfügung stehen soll. Es können mehrere Kundengruppen ausgewählt werden, wenn STRG gedrückt wird.

Sortiernummer

Anpassen der Sortierung der Zahlungsarten in der Auswahl.

Hinweistext

Die Hinweistexte hier haben keine Auswirkung auf die Darstellung der Zahlungsart, da hier das von Klarna vorgegebene Template gerendert wird.

E-Mail: Bestätigung der Zahlung / Storno der Bestellung

Hier kann ausgewählt werden, welche E-Mails versendet werden sollen.

Zahlung vor Bestellabschluss

Dies ist eine technisch notwendige Einstellung – lassen Sie den Wert auf "Ja" stehen.

Anzahl Bestellungen nötig

Hier kann angeben werden, ab wie vielen Bestellungen diese Zahlungsart dem Kunden zur Verfügung steht.

Mindestbestellwert

Mindestbestellwert der erreicht sein muss, damit die Zahlungsart verfügbar ist.

Maximaler Bestellwert

Gibt an, bis zu welchem Maximalwert die Zahlungsart zur Verfügung stehen soll.

Versandarten zuordnen

Im Admin-Bereich des Shops unter dem Menüpunkt "Versand -> Versandarten" können die Klarna-Zahlungsarten den verschiedenen Versandarten hinzugefügt werden, bei denen Sie zur Verfügung stehen sollen.

Zugangsdaten konfigurieren

Die Klarna API-Zugangsdaten, die zur Verbindung des Shops mit Klarna benötigt werden, finden sich im Plugin-Backend im Tab "Einstellungen".

Einstellungen vornehmen

Die Einstellungen des Plugin sind im Plugin-Backend unter dem Tab "Einstellungen" erreichbar.

Einstellungen

Generelle Einstellung zum Verhalten des Plugins.

Sandbox Modus

Umschalten zwischen "TEST" und "LIVE" Modus. Im Testmodus können keine echten Bestellungen/Zahlungen durchgeführt werden!

Händler-ID

Die Händler-ID, welche Klarna vergeben hat.

Passwort

Das Passwort bzw. Shared Secret zur vergebenen Händler-ID.

Eskalations-Mail-Adresse

An die hier eingetragene E-Mail-Adresse sendet das Plugin Warn- und Hinweismeldungen, wenn ein Eingreifen erforderlich ist.

Bestellbestätigungsformular

Der phpQuery-Selektor für das Formular auf der Bestellbestätigungsseite. phpQuery ist eine serverseitige Implementierung von jQuery-Funktionen und mithilfe dieser Selektoren können Sie die Buttons unabhängig vom eingesetzten Template und je nach Wunsch platzieren.

Erfassung von Versandkosten und Rabattcodes/Guthaben

Mit dieser Einstellung kann angegeben werden zu welchem Zeitpunkt die Versandkosten und benutzte Rabattcodes/Guthaben bei Klarna aktiviert werden sollen. Diese Einstellung ist nur für Bestellungen, welche teilversandt werden, nötigt.

Automatische Erfassung aktivieren

Hier kann die automatische Aktivierung bei Bedarf aktiviert werden. Wenn Sie diese Optionen aktiviert ist, werden die Bestellungen automatisch bei Klarna aktiviert und als "bezahlt" markiert! Dies gilt nur für Bestellungen, welche nur aus Digitalen Gütern / Download-Artikeln bestehen!

Extra Merchant Data (EMD)

Auswahl an Zusatzdaten, welche an Klarna übermittelt werden sollen.

Customer Account Info

Gibt an, ob die Kundokonto-Daten an Klarna übermittelt werden sollen oder nicht.

Purchase History Full

Gibt an, ob die Einkaufshistorie des Kunden an Klarna übermittelt werden sollen oder nicht.

Generisches EMD-Feld zulassen

Gibt an, ob generische EMD-Daten, individuell angepasst an den Shop, mit an Klarna gesenden werden sollen. Dazu muss diese Option aktiviert sein.

Außerdem ist eine emd_custom.php im Plugin-Verzeichnis notwendig. In dieser Datei muss eine Funktion mit folgender Signatur definiert werden addCustomMerchantData(array &$data, \JTL\Customer\Customer $customer, ?\JTL\Checkout\Bestellung $order, \JTL\Cart\Cart $cart, ?string $method).

Diese Methode bekommt eine Referenz des $data-Objekts worauf direkt gearbeitet werden kann, um Daten hinzuzufügen oder anzupassen. Außerdem bekommt die Methode den Kunden, die Bestellung (sofern vorhanden), den Warenkorb, und sofern vorhanden die verwendete Klarna-Methode ("pay_now", "direct_bank_transfer", "card, "pay_later", oder "slice_it") als Parameter übergeben. Der Rückgabewert der Methode wird nicht ausgewertet.

Eine beispielhafte Implementation der emd_custom.php könnte wie folgt aussehen:

<?php declare(strict_types = 1);

use JTL\Customer\Customer;
use JTL\Cart\Cart;
use JTL\Checkout\Bestellung;

function addCustomMerchantData(array &$data, Customer $customer, ?Bestellung $order, Cart $cart, ?string $method) : void
{
    // Do something with $data
    $data['foo'] = 'bar';
}

Weitere Informationen zu den unterstützen Feldern findet sich in der Klarna API Dokumentation: https://developers.klarna.com/api/#payments-api__create-a-new-orderattachment__body

On-Site Messaging

phpQuery Selektoren zum Platzieren der On-Site Messaging Placements. phpQuery ist eine serverseitige Implementierung von jQuery-Funktionen und mithilfe dieser Selektoren können Sie die Placements unabhängig vom eingesetzten Template und je nach Wunsch platzieren.

PQ-Selektor Artikelpreis

Der phpQuery-Selektor des Artikelpreises auf der Artikelseite. 

PQ-Selektor Warenkorbpreis

Der phpQuery-Selektor der Gesamtwarensumme auf der Warenkorbseite.

PQ-Selektor Homepage

Der phpQuery-Selektor für die Startseite.

Widget-Anpassungen

Aussehen des Klarna Widgets anpassen.

Rahmen-Farbe

Farbe der Rahmen im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Rahmen-Farbe (ausgewählt)

Farbe der Rahmen von ausgewählten Elementen im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Button-Farbe

Farbe des Buttons im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Buttontext-Farbe

Farbe der Button-Texte im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Checkbox-Farbe

Farbe der Checkboxen im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Checkbox-Häkchen-Farbe

Farbe der Checkbox-Häkchen im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Detail-Infos-Farbe

Farbe der Detail-Infos im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Kopfbereich-Farbe

Farbe des Kopfbereichs im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Link-Farbe

Farbe der Links im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Text-Farbe

Farbe des Texts im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Text-Farbe (sekundär)

Farbe des sekundären Texts im Widget als CSS Hex-Farbwert (z.B. #FF9900)

Rahmen-Radius

Radius des Rahmens im Widget (z.B. 8px oder 5%)

Konfiguration (WaWi)

Zahlungsart einrichten

In der JTL WaWi muss eine Zahlungsart für "Klarna Rechnug", "Klarna Sofort bezahlen", und "Klarna Ratenzahlung" angelegt werden. Die Zahlungsarten können in der WaWi unter "Zahlungen -> Zahlungsarten" angelegt werden.

Die weiteren Einstellungen hängen davon ab, wie die Zahlungserfassung im Plugin konfiguriert wurde.

Mit automatischer Erfassung (Auto-Capture aktiviert)

Sofern die "automatische Erfassung" in den Plugin Einstellungen aktiviert wurde, sollte der Haken "Auslieferung vor Zahlungseingang möglich" deaktiviert werden, da die Bestellungen immer als bezahlt im Shop ankommen sollten.

Nicht bezahlte Bestellungen deuten in dem Fall darauf hin, dass eine nicht-autorisierte Bestellung vom Shop in die Wawi gelangt ist. Solche Bestellungen sollten nicht ausgeliefert werden, da dafür keine Zahlung garantiert ist!

Ohne automatische Erfassung (Auto-Capture deaktiviert)

Sofern die "automatische Erfassung" in den Plugin Einstellungen deaktiviert wurde, sollte der Haken "Auslieferung vor Zahlungseingang möglich" aktiviert werden, da alle Bestellungen zunächst als nicht bezahlt in der Wawi ankommen. Erst nach dem Versand bzw. Teilversand der Bestellung wird der eigentliche Zahlungseinzug gegen Klarna aktiviert.

Betrieb

Standardablauf

Zum besseren Verständnis ist der Ablauf/Lebenszyklus einer mit Klarna bezahlten Bestellung hier genauer beschrieben.

Mit automatischer Erfassung (Auto-Capture aktiviert)

1. Der Kunde wählt eine Klarna Zahlungsart im Shop aus.
2. Der Kunde gibt, falls nötig, die von Klarna geforderten Angaben an.
3. Der Kunde bestellt zahlungspflichtig.
4. Das Plugin legt die Bestellung und den Zahlungseingang im Shop an.
5. Die WaWi holt die Bestellung und den Zahlungseingang ab. Die Bestellung kommt in Ihrer Wawi als Bezahlt = Ja an. Im Hinweis-Feld der Bestellung fügt das Plugin die Klarna Bestell-ID hinzu.
6. Sie versenden die Bestellung.

Ohne automatische Erfassung (Auto-Capture deaktiviert)

1. Der Kunde wählt eine Klarna Zahlungsart im Shop aus.
2. Der Kunde gibt, falls nötig, die von Klarna geforderten Angaben an.
3. Der Kunde bestellt zahlungspflichtig.
4. Das Plugin autorisiert die Bestellung gegen Klarna. Die Autorisierung ist bei Erfolg im Status "Autorisiert" bzw. "Authorized". Es wird noch kein Zahlungsbetrag aktiviert.
5. Das Plugin legt die Bestellung ohne Zahlungseingang im Shop an.
6. Die WaWi holt die Bestellung ab. Die Bestellung ist unbezahlt. Im Hinweis-Feld der Bestellung fügt das Plugin die Klarna Bestell-ID hinzu.
7. Sie versenden die Bestellung.
8. Das Plugin erkennt den Versand und löst die Aktivierung über den Gesamtbetrag oder, sofern die Bestellung teilversandt wurde, den entsprechenden Teilbetrag der Bestellung gegen Klarna.
9. Wenn der Gesamtbetrag der Bestellung, d.h. wenn die Bestellung komplett versendet wurde, aktiviert wurde, setzt das Plugin den Zahlungseingang im Shop.
10. Die Wawi holt den Zahlungseingang ab. Die Bestellung ist im Status bezahlt = ja.

Storno

Wie der Storno-Vorgang behandelt wird, ist abhängig davon ob die automatische Erfassung aktiviert wurde oder nicht.

Mit automatischer Erfassung / Bereits bezahlte Bestellung

Da in diesem Fall die Zahlung schon erfolgt ist bzw. der Zahlungsbetrag gegen Klarna aktiviert ist, kann das Plugin die Bestellung nicht mehr gegen Klarna abbrechen. Die Bestellung muss über das Klarna Händlerportal manuell erstattet werden. Im Plugin-Backend befindet sich unter jeder Bestellung ein Link, welcher die jeweilige Bestellung im Klarna Händler-Portal aufruft.

Ohne automatische Erfassung / Noch nicht bezahlte Bestellung

Das Plugin erkennt der Storno-Vorgang automatisch und bricht die Bestellung gegen Klarna ab.

Teil-Storno

Um eine Bestellung in Klarna teil zu stornieren, muss das ausstehende Betrag freigegeben werden. Dies kann sowohl über das Plugin-Backend als auch über das Klarna Händler-Portal geschehen. Im Plugin-Backend wird bei jeder teil-erfassten Bestellung ein Button "Genehmigten Betrag entfernen" angezeigt. Über diesen Button kann der ausstehende Betrag freigeben werden und die Bestellung ist für Klarna teil-storniert.

Retouren / Erstattungen

Retouren und Erstattungen müssen generell über das Klarna Händler-Portal vorgenommen werden. Jede Bestellung im Plugin-Backend enthält einen Link zur entsprechenden Bestellung im Händler-Portal. Des Weiteren werden über das Händler-Portal getätigte Erstattungen im Plugin Backend des Shops bei jeder Bestellung unter dem Punkt "Erstattungen" angezeigt.

Bestelldaten ändern

Wenn Bestelldaten, wie die Liefer- oder Rechnungsadresse, oder die Bestellpositionen (hinzufügen, entfernen, rabattieren) in der WaWi geändert werden, müssen diese Änderungen auch im Klarna Händler-Portal für diese Bestellung vorgenommen werden. Dies ist notwendig, da die WaWi beim Shop-Abgleich diese Änderungen nicht an den Shop weitergibt, wodurch das Plugin nicht entsprechend reagieren kann.

Aus diesem Grund enthält jede Bestellung im Plugin-Backend einen Link zur entsprechenden Bestellung im Händler-Portal.

On-Site Messaging (OSM)

On-Site-Messaging ist eine Lösung, die den Endverbraucher vor dem Kauf darauf hinweist, dass er zum Kauf bei Klarna berechtigt sein kann. Das Messaging kann dabei von allgemeinen Bannern zur Förderung Ihrer Partnerschaft mit Klarna und der Verfügbarkeit von Finanzmitteln bis zu personalisierten Kreditaktionen auf Produkt- oder Warenkorbseiten reichen.

Um On-Site Messaging auf Ihrer Seite nutzen zu können, müssen zuerst die folgenden Schritte ausgeführt werden:

1. Aufrufen des Klarna Händler-Portals
2. On-Site Messaging aus der App-Liste aufrufen
3. Akzeptieren der Nutzungsbedingungen
4. Im Plugin-Backend ein neues Placement hinzufügen
5. JavaScript-Tag vom Händler-Portal kopieren und in das JavaScript-Tag Feld einfügen
6. Placement-Tag vom Händler-Portal kopieren und in das Placement-Tag Feld einfügen

Individualisierung

Die verwendeten Templates des Plugins können mit eigenen Templates überschrieben werden, um zum Beispiel eigene CSS-Styles einzubinden.

Template-Dateien

Di folgenden Template-Dateien können ersetzt werden, indem eine Datei mit dem Namen *_custom.tpl angelegt wird. Diese Dateien werden dann anstelle der originalen .tpl-Datei geladen.

FAQ

Ist das Plugin mehrsprachenfähig? Worauf muss ich achten?

Ja das Plugin unterstützt unbegrenzt Sprachen. Im Auslieferungszustand werden jedoch nur deutsch und englisch vollständig mitgeliefert. Beim Einsatz weiterer Fremdsprachen müssen die fehlenden Plugin-Sprachvariablen ergänzt werden.

Die Sprachvariablen befinden sich in der Pluginverwaltung unter dem "Sprachvariablen"-Link in der Zeile des Plugins.

Changelog

v1.0.0

• Initiales Release