VibeFox Klarna for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé. Sans WooCommerce, l'extension refuse de s'activer.

PHP : 8.0 ou ultérieur.

HTTPS : Klarna exige HTTPS pour les paiements réels.

Compte marchand Klarna : vous avez besoin des identifiants API Klarna (nom d'utilisateur et mot de passe) de votre compte marchand pour une région d'API, ainsi que des identifiants de test du portail 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 de la boutique : 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_klarna_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Klarna Payments > Manage, ou cliquez sur Settings sous le nom de l'extension dans la page Extensions.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. Choisissez la API region de votre compte marchand Klarna.

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

7. Saisissez le nom d'utilisateur et le mot de passe de production du Klarna Merchant Portal, décochez Test mode et choisissez le moment où les commandes sont capturées (par défaut : lorsque la commande est marquée comme Terminée).

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Klarna Payments. À côté du titre de la page, un badge affiche TEST MODE ou LIVE. La page vous avertit lorsque le nom d'utilisateur ou le mot de passe du mode actif est manquant (Klarna est alors masqué au paiement) et lorsque la devise de la boutique n'est pas vendue par Klarna dans la région d'API sélectionnée. Dans la liste des moyens de paiement, Klarna est signalé comme nécessitant une configuration tant que les identifiants du mode actif ne sont pas saisis, et affiche un badge de mode test tant que le mode test est activé.

Général

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 au paiement. Par défaut : Klarna.

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) sont créés dans le Klarna Merchant Portal (portal.klarna.com) sous Settings > Klarna API credentials. Les identifiants de test proviennent du portail 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: Use the Klarna playground (test credentials, no real payments). Par défaut : activé. Tant que le mode test est activé, le paiement affiche TEST MODE: Klarna playground, no real payment is made. 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.

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 API de production, par exemple PK12345_abcdef012345.

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

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

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

Gestion des commandes

Une commande Klarna passée est une autorisation : le client n'est débité que lorsque la commande est capturée. Les autorisations non capturées expirent, généralement au bout de 28 jours : terminez (expédiez) 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. Si une capture échoue, la commande est mise en attente avec une note.

When the order is Completed (recommended): capture à l'expédition en marquant la commande comme Terminée (par défaut). Le montant capturé correspond au total de la commande moins ce qui a déjà été capturé, sans jamais dépasser le montant encore autorisé.

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

Manually in the Klarna portal: le plugin 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'URL de notification affichée dans cette section. Elle ressemble à ceci : https://your-site/wc-api/wc_kl_payment/. L'URL est envoyée automatiquement avec chaque commande, il n'y a donc rien à configurer chez Klarna. Le contenu de la notification n'est jamais considéré comme fiable : chaque notification est vérifiée avec la Order Management API de Klarna, et la commande Klarna doit renvoyer à cette commande de la boutique. L'extension agit selon ce que Klarna indique :

ACCEPTED: Klarna a accepté l'achat. La commande est marquée comme 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 en échec.

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.

Avancé

Debug log: Log API calls and payment events dans WooCommerce > Status > Logs, source wcp_klarna_payment. Les erreurs sont toujours journalisées. Les journaux ne contiennent jamais d'identifiants ni de données clients. Par défaut : désactivé.

Uninstall: Delete the plugin settings and logs when the plugin is deleted. Les données de commande (identifiants de commande Klarna) sont toujours conservées. Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Klarna) et le widget Klarna se charge dans le paiement. Il y choisit de payer maintenant, plus tard ou en plusieurs fois, selon les options proposées par Klarna. Lorsque le client clique sur « Passer la commande », Klarna autorise l'achat dans le widget. Dans le bloc Paiement, la session Klarna est d'abord mise à jour avec le panier final, afin que les modifications ultérieures de la livraison ou des totaux n'amènent pas Klarna à refuser la commande. L'extension crée ensuite la commande Klarna côté serveur, avec les lignes, les totaux et les adresses de la commande WooCommerce.

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

ACCEPTED: la commande est immédiatement marquée comme payée et le client accède à la page Commande reçue. Le montant est autorisé et capturé selon Capture.

PENDING: la commande est mise en attente jusqu'à l'arrivée de la notification de Klarna. Ne l'expédiez pas avant.

REJECTED: la commande passe en échec et le client voit Klarna could not approve this purchase. Please choose another payment method.

Si Klarna ne peut pas accepter la commande, le client voit un bref 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 demande de cliquer à nouveau sur « Passer la commande ». Les détails sont ajoutés aux notes de commande et au journal. Si le pays de facturation 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.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec le stockage des commandes haute performance de WooCommerce (HPOS).

L'extension ne comprend pas Klarna Checkout (KCO, remplacement complet du paiement), les boutons Klarna Express Checkout, On-site messaging ni 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 son passage.

Commandes et remboursements

Statuts de commande

Processing or Completed: Klarna a accepté l'achat. WooCommerce applique le statut habituel d'une commande payée. La note de commande indique l'identifiant de commande Klarna et le moment de la capture. L'identifiant de transaction est l'identifiant de commande Klarna. Lorsque la commande est capturée, une note indique le montant capturé et l'identifiant de capture.

On hold: l'achat est en attente de contrôle antifraude, Klarna a renvoyé un statut antifraude inattendu, le montant ou la devise indiqués par Klarna ne correspondaient pas à la commande, ou une capture a échoué. Les notes de commande indiquent le cas.

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

Cancelled: vous avez annulé la commande, ou Klarna signale la commande Klarna comme annulée, expirée ou close. Avec Cancellation activé, l'annulation d'une commande non encore capturée annule 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.

Capture

Avec When the order is Completed, marquer la commande comme Terminée capture le total de la commande. Si la capture échoue, par exemple parce que le total de la commande a dépassé le montant autorisé après une modification, la commande est mise en attente avec une note indiquant que le client n'a PAS été débité, et le client ne reçoit pas l'e-mail « Commande terminée ». Corrigez le problème et marquez à nouveau la commande comme Terminée pour réessayer, ou capturez dans le Klarna Merchant Portal.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Klarna Payments. Les remboursements totaux et partiels sont pris en charge pour les montants capturés, dans la limite du montant capturé moins ce qui a déjà été remboursé. 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, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande avec l'identifiant de remboursement Klarna. Un remboursement relancé n'est jamais effectué deux fois.

Une commande non encore capturée ne peut pas être remboursée : annulez-la pour libérer l'autorisation. Les remboursements effectués dans le Klarna Merchant Portal ne sont pas synchronisés avec WooCommerce.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Klarna Payments. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site 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 au paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires de la boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Extensions et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les notifications continuent d'être traitées, et les captures, annulations et remboursements fonctionnent toujours.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Klarna n'apparaît pas au 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. 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).

Le paiement a abouti, mais la commande reste On hold : le paiement est en attente du contrôle antifraude de Klarna, et la commande est mise à jour dès l'arrivée de la notification de Klarna. Vérifiez que votre site peut recevoir les requêtes de Klarna à l'URL de notification 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. Consultez WooCommerce > Status > Logs, source wcp_klarna_payment.

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.

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

La notification répond mismatch_ref : la commande Klarna ne renvoie pas à cette commande de la boutique. 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.

Échec de la capture, commande On hold : lisez la note de commande. 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 marquez à nouveau la commande comme Terminée, ou capturez dans le Klarna Merchant Portal.

Échec du remboursement : lisez le message. La commande n'est peut-être pas encore capturée (annulez-la plutôt), le montant dépasse peut-être ce qui peut encore être remboursé, ou les identifiants de l'environnement de la commande sont peut-être absents.

Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle et les journaux (source wcp_klarna_payment) ne sont supprimés que si Uninstall (Delete the plugin settings and logs when the plugin is deleted) était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Klarna est une marque appartenant à son titulaire respectif. Cette extension n'est ni affiliée à Klarna ni approuvée par Klarna.