VibeFox Klarna for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions antérieures de PHP.

Compte marchand Klarna : vous avez besoin des identifiants API (nom d'utilisateur et mot de passe) de votre compte marchand Klarna pour une région d'API, ainsi que des identifiants de test du portail de l'environnement de test Klarna (voir Configuration). Chaque région d'API a ses propres identifiants. Un seul compte marchand (une région d'API) peut être utilisé par boutique.

Devise : une devise Klarna de votre région : EUR, SEK, NOK, DKK, GBP, CHF, PLN, CZK, HUF ou RON en Europe ; USD, CAD ou MXN en Amérique du Nord ; AUD ou NZD en Océanie.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans le back-office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Klarna Payments dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Choisissez l'API region de votre compte marchand Klarna.

5. Saisissez le nom d'utilisateur et le mot de passe de test du portail de l'environnement de test Klarna, laissez Test mode activé, activez Enable/Disable, cliquez sur Save et passez une commande de test.

6. Saisissez le nom d'utilisateur et le mot de passe de production du Klarna Merchant Portal, désactivez Test mode et choisissez le moment de capture des commandes (par défaut : à l'expédition).

À l'installation, le module crée deux statuts de commande : Awaiting Klarna fraud review et Klarna payment on hold. Aucun des deux ne compte comme payé et aucun n'envoie d'e-mail. PrestaShop propose un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Klarna Payments > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche TEST MODE: Klarna playground, no real payments. ou LIVE: real Klarna payments. Elle vous avertit lorsque le nom d'utilisateur ou le mot de passe du mode actif est manquant (Klarna est alors masqué à l'étape de paiement) et lorsque la devise par défaut de la boutique n'est pas vendue par Klarna dans la région d'API sélectionnée.

Klarna Payments

Enable/Disable : Enable Klarna Payments active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement que voit le client à l'étape de paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Klarna. Obligatoire.

Description : le texte affiché au client au-dessus du widget Klarna. Par défaut : Pay now, later or in instalments with Klarna.

Identifiants API

Les identifiants API Klarna (nom d'utilisateur et mot de passe) se créent dans le Klarna Merchant Portal (portal.klarna.com) sous Settings > Klarna API credentials. Les identifiants de test proviennent du portail de l'environnement de test : playground.eu.portal.klarna.com pour l'Europe, playground.us.portal.klarna.com pour l'Amérique du Nord et l'Océanie.

Test mode : utilise l'environnement de test Klarna (identifiants de test, aucun paiement réel). Par défaut : activé. Tant que le mode test est activé, le client voit TEST MODE: Klarna playground, no real payment is made. sous le moyen de paiement. Les commandes conservent l'environnement dans lequel elles ont été passées : les captures et remboursements des commandes de test utilisent toujours les identifiants de test.

API region : la région de votre compte marchand Klarna. Les clients ne peuvent payer avec Klarna que depuis les pays de cette région, dans la devise de leur pays. Le pays est pris dans l'adresse de facturation du panier.

Europe : Autriche, Belgique, Finlande, France, Allemagne, Grèce, Irlande, Italie, Pays-Bas, Portugal, Slovaquie et Espagne (EUR), Suède (SEK), Norvège (NOK), Danemark (DKK), Royaume-Uni (GBP), Suisse (CHF), Pologne (PLN), République tchèque (CZK), Hongrie (HUF), Roumanie (RON). Par défaut.

North America (US, CA, MX) : États-Unis (USD), Canada (CAD), Mexique (MXN).

Oceania (AU, NZ) : Australie (AUD), Nouvelle-Zélande (NZD).

Live username (UID) : le nom d'utilisateur de l'API de production, par exemple PK12345_abcdef012345.

Live password : le mot de passe de l'API de production (secret partagé).

Test username (UID) : le nom d'utilisateur de l'API de l'environnement de test.

Test password : le mot de passe de l'API de l'environnement de test (secret partagé).

Les mots de passe enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Clear saved passwords : cochez un mot de passe et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Gestion des commandes

Une commande Klarna passée est une autorisation : le client n'est débité qu'au moment de la capture de la commande. Les autorisations non capturées expirent, généralement après 28 jours. Expédiez donc les commandes à temps ou utilisez la capture automatique.

Capture : moment où le client est débité. Les remboursements ne sont possibles que pour les montants capturés.

When the order is shipped (recommended) : capture lorsque vous passez la commande à un statut d'expédition, comme Shipped ou Delivered (par défaut). Le montant capturé correspond au total de la commande moins ce qui a déjà été capturé, sans dépasser le montant encore autorisé. Si la capture échoue, le statut ne change pas et la raison s'affiche sur la page de commande.

Immediately (auto capture) : débite le client tout de suite, pour les biens numériques ou les services.

Manually in the Klarna portal : le module ne capture pas. Capturez la commande dans le Klarna Merchant Portal.

Cancellation : Cancel the Klarna order (release the authorization) when a not yet captured order is Cancelled. Par défaut : activé.

Notifications

Klarna transmet le résultat d'un contrôle antifraude (commandes enregistrées comme « pending ») à l'adresse indiquée dans Notification URL. Avec les URL personnalisées, elle ressemble à https://your-shop/module/wcp_klarna_payment/notification, éventuellement avec un code de langue comme /en/. L'URL est transmise automatiquement avec chaque commande : vous n'avez rien à configurer chez Klarna. Le contenu de la notification n'est jamais considéré comme fiable : chaque notification est vérifiée auprès de l'API Klarna Order Management, avec les identifiants de l'environnement et de la région dans lesquels la commande a été passée, et la commande Klarna doit se rapporter au panier de cette boutique. Le module agit selon ce que Klarna signale :

ACCEPTED : Klarna a accepté l'achat. La commande est marquée payée après contrôle du montant et de la devise.

REJECTED or STOPPED : l'achat n'a pas passé le contrôle antifraude. La commande passe au statut Payment error.

Klarna order CANCELLED, EXPIRED or CLOSED : le client n'a pas été débité. La commande est annulée.

Si Klarna accepte un achat après que vous avez annulé ou remboursé la commande, la commande n'est pas rouverte et l'autorisation Klarna est libérée. La notification fonctionne lorsque la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique.

Avancé

Debug log : consigne les appels API et les événements de paiement dans logs/wc_kl_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours consignées. Le journal ne contient jamais d'identifiants, de jetons d'autorisation ni de données clients. Par défaut : désactivé.

Log : affiche la taille et les dernières entrées du journal, avec un bouton pour le vider.

Uninstall : supprime les réglages du module et le journal lors de la désinstallation du module. Les données de commande (identifiants de commandes Klarna, remboursements) sont toujours conservées. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Klarna, avec le logo Klarna), et le widget Klarna se charge dans l'étape de paiement. Le module crée la session Klarna à partir du panier, côté serveur. Dans le widget, le client choisit de payer maintenant, plus tard ou en plusieurs fois, selon les options proposées par Klarna. Lorsque le client passe commande, la session Klarna est d'abord mise à jour avec le panier définitif, puis Klarna autorise l'achat dans le widget. Le module crée ensuite la commande Klarna côté serveur, avec les lignes de commande, les totaux et les adresses du panier. Les remises du panier sont envoyées à Klarna sous forme de ligne distincte. Aucune commande n'existe avant la réponse de Klarna.

Le résultat dépend du statut antifraude Klarna :

ACCEPTED : la commande est créée avec le statut Payment accepted et le client voit la page standard de confirmation de commande. Le montant est autorisé, puis capturé selon le réglage Capture.

PENDING : la commande est créée avec le statut Awaiting Klarna fraud review jusqu'à l'arrivée de la notification de Klarna. Ne l'expédiez pas avant.

REJECTED : aucune commande n'est créée. Le client reste à l'étape de paiement avec le message Klarna could not approve this purchase. Please choose another payment method.

Si Klarna ne peut pas accepter la commande, le client reste à l'étape de paiement avec un court message, par exemple 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. ou, lorsque l'autorisation a expiré, une invitation à cliquer de nouveau sur « Place order ». Les détails sont inscrits dans le journal. Si le pays et la devise du client ne correspondent à aucun marché Klarna de votre région, le client voit Klarna is not available for your billing country and currency. Please choose another payment method.

Un double clic ne crée jamais une seconde commande Klarna pour le même panier. Si le panier change pendant que Klarna répond, par exemple dans un autre onglet du navigateur, la commande est créée avec le statut Klarna payment on hold et une note. Si Klarna a approuvé l'achat mais que la commande n'a pas pu être créée, le client voit Your Klarna purchase was approved, but the order could not be completed automatically. Please contact us — do not pay again. La tentative suivante ou la notification de Klarna crée la commande à partir de la commande Klarna enregistrée, sans nouvelle autorisation.

La commande Klarna dans le Klarna Merchant Portal porte le numéro de panier comme référence marchande, car la commande PrestaShop n'existe pas encore lorsqu'elle est passée.

Le module ne propose pas Klarna Checkout (KCO, qui remplace tout le paiement), les boutons Klarna Express Checkout, On-site messaging ou Sign in with Klarna, ni les abonnements ou moyens de paiement enregistrés, ni les captures partielles par ligne de commande. Les lignes de commande ne sont pas renvoyées à Klarna lorsque vous modifiez une commande après l'avoir passée.

Commandes et remboursements

Order statuses

No order yet : le client n'a pas terminé l'autorisation Klarna, ou Klarna a refusé l'achat. Seul le panier existe.

Payment accepted : Klarna a accepté l'achat. Le paiement est enregistré avec l'identifiant de commande Klarna comme identifiant de transaction, et une note privée indique l'identifiant de commande Klarna et le moment de la capture.

Awaiting Klarna fraud review : l'achat attend le contrôle antifraude de Klarna. La notification de Klarna fait passer la commande au statut Payment accepted, Payment error ou Canceled.

Klarna payment on hold : Klarna a renvoyé un statut antifraude inattendu, ou le montant ou la devise signalés par Klarna ne correspondent pas à la commande. La note l'explique. Vérifiez la commande dans le Klarna Merchant Portal.

Payment error : Klarna a refusé ou arrêté l'achat après le contrôle antifraude. N'expédiez pas la commande.

Canceled : vous avez annulé la commande, ou Klarna signale la commande Klarna comme annulée, expirée ou fermée. Avec Cancellation activé, l'annulation d'une commande non encore capturée annule aussi la commande Klarna et libère l'autorisation, de sorte que le client n'est pas débité. Une commande déjà capturée n'est pas annulée chez Klarna : remboursez-la pour restituer l'argent.

Refunded : le montant capturé a été entièrement remboursé par l'intermédiaire du module.

Capture

Avec When the order is shipped, passer la commande à un statut d'expédition capture le total de la commande avant l'enregistrement du nouveau statut. Si Klarna refuse la capture, par exemple parce que le total de la commande a dépassé le montant autorisé après une modification, le statut ne change pas, aucun e-mail n'est envoyé, et la raison s'affiche sur la page de commande et dans une note : le client n'a PAS été débité. Corrigez le problème et changez de nouveau le statut pour réessayer, ou capturez dans le Klarna Merchant Portal et passez Capture en manuel. Sous PrestaShop 8 en mode production, le back-office peut enregistrer le statut quand même ; le module définit alors Klarna payment on hold à la place, avec une note, afin que la commande ne soit jamais affichée comme expédiée sans capture. Une capture réussie ajoute une note avec le montant capturé et l'identifiant de la capture.

Bloc Klarna payment

La page de commande affiche un bloc Klarna payment avec l'identifiant de commande Klarna, son environnement et sa région, un badge Playground pour les commandes de test, le statut antifraude et le statut Klarna, le montant autorisé, les montants capturé et remboursé, ainsi que l'historique des remboursements.

Remboursements

Dans le bloc Klarna payment, saisissez le montant (le montant non encore remboursé est prérempli), facultativement un motif, puis cliquez sur Refund via Klarna. Confirmez la question Refund this amount through Klarna? This cannot be undone. Les remboursements totaux et partiels sont possibles pour les montants capturés, dans la limite de ce que Klarna indique comme capturé moins ce qui a déjà été remboursé. Vous devez avoir le droit de modifier les commandes ; l'accès aux modules n'est pas nécessaire. Le remboursement est envoyé à l'environnement et à la région dans lesquels la commande a été passée, les identifiants de cet environnement doivent donc être renseignés. Si Klarna n'accepte pas le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant de remboursement Klarna. Un remboursement total passe la commande au statut Refunded ; un remboursement partiel ne modifie pas le statut. Un remboursement relancé n'est jamais effectué deux fois.

Une commande non encore capturée ne peut pas être remboursée : annulez-la à la place pour libérer l'autorisation. Avec Capture en manuel, la boutique ne sait pas ce que vous avez capturé dans le Klarna Merchant Portal. Le formulaire de remboursement s'affiche alors avec un montant vide, et Klarna vérifie le montant lors de l'envoi.

Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Klarna. Les remboursements effectués dans le Klarna Merchant Portal n'apparaissent pas dans le bloc, mais ils sont pris en compte dans le montant que Klarna autorise encore à rembourser.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Klarna Payments est le premier bloc de Modules > Module Manager > VibeFox Klarna Payments > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-klarna et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back-office (l'anglais et le russe sont inclus).

Si la clé n'est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d'une date. Après un changement d'adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : le domaine de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.

Sans clé active, Klarna n'est pas affiché aux clients à l'étape de paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : le moyen de paiement vous est donc masqué également. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester à l'étape de paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les notifications Klarna continuent d'être traitées, et les commandes peuvent toujours être capturées, annulées et remboursées.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. Désinstaller ou réinitialiser le module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Klarna n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable/Disable est activé et que les identifiants du mode actif sont renseignés : nom d'utilisateur et mot de passe de test en mode test, identifiants de production en mode production. La page de configuration affiche un avertissement lorsqu'ils manquent. Le pays de facturation du client doit être un pays Klarna de votre API region, et le client doit payer dans la devise de ce pays (par exemple, un client suédois doit payer en SEK). Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe de clients.

Le paiement a abouti, mais la commande reste en Awaiting Klarna fraud review : l'achat attend le contrôle antifraude de Klarna, et la commande est mise à jour à l'arrivée de la notification de Klarna. Vérifiez que votre boutique peut recevoir les requêtes de Klarna à la Notification URL affichée dans les réglages, et que les identifiants de l'environnement dans lequel la commande a été passée sont toujours renseignés. Activez Debug log et consultez le champ Log sur la page du module.

La notification répond Not configured : les identifiants de l'environnement (test ou production) dans lequel la commande a été passée sont absents, la notification ne peut donc pas être vérifiée. Renseignez-les. Klarna réessaie la notification.

La notification répond Verification failed : la commande Klarna n'a pas pu être lue depuis l'API Order Management. Klarna réessaie la notification.

La notification répond Busy : la commande était en cours de mise à jour par une autre requête au même moment. Klarna réessaie la notification.

La notification répond mismatch_ref ou Unknown order : la commande Klarna ne se rapporte pas au panier de cette boutique, ou le module ne la connaît pas. La commande n'est pas modifiée.

Le widget ne se charge pas : le client voit Klarna could not be loaded. Please try again or choose another payment method. ou Klarna is not available for this purchase. Vérifiez les identifiants du mode actif, ainsi que le pays et la devise du client.

Le passage au statut Shipped est refusé : la capture Klarna a échoué. Lisez la raison dans le bloc Klarna payment ou dans la note. Le total de la commande dépasse peut-être ce qui reste autorisé, la commande Klarna n'est peut-être pas encore acceptée, ou l'autorisation a peut-être expiré. Corrigez le problème et changez de nouveau le statut, ou capturez dans le Klarna Merchant Portal.

Le remboursement échoue : lisez le message dans le bloc. La commande n'est peut-être pas encore capturée (annulez-la à la place), le montant dépasse peut-être ce qui reste remboursable, ou les identifiants de l'environnement de la commande sont peut-être absents.

Le client voit This order is already being paid : une autre requête pour le même panier est en cours, par exemple un double clic. Patientez un instant et vérifiez si la commande a bien été créée.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Klarna Payments et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Uninstall est activé dans la section Advanced, les réglages du module, le journal et les sessions temporaires du widget sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les commandes et remboursements Klarna, ainsi que les statuts de commande Awaiting Klarna fraud review et Klarna payment on hold, sont toujours conservés : les commandes passées auparavant peuvent donc être capturées et remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Klarna est une marque déposée de son titulaire respectif. Ce module n'est ni affilié à Klarna ni approuvé par Klarna.