OXID eShop Dokumentation / Handbuch

Lizenz: Copyright © 2024 Klarna AB
Licensed under the Apache License, Version 2.0 (the „License“); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an „AS IS“ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Dieses Plugin ermöglicht Ihnen die Erweiterung Ihres OXID eShops um die von Klarna bereitgestellten Zahlungsarten.

Die von Klarna bereitgestellten Zahlungsarten werden, wie im OXID eShop normalerweise üblich, auf der Bezahlartenauswahlseite aufgelistet. Dabei haben Sie die Auswahl zwischen drei verschiedenen Optionen:

Wir empfehlen zu Ihrer eigenen Sicherheit die Erstellung einer Datensicherung (Backup), sowohl von den Shop-Dateien als auch von Ihrer Mysql-Datenbank, bevor Sie mit der Installation beginnen, damit Sie im Falle eines Problems auf den vorherigen Stand zurückgreifen können.

Tipp: Führen Sie die gewünschte Installation samt ggf. erforderlicher Template-Anpassungen am besten zunächst in einem Stage-System / Test-System durch, bevor Sie Änderungen in Ihrem produktiven System vornehmen.

• Community Edition: Version 7.0.x - 7.4.x
• Professional Edition: Version 7.0.x - 7.4.x
• Enterprise Edition: Version 7.0.x - 7.4.x

Bitte prüfen Sie, ob Ihnen das passende Paket für Ihre OXID eShop Version vorliegt.
Installieren Sie diese Modulversion nicht, wenn Sie eine andere Shopversion einsetzen!

Das Klarna Checkout und Klarna Payments Modul für den OXID eShop ist lauffähig und getestet mit PHP 8.0 bis PHP 8.4.

Die aktuelle Versionsnummer des OXID 7 Klarna Payments Plugin erhalten Sie unter https://github.com/FATCHIP-GmbH/OXID-Klarna-7/releases

Um das OXID 7 Klarna Payments Plugin zu aktualisieren, müssen Sie die nachfolgenden Schritte ausführen:

• Loggen Sie sich per sFTP/FTP auf Ihren Server ein und wechseln Sie in das Rootverzeichnis des Shops
• Öffnen Sie die composer.json und ändern Sie die angegebene Version auf die Version, auf die Sie aktualisieren möchten
  
• Loggen Sie sich auf die Kommandozeile (CLI) ein und navigieren Sie zum Rootverzeichnis des Shops
• Führen Sie den nachfolgenden Befehl:
  

  composer update

Der Server, auf dem das Klarna CPayments Modul für den OXID eShop genutzt werden soll, muss selbstverständlich den OXID Server- und Systemvoraussetzungen entsprechen: https://docs.oxid-esales.com/eshop/de/7.1/installation/neu-installation/server-und-systemvoraussetzungen.html

Um das Klarna Payments Modul für den OXID eShop nutzen zu können, muss der Shop zwingend über ein SSL-Zertifikat verfügen.

Hinweis: Es ist unerheblich, ob es sich um ein offizielles oder ein selbst-signiertes SSL-Zertifikat handelt.

Klarna sendet zur Validierung von Transaktionen Requests an Ihren OXID eShop.

Damit solche Callback Aufrufe von Klarna an Ihren Shop erfolgen können, muss Ihr Shop frei von draußen über das Internet erreichbar sein. Das heißt, es darf weder einen Passwortschutz, noch eine IP-Sperre oder einen Firewallschutz in Ihrem Shop aktiv sein, der Klarna daran hindert, die entsprechenden Validierungs-URLs aufzurufen.

Denken Sie insbesondere daran, wenn Sie in Ihrer Entwicklungs- oder Stage-Umgebung testen wollen: HTTPS-Aufrufe von den externen Klarna Servern auf Port 443 Ihres Servers müssen erlaubt sein.

Die Artikelnummern im Feld OXARTICLES.OXARTNUM müssen im Shop (bei der Enterprise Edition lediglich für die jeweilige Subshop-ID) stets eindeutig vergeben werden. Das vorliegende Klarna Payments Modul für den OXID eShop sendet diese Artikelnummern während des Bestellprozesses zur Validierung an Klarna. Gibt es dabei in einer Bestellung mehrere Bestellzeilen mit Artikeln oder Varianten mit der gleichen Artikelnummer, so kann die Bestellung nicht angelegt werden.

Das vorliegende Klarna Payments Modul für den OXID eShop stellt die Klarna Payments Zahlarten für die folgenden Länder zur Verfügung: SE, NO, FI, DE, AT, CH, NL, UK, BE, IT, ES, FR, DK, IRL

Bitte stellen Sie sicher, dass Sie Klarna Zahlungsarten ausschließlich in den Ländern aktivieren, für die Sie mit Klarna entsprechende Verträge abgeschlossen haben.

Es gibt ein paar Besonderheiten im Klarna Payments Modul für den OXID eShop, sowie einige Klarna Features, die zur Zeit noch nicht mit dem Klarna Payments Modul für den OXID eShop umgesetzt wurden. Bitte prüfen Sie vor dem Einsatz dieses Moduls, ob diese Besonderheiten ggf. für Sie relevant sind:

• Pending Flow: Das vorliegende Modul geht davon aus, dass Bestellungen seitens Klarna entweder sofort akzeptiert oder sofort abgelehnt werden. Der Klarna Pending Status wird jedoch nicht unterstützt. Dies muss bei der Konfiguration der Merchant ID seitens Klarna berücksichtigt werden.
• Erstattungen/Retouren: Gutschriften einer zuvor abgebuchten Zahlung können nicht über das OXID Admin Backend an Klarna gesendet werden. Verwenden Sie dazu bitte das Klarna Merchant Portal. Auf dem Reiter „Klarna“ bei jeder Klarna-Bestellung finden Sie einen Link, der Sie direkt dorthin führt.
• Gift Cards: Klarna versteht darunter Geldgutscheine, die man z.B. in einem Ladengeschäft erwerben kann. Einer derartige Funktion wird seitens des OXID eShops zur Zeit nicht angeboten.
• Gutscheine: OXID Promotion Gutscheine werden an Klarna als „Discounts“ übermittelt.
• Partial Captures: Es ist nicht möglich, über das OXID Admin Backend Teillieferungen an Klarna zu übermitteln. Verwenden Sie dazu bitte das Klarna Merchant Portal. Auf dem Reiter „Klarna“ bei jeder Klarna-Bestellung finden Sie einen Link, der Sie direkt dorthin führt.
• B2B-Support: Bestellungen von Firmen sind technisch im Modul implementiert, werden jedoch durch Klarna nur in Ausnahmefällen für einzelne Länder vertraglich aktiviert. Bitte wenden Sie sich an Ihren Klarna Account Manager für weitere Informationen, ob B2B für Ihre Verkaufsländer verfügbar ist. Im Bereich Klarna Checkout kann ein Firmenname eingegeben werden, der als „c/o Angabe“ gespeichert wird.
  Die Integration von Billie für B2B-Bestellungen sind in Planung.
• Das automatische Abbuchen von Bestellungen direkt bei Bestellabschluss wurde in diesem Klarna Checkout und Klarna Payments Modul für den OXID eShop nicht implementiert
• Lokalisierung: Wählt ein Kunde in einem deutschen Shop mit Shop-Frontend Sprache deutsch im Klarna Checkout Global Iframe als Lieferland Japan, dann bleibt die Sprache des Iframes deutsch.
• Bitte prüfen Sie, ob Sie Telefonnummer oder Geburtsdatum als Pflichtfelder festgelegt haben unter Admin > Stammdaten > Grundeinstellungen > Einstell. > Weitere Einstellungen > “Muss”-Felder für die Registrierung des Kunden. Wenn Sie eins von diesen Feldern zwingend benötigen, stellen Sie sicher, dass Sie diese Felder auch in der Klarna Checkout Konfiguration als Pflichtfelder setzen. Andernfalls kann es zu Bestellabbrüchen aufgrund unvollständiger Daten kommen.

Um das Klarna Modul in Ihrem Shop einzurichten führen sie bitte in der angegebenen Reihenfolge folgende Schritte aus.

• Loggen Sie sich auf die Kommandozeile (CLI) ein und navigieren Sie zum Rootverzeichnis des Shops
• Führen Sie den nachfolgenden Befehl:
  

  composer require fatchip-gmbh/oxid-klarna-7

1. Loggen Sie sich in den Admin-Bereich Ihres OXID eShops ein
2. Aktivieren Sie das Plugin Gehen Sie zu „Erweiterungen“ → „Module“ → „Klarna Payments“ → „Stamm“ und klicken Sie auf „Aktivieren“

Ordnen Sie die neu erstellten Klarna-Zahlungsarten unter „Shopeinstellungen“ → „Versandarten“ den entsprechenden Versandarten zu, so wie Sie es auch für andere Zahlungsarten im OXID eShop machen würden.

Falls Sie die OXID Enterprise Edition verwenden, wiederholen Sie bitte die Schritte 2 und 3 für jeden einzelnen Sub-Shop/Mandanten.

Im eShop Admin Haupt-Menü taucht die neue Rubrik „Klarna“ links mit mehreren Unter-Menüeinträgen auf:

Hier erscheinen einige Informationen über Klarna:

Auf dieser Seite tätigen Sie einige Einstellungen.

Weitere Informationen finden Sie auch in der Tooltip-Hilfe im Shop, indem Sie auf das Fragezeichen-Symbol hinter der jeweiligen Einstellung klicken.

Ganz unten auf der jeweiligen Seite finden Sie stets die Schaltfläche „Speichern“. Denken Sie daran, Ihre getätigten Einstellungen immer zu speichern, damit sie ins System übernommen werden.

Hier können Sie auswählen, welche Klarna Payments Sie anbieten möchten:

Weitere Einstellungen sind für die Klarna Payments im Bereich der Design Einstellungen möglich.

Wählen Sie hier, welches Klarna Element im Footer Ihres Shops eingebunden werden soll. Im Betriebs-Modus „Klarna Checkout“ haben Sie hier die Auswahl zwischen dem „Payment Method Display“, das den Kunden Ihres Shops anzeigt, welche Klarna Zahlungsmethoden zur Verfügung stehen, und einem einfachen Klarna Logo. Es lässt sich zeitgleich nur eine dieser Optionen anschalten – oder gar keine. Abhängig von Ihrem Shop-Design können Sie eine passende Farb-Variation von „Payment Method Display“ oder Logo auswählen. Das „Payment Method Display“ steht darüber hinaus in einer langen und einer kurzen Variante zur Verfügung. Im Betriebs-Modus „Klarna Payments“ steht hier lediglich das Klarna Logo zur Einbindung zur Verfügung.

Mit diesen Einstellungen können Sie das Look'n'Feel der Klarna Payment Zahlungsoptionen Ihrem Shop Layout anpassen. Lassen Sie die Felder einfach leer, um das Klarna Standard Farbschema zu verwenden.

Tipp: Bei Klick in eines der Farb-Felder öffnet sich ein komfortabler Farbwähler, so dass der hexadezimale Farbcode automatisch ins Feld eingetragen wird. Die Radius Einstellung wirkt sich unmittelbar auf das Eingabefeld selbst aus, damit man direkt ein Bild davon hat, wie der gewählte Radius im Frontend aussieht.

Hier sehen Sie, wie sich die Eingabe von Farbwerten in die oben stehenden Feldern im Shop Frontend auswirkt:

Aktivieren Sie die Funktionen auf dieser Seite lediglich, falls Sie entsprechend von Ihrem Klarna Integration Manager instruiert wurden.

Klarna Extra Merchant Data bezeichnet zusätzliche Informationen über Ihre Kunden, die ggf. von Ihrem Shop automatisch an Klarna übertragen werden und seitens Klarna für eine bessere Risikoeinschätzung erforderlich sind.

Customer Account Info übermittelt Informationen über das Kundenkonto an Klarna: Wann wurde das Konto angelegt, wann wurde es zuletzt verändert.

Payment History Full übertägt Informationen über die Anzahl und Summen der Käufe eines Kunden, das Datum des ersten und letzten Kaufs sowie die verwendete Bezahltmethode. Wenn Sie diese Informationen an Klarna übertragen, weisen Sie bitte für jede Bezahlart im Shop einmal zu, um welchen Typ der Zahlungsart es sich handelt und ob und ggf. wie diese Bestellungen als bezahlt an Klarna gemeldet werden sollen.

Mit Hilfe des Pass-through Feldes „merchant_data“ können Sie bei Bedarf individuelle Zusatz-Informationen zu einer Bestellung an Klarna übergeben. Auf diese Daten können Sie später mittels API bei jedem Abruf der Bestelldaten von Klarna wieder zugreifen. Sie können in diesem Feld z.B. eine einfache Zeichenfolge aber auch eine komplexe JSON Struktur als String an Klarna übertragen.

Wird der entsprechende Schalter im Admin-Backend gesetzt, so wird die Methode getPassThroughField() der Klasse KlarnaPassThrough ausgeführt. Diese Klasse liefert standardmäßig eine leere Antwort zurück. Um entsprechend individuelle Informationen an Klarna zu übertragen, muss diese Klasse mit Hilfe eines eigenen Moduls überladen werden.

Dies ist der einfachste Weg, um Zusatz-Informationen an Klarna zu übermitteln. Näheres hierzu erfahren Sie in der Entwickler-Dokumentation.

Hier ist ein Beispiel für ein individuelles Erweiterungs-Modul:

class your_module_pass_through extends your_module_pass_trough_parent
{
 public function getPassThroughField()
 {
 $mainData = „any custom string“;
 return $mainData;
 }
}

Ihr Modul müssen Sie über die Metadata.php in Ihrem Shop bekannt machen.

Ein weiterer, etwas komplexerer Weg, um Zusatz-Informationen an Klarna übermitteln, ist, das Klarna Modul mit einem individuellen Modul zu erweitern um weitere Informations-Pakete wie Travel, Event, Voucher oder Subscription an Klarna zu übermitteln.

Hier ist ein Beispiel für ein individuelles Erweiterungs-Modul:

class your_module_klarna_emd extends your_module_klarna_emd_parent
{
 public function getAttachments($oxUser)
 {
 $mainData = parent::getAttachments($oxUser);
 $myEMDData = array('your_custom_info' =>
 array('example_field' => 'example data')
 );
 return array_merge($mainData, $myEMDData);
 }
}

Ihr Modul müssen Sie über die Metadata.php in Ihrem Shop bekannt machen.

Kunden sind sich nicht immer der verschiedenen Kredit- und Finanzierungsmöglichkeiten bewusst, die ihnen zur Verfügung stehen, bevor sie die Kasse erreichen. Frühzeitig verfügbare Finanzierungsmöglichkeiten beeinflussen die Kaufentscheidung. On-Site Messaging ist einfach und problemlos zu integrieren und bietet maßgeschneiderte Informationen, die von allgemeinen Bannern über die Förderung Ihrer Partnerschaft mit Klarna und die Verfügbarkeit einer Ratenzahlung bis hin zu personalisierten Kreditaktionen auf Produkt- oder Warenkorbseiten reichen.

Wählen Sie im Ihrem Shop-Admin Backend unterhalb des Menü-Punkts „Klarna“ den Link „On-Site Messaging“, um weitere Informationen und eine Schritt-für-Schritt-Anleitung für die Einrichtung und Konfiguration zu erhalten.

Falls Sie eines der vom OXID eShop standardmäßig mit ausgelieferten Themes / Template-Sätze verwenden, dann werden die Placement-Codes, die Sie im im Admin-Bereich hinterlegen können, direkt an der entsprechenden Stelle im Template eingefügt. Wie die verschiedenen Placements in der Praxis bei Verwendung von Standard Themes aussehen, sehen Sie auf den folgenden Screenshots.

Credit Promotion Artikeldetailseite	Unterhalb des Warenkorb-Buttons auf der Artikeldetailseite wird die Credit Promotion eingefügt. Auf Basis des Produktpreises wird eine entsprechende Ratenzahlung angeboten.
Credit Promotion Warenkorb	Diese Promotion wird auf der Warenkorb-Seite angezeigt – die berechnete Rate bezieht sich auf den Kauf des gesamten Warenkorb-Inhalts per Ratenzahlung.
Top-strip Promotion	Diese Promotion erscheint auf der Shop Startseite ganz oben.
Banner Promotion	Zwischen den Sektionen „Unsere Marken“ und „Frisch eingetroffen“ auf der Shop-Startseite erscheint eine Banner Promotion:

Nutzen Sie stark modifizierte oder komplett individuelle Templates, so können Sie die Placement-Tags, die Sie im Klarna Händlerportal erhalten natürlich auch direkt an der gewünschten Stelle in Ihren Templates einfügen. Optisch können Sie sich bei der individuellen Integration an den oben gezeigten Screenshots orientieren. Beachten Sie bitte, das auf der jeweiligen Seite, auf der ein Placement-Tag verwendet werden soll, stets auch der JavaScript-Tag eingebunden werden muss. Wenn Sie jedoch die Pflege der Placement-Tags über den Admin-Bereich vornehmen wollen, dann müssten Sie die entsprechenden Platzhalter, die jetzt in verschiedenen Template Blöcken verankert sind, an den gewünschten Stellen übernehmen. Platzhalter für Placement-Tags finden Sie in folgenden Dateien:

Auch hier muss jeweils der JavaScript-Tag mit auf der jeweiligen Seite platziert werden.

Nach der Installation des Klarna Checkout und Klarna Payments Modul für den OXID eShops erscheint in der Rubrik „Bestellungen“ nach Auswahl einer entsprechenden Klarna Bestellung ein neuer Reiter „Klarna“.

Während des Bestellprozesses im Shop wird für den jeweiligen Kunden eine entsprechende Klarna Reservierung angelegt und die Bonität geprüft. Um für Bestellungen ausbezahlt zu werden, müssen Sie Klarna darüber informieren, wenn Sie die Ware versendet haben. Dies können Sie über den OXID Admin Bereich tun, indem Sie auf dem Klarna Reiter auf den Button „Komplette Bestellung capturen“ klicken. Ein „Capture“ aktiviert somit die Forderung bei Klarna und führt somit beispielsweise auch zur Abbuchung, falls mit Kreditkarte bezahlt wurde.

Auch wenn Sie auf dem Reiter „Übersicht“ oder „Stamm“ auf „Jetzt versenden“ klicken, sendet der Shop im Hintergrund automatisch ein „Capture“ an Klarna.

Über das OXID Admin Backend getätigte Änderungen an der Bestellung (z.B. Hinzufügen und Löschen von Artikeln und Rabatten) werden, wenn möglich, ebenfalls an Klarna übertragen.

Wir empfehlen auf umfangreiche Anpassungen von Bestellungen mittels OXID Admin Backend zu verzichten, sondern hier lediglich den Standardprozess wie z.B. „Komplette Bestellung capturen“ oder „Bestellung stornieren“ zu nutzen. Für eine zuvor vollständig mit „Capture“ erledigte Bestellung ist anschließend auch ein vollständiger „Refund“ über das OXID Admin-Backend möglich. Alle weiteren notwendigen Anpassungen an Bestellungen und auch z.B. die Abwicklung von Teil-Retouren können bequem über das Klarna Portal vorgenommen werden.

In Farbe „grün“ wird Ihnen angezeigt, ob die Daten der Bestellung im OXID eShop und im Klarna Portal übereinstimmen. Bei Abweichungen prüfen Sie den Status ggf. direkt im Klarna Portal, denn nur die Daten dort sind ausschlaggebend.

Im OXID Admin-Backend ist für sämtliche Bestellungen, die über eine Klarna Bezahlart getätigt wurden, die nachträgliche Bearbeitung von Adressen gesperrt, denn die Risiko-Prüfung galt ausschließlich für die beim Online-Kauf hinterlegte Adresse.

Mittels Klarna API können auch verschiedene Warenwirtschafts- oder Logistik-Lösungen angebunden werden, um so z.B. automatisch bei Warenversand „Capture“ Meldungen und bei Retouren entsprechende „Refund“ Meldungen an Klarna zu übertragen.

Die Installation des Klarna Payments Moduls für den OXID eShop hat zahlreiche Auswirkungen auf das Frontend des Online-Shops.

Verwenden Sie das OXID APEX Theme, dann werden die Klarna Anpassungen automatisch über die OXID Template Blöcke eingefügt.

Verwenden Sie jedoch ein individuelles oder angepasstes Theme, bei dem ggf. die OXID Template Blöcke verändert oder gelöscht wurden, empfehlen wir Ihnen, anhand der im Plugin enthaltenen Templatedateien zu überprüfen , ob in Ihrem Online-Shop alle Klarna Funktionen korrekt eingebunden wurden.

Updates des Klarna Payments Moduls für den OXID eShop werden auf Github veröffentlicht. Den aktuellen Versions-Stand Ihres installierten Moduls sehen Sie, wenn Sie im OXID Admin Bereich in der Rubrik „Klarna“ auf „Start“ klicken.

Github Repository: https://github.com/FATCHIP-GmbH/OXID-Klarna-7/releases

Bei Bedarf erhalten Sie Support bei der Installation, Konfiguration oder beim täglichen Betrieb Ihres Moduls direkt von Klarna.

Solange Sie noch in der Integrationsphase sind, wenden Sie sich bitte entweder an Ihren persönlichen Klarna Integrationsmanager, oder sofern Ihnen kein technischer Ansprechpartner von Klarna zugewiesen wurde, wenden Sie sich bitte an oxid@klarna.com.

Befinden Sie sich bereits im Live-Betrieb mit Klarna, so wenden Sie sich bitte für Unterstützung und Support an den Klarna Merchant Support unter der E-Mail-Adresse shop@klarna.de.