VibeFox Klarna for PrestaShop — Hilfe
Anforderungen
PrestaShop: 8.0 bis 9.x.
PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.
Klarna-Händlerkonto: Sie benötigen die API-Zugangsdaten (Benutzername und Passwort) Ihres Klarna-Händlerkontos für eine API-Region sowie die Testzugangsdaten aus dem Playground-Portal von Klarna (siehe Konfiguration). Jede API-Region hat eigene Zugangsdaten. Pro Shop kann nur ein Händlerkonto (eine API-Region) verwendet werden.
Währung: eine Klarna-Währung Ihrer Region: EUR, SEK, NOK, DKK, GBP, CHF, PLN, CZK, HUF oder RON in Europa; USD, CAD oder MXN in Nordamerika; AUD oder NZD in Ozeanien.
VibeFox-Lizenzschlüssel: Erhältlich auf vibefox.net. Ein Schlüssel funktioniert für eine Domain.
Installation
1. Gehen Sie im Back Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls aus.
2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie VibeFox Klarna Payments später in der Modulliste und klicken Sie dort auf Configure.
3. Geben Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).
4. Wählen Sie die API region Ihres Klarna-Händlerkontos.
5. Geben Sie Benutzername und Passwort der Testumgebung aus dem Playground-Portal von Klarna ein, lassen Sie Test mode eingeschaltet, aktivieren Sie Enable/Disable, klicken Sie auf Save und platzieren Sie eine Testbestellung.
6. Geben Sie Benutzername und Passwort für den Livebetrieb aus dem Klarna Merchant Portal ein, schalten Sie Test mode aus und wählen Sie, wann Bestellungen erfasst werden (Standard: wenn die Bestellung versandt wird).
Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Klarna fraud review und Klarna payment on hold. Keiner davon gilt als bezahlt oder löst eine E-Mail aus. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Klarna Payments > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite TEST MODE: Klarna playground, no real payments. oder LIVE: real Klarna payments. an. Sie warnt, wenn Benutzername oder Passwort des aktiven Modus fehlen (Klarna wird dann in der Kasse ausgeblendet), und wenn die Standardwährung des Shops in der gewählten API-Region nicht von Klarna verkauft wird.
Klarna Payments
Enable/Disable: Enable Klarna Payments schaltet die Zahlungsart ein oder aus. Standard: aus.
Title: Der Name der Zahlungsart, den Kunden in der Kasse sehen. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: Klarna. Pflichtfeld.
Description: Der Text, der Kunden über dem Klarna-Widget angezeigt wird. Standard: Pay now, later or in instalments with Klarna.
API-Zugangsdaten
Die API-Zugangsdaten von Klarna (Benutzername und Passwort) werden im Klarna Merchant Portal (portal.klarna.com) unter Settings > Klarna API credentials erstellt. Testzugangsdaten stammen aus dem Playground-Portal: playground.eu.portal.klarna.com für Europa, playground.us.portal.klarna.com für Nordamerika und Ozeanien.
Test mode: Verwendet die Klarna-Testumgebung (Testzugangsdaten, keine echten Zahlungen). Standard: an. Solange der Testmodus aktiv ist, sehen Kunden unter der Zahlungsart TEST MODE: Klarna playground, no real payment is made. Bestellungen behalten die Umgebung, in der sie aufgegeben wurden: Erfassungen und Erstattungen von Testbestellungen verwenden immer die Testzugangsdaten.
API region: Die Region Ihres Klarna-Händlerkontos. Kunden können nur aus den Ländern dieser Region mit Klarna bezahlen, und zwar in der Währung ihres Landes. Das Land wird aus der Rechnungsadresse des Warenkorbs übernommen.
Live username (UID): der API-Benutzername für den Produktivbetrieb, zum Beispiel PK12345_abcdef012345.
Live password: das API-Passwort für den Produktivbetrieb (gemeinsames Geheimnis).
Test username (UID): der API-Benutzername der Testumgebung.
Test password: das API-Passwort der Testumgebung (gemeinsames Geheimnis).
Gespeicherte Passwörter werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.
Clear saved passwords: Setzen Sie den Haken bei einem Passwort und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert.
Bestellverwaltung
Eine aufgegebene Klarna-Bestellung ist eine Autorisierung: Der Kunde wird erst belastet, wenn die Bestellung erfasst wird. Nicht erfasste Autorisierungen verfallen, in der Regel nach 28 Tagen. Versenden Sie Bestellungen daher rechtzeitig oder nutzen Sie die automatische Erfassung.
Capture: Wann der Kunde belastet wird. Erstattungen sind nur für erfasste Beträge möglich.
Cancellation: Cancel the Klarna order (release the authorization) when a not yet captured order is Cancelled. Standard: an.
Benachrichtigungen
Klarna meldet das Ergebnis einer Betrugsprüfung (Bestellungen mit dem Status "pending") an die Adresse, die unter Notification URL angezeigt wird. Mit schönen URLs sieht sie so aus: https://your-shop/module/wcp_klarna_payment/notification, möglicherweise mit einem Sprachcode wie /en/. Die URL wird automatisch mit jeder Bestellung übermittelt, Sie müssen bei Klarna also nichts einrichten. Dem Inhalt der Benachrichtigung wird nie vertraut: Jede Benachrichtigung wird mit der Klarna Order Management API geprüft, und zwar mit den Zugangsdaten der Umgebung und Region, in der die Bestellung aufgegeben wurde. Die Klarna-Bestellung muss sich auf den Warenkorb dieses Shops beziehen. Das Modul handelt anhand dessen, was Klarna meldet:
Akzeptiert Klarna einen Kauf, nachdem Sie die Bestellung storniert oder erstattet haben, wird die Bestellung nicht wieder geöffnet und die Klarna-Autorisierung wird aufgehoben. Die Benachrichtigung funktioniert, während der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.
Erweitert
Debug log: Protokolliert API-Aufrufe und Zahlungsereignisse in logs/wc_kl_debug.log.php im Modulordner. Die Datei kann nicht über das Web aufgerufen werden. Fehler werden immer protokolliert. Das Protokoll enthält nie Zugangsdaten, Autorisierungstoken oder Kundendaten. Standard: aus.
Log: Zeigt die Größe und die neuesten Einträge des Protokolls sowie eine Schaltfläche zum Leeren.
Uninstall: Löscht beim Deinstallieren des Moduls die Moduleinstellungen und das Protokoll. Bestelldaten (Klarna-Bestell-IDs, Erstattungen) bleiben immer erhalten. Standard: aus.
Kasse
Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Klarna mit dem Klarna-Logo), und das Klarna-Widget wird im Zahlungsschritt geladen. Das Modul erstellt die Klarna-Sitzung serverseitig aus dem Warenkorb. Im Widget wählt der Kunde Sofort bezahlen, Später bezahlen oder In Raten zahlen, je nachdem, was Klarna anbietet. Wenn der Kunde die Bestellung aufgibt, wird die Klarna-Sitzung zuerst mit dem endgültigen Warenkorb aktualisiert, und Klarna autorisiert den Kauf im Widget. Danach legt das Modul die Klarna-Bestellung serverseitig mit den Positionen, Summen und Adressen des Warenkorbs an. Warenkorbrabatte werden als separate Position an Klarna übermittelt. Vor der Antwort von Klarna existiert keine Bestellung.
Das Ergebnis hängt vom Betrugsstatus von Klarna ab:
Kann Klarna die Bestellung nicht annehmen, bleibt der Kunde in der Kasse mit einer kurzen Meldung, zum Beispiel Klarna could not accept this order. Please check your billing details or choose another payment method., Klarna did not respond. Please try again in a moment. oder, wenn die Autorisierung abgelaufen ist, mit der Aufforderung, erneut auf "Place order" zu klicken. Die Details werden im Protokoll festgehalten. Stimmen Land und Währung des Kunden nicht mit einem Klarna-Markt Ihrer Region überein, sieht der Kunde Klarna is not available for your billing country and currency. Please choose another payment method.
Ein Doppelklick erzeugt nie eine zweite Klarna-Bestellung für denselben Warenkorb. Ändert sich der Warenkorb, während Klarna antwortet, zum Beispiel in einem anderen Browser-Tab, wird die Bestellung als Klarna payment on hold mit einer Notiz angelegt. Hat Klarna den Kauf genehmigt, die Bestellung konnte aber nicht angelegt werden, sieht der Kunde Your Klarna purchase was approved, but the order could not be completed automatically. Please contact us — do not pay again. Der nächste Versuch oder die Benachrichtigung von Klarna legt die Bestellung aus der gespeicherten Klarna-Bestellung an, ohne eine neue Autorisierung.
Die Klarna-Bestellung im Klarna Merchant Portal trägt die Warenkorbnummer als Händlerreferenz, weil die PrestaShop-Bestellung beim Aufgeben noch nicht existiert.
Das Modul bietet kein Klarna Checkout (KCO, vollständiger Ersatz der Kasse), keine Klarna-Express-Checkout-Buttons, kein On-site messaging oder Sign in with Klarna, keine Abonnements oder gespeicherten Zahlungsmethoden und keine Teilerfassungen pro Bestellposition. Bestellpositionen werden nicht erneut an Klarna übermittelt, wenn Sie eine Bestellung nach dem Aufgeben bearbeiten.
Bestellungen und Erstattungen
Order statuses
No order yet: Der Kunde hat die Klarna-Autorisierung nicht abgeschlossen, oder Klarna hat den Kauf abgelehnt. Es existiert nur der Warenkorb.
Payment accepted: Klarna hat den Kauf akzeptiert. Die Zahlung wird mit der Klarna-Bestell-ID als Transaktions-ID erfasst, und eine interne Notiz zeigt die Klarna-Bestell-ID und den Zeitpunkt der Erfassung.
Awaiting Klarna fraud review: Der Kauf wartet auf die Betrugsprüfung durch Klarna. Die Benachrichtigung von Klarna setzt die Bestellung auf Payment accepted, Payment error oder Canceled.
Klarna payment on hold: Klarna hat einen unerwarteten Betrugsstatus gemeldet, oder der von Klarna gemeldete Betrag bzw. die Währung stimmen nicht mit der Bestellung überein. Die Notiz erklärt es. Prüfen Sie die Bestellung im Klarna Merchant Portal.
Payment error: Klarna hat den Kauf nach der Betrugsprüfung abgelehnt oder gestoppt. Versenden Sie die Bestellung nicht.
Canceled: Sie haben die Bestellung storniert, oder Klarna meldet die Klarna-Bestellung als storniert, abgelaufen oder geschlossen. Bei eingeschalteter Cancellation storniert das Stornieren einer noch nicht erfassten Bestellung auch die Klarna-Bestellung und hebt die Autorisierung auf, sodass der Kunde nicht belastet wird. Eine bereits erfasste Bestellung wird bei Klarna nicht storniert: Erstatten Sie sie, um das Geld zurückzugeben.
Refunded: Der erfasste Betrag wurde über das Modul vollständig erstattet.
Capture
Bei When the order is shipped erfasst das Setzen der Bestellung auf einen Versandstatus den Bestellbetrag, bevor der neue Status gespeichert wird. Verweigert Klarna die Erfassung, zum Beispiel weil die Bestellsumme nach einer Bearbeitung über den autorisierten Betrag gestiegen ist, bleibt der Status unverändert, es wird keine E-Mail gesendet, und der Grund wird auf der Bestellseite und in einer Notiz angezeigt: Der Kunde wurde NICHT belastet. Beheben Sie das Problem und ändern Sie den Status erneut, um es noch einmal zu versuchen, oder erfassen Sie im Klarna Merchant Portal und stellen Sie Capture auf manuell um. Unter PrestaShop 8 im Produktionsmodus kann das Back Office den Status trotzdem speichern. Dann setzt das Modul stattdessen Klarna payment on hold mit einer Notiz, damit die Bestellung nie als versandt angezeigt wird, ohne dass erfasst wurde. Eine erfolgreiche Erfassung fügt eine Notiz mit dem erfassten Betrag und der Erfassungs-ID hinzu.
Block Klarna payment
Die Bestellseite zeigt einen Block Klarna payment mit der Klarna-Bestell-ID, ihrer Umgebung und Region, einem Badge Playground für Testbestellungen, dem Betrugsstatus und dem Klarna-Status, dem autorisierten Betrag, den erfassten und erstatteten Beträgen sowie dem Erstattungsverlauf.
Erstattungen
Geben Sie im Block Klarna payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Klarna. Bestätigen Sie die Frage Refund this amount through Klarna? This cannot be undone. Vollständige und teilweise Erstattungen sind für erfasste Beträge möglich, bis zu dem, was Klarna als erfasst meldet, abzüglich bereits erstatteter Beträge. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Module ist nicht erforderlich. Die Erstattung wird an die Umgebung und Region gesendet, in der die Bestellung aufgegeben wurde, daher müssen die Zugangsdaten dieser Umgebung hinterlegt sein. Akzeptiert Klarna die Erstattung nicht, zeigt der Block den Fehler, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit der Klarna-Erstattungs-ID hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded; eine teilweise Erstattung ändert den Status nicht. Eine wiederholte Erstattung wird nie zweimal ausgeführt.
Eine noch nicht erfasste Bestellung kann nicht erstattet werden. Stornieren Sie sie stattdessen, um die Autorisierung aufzuheben. Bei Capture auf manuell weiß der Shop nicht, was Sie im Klarna Merchant Portal erfasst haben. Das Erstattungsformular wird dann mit einem leeren Betrag angezeigt, und Klarna prüft den Betrag beim Absenden.
Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsbuttons von PrestaShop auf der Bestellseite senden kein Geld über Klarna zurück. Erstattungen, die im Klarna Merchant Portal vorgenommen wurden, erscheinen nicht im Block, zählen aber zu dem Betrag, den Klarna noch erstatten lässt.
Lizenzschlüssel
Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Klarna Payments ist der erste Block auf Modules > Module Manager > VibeFox Klarna Payments > Configure, über den Einstellungen. Geben Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: presta-payment-klarna und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. Die Texte des Blocks folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).
Wird der Schlüssel nicht akzeptiert, nennt der Block den Grund, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nachdem sich die Shop-Adresse geändert hat oder nachdem Sie einen Domain-Platz in Ihrem Konto freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul weiter mit dem zuletzt bekannten Status.
Ein Schlüssel funktioniert für eine Domain: die Domain des Haupt-Shops, auch bei einer Multistore-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.
Ohne aktiven Schlüssel wird Klarna Kunden in der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Der PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind, daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht in der Kasse testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen: Klarna-Benachrichtigungen werden weiterhin verarbeitet, und Bestellungen können weiterhin erfasst, storniert und erstattet werden.
Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support benötigen jedoch eine Verlängerung. Der Status wird automatisch erneut geprüft, während Sie im Back Office arbeiten: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Es ist kein Cron-Job nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
Klarna wird in der Kasse nicht angezeigt: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die Zugangsdaten des aktiven Modus ausgefüllt sind: Benutzername und Passwort der Testumgebung im Testmodus, im Livebetrieb die Live-Zugangsdaten. Die Einstellungsseite zeigt eine Warnung, wenn sie fehlen. Das Rechnungsland des Kunden muss ein Klarna-Land Ihrer API region sein, und der Kunde muss in der Währung dieses Landes bezahlen (ein Kunde aus Schweden zum Beispiel in SEK). Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.
Die Zahlung ist erfolgt, aber die Bestellung bleibt bei Awaiting Klarna fraud review: Der Kauf wartet auf die Betrugsprüfung durch Klarna, und die Bestellung wird aktualisiert, sobald die Benachrichtigung von Klarna eintrifft. Prüfen Sie, ob Ihr Shop Anfragen von Klarna an der in den Einstellungen angezeigten Notification URL empfangen kann und ob die Zugangsdaten der Umgebung, in der die Bestellung aufgegeben wurde, noch hinterlegt sind. Aktivieren Sie Debug log und prüfen Sie das Feld Log auf der Modulseite.
Die Benachrichtigung antwortet Not configured: Die Zugangsdaten der Umgebung (Test oder Live), in der die Bestellung aufgegeben wurde, fehlen, daher kann die Benachrichtigung nicht geprüft werden. Geben Sie sie ein. Klarna versucht die Benachrichtigung erneut.
Die Benachrichtigung antwortet Verification failed: Die Klarna-Bestellung konnte nicht über die Order Management API gelesen werden. Klarna versucht die Benachrichtigung erneut.
Die Benachrichtigung antwortet Busy: Die Bestellung wurde im selben Moment von einer anderen Anfrage aktualisiert. Klarna versucht die Benachrichtigung erneut.
Die Benachrichtigung antwortet mismatch_ref oder Unknown order: Die Klarna-Bestellung bezieht sich nicht auf den Warenkorb dieses Shops, oder das Modul kennt sie nicht. Die Bestellung wird nicht verändert.
Das Widget lädt nicht: Der Kunde sieht Klarna could not be loaded. Please try again or choose another payment method. oder Klarna is not available for this purchase. Prüfen Sie die Zugangsdaten des aktiven Modus sowie Land und Währung des Kunden.
Die Statusänderung auf Shipped wird abgelehnt: Die Klarna-Erfassung ist fehlgeschlagen. Lesen Sie den Grund im Block Klarna payment oder in der Notiz. Die Bestellsumme benötigt möglicherweise mehr als den noch autorisierten Betrag, die Klarna-Bestellung ist eventuell noch nicht akzeptiert, oder die Autorisierung ist abgelaufen. Beheben Sie das Problem und ändern Sie den Status erneut, oder erfassen Sie im Klarna Merchant Portal.
Erstattung schlägt fehl: Lesen Sie die Meldung im Block. Die Bestellung ist vielleicht noch nicht erfasst (stornieren Sie sie dann stattdessen), der Betrag übersteigt möglicherweise den noch erstattbaren Betrag, oder die Zugangsdaten der Umgebung der Bestellung fehlen.
Der Kunde sieht This order is already being paid: Eine andere Anfrage für denselben Warenkorb läuft, zum Beispiel ein Doppelklick. Warten Sie einen Moment und prüfen Sie, ob die Bestellung angelegt wurde.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Klarna Payments und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Uninstall im Abschnitt Advanced eingeschaltet, werden die Moduleinstellungen, das Protokoll und die temporären Widget-Sitzungen entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Klarna-Bestellungen und -Erstattungen sowie die Bestellstatus Awaiting Klarna fraud review und Klarna payment on hold bleiben immer erhalten, sodass zuvor aufgegebene Bestellungen nach einer Neuinstallation weiter erfasst und erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
Klarna ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit Klarna verbunden noch wird es von Klarna unterstützt.
