VibeFox Klarna for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Senza WooCommerce il plugin non si attiva.

PHP: 8.0 o successivo.

HTTPS: Klarna richiede HTTPS per i pagamenti reali.

Account commerciante Klarna: ti servono le credenziali API Klarna (nome utente e password) del tuo account commerciante per una regione API, e le credenziali di test del portale di test Klarna (vedi Configurazione). Ogni regione API ha le proprie credenziali. È possibile usare un solo account commerciante (una regione API) per negozio.

Valuta del negozio: una valuta Klarna della tua regione: EUR, SEK, NOK, DKK, GBP, CHF, PLN, CZK, HUF o RON in Europa; USD, CAD o MXN in Nord America; AUD o NZD in Oceania.

Chiave di licenza VibeFox: acquistabile su vibefox.net. Una chiave funziona su un dominio.

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. In alternativa puoi caricare la cartella wcp_klarna_payment in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Klarna Payments > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Scegli la API region del tuo account commerciante Klarna.

6. Inserisci nome utente e password di test del portale di test Klarna, lascia attivo Test mode, attiva Enable/Disable ed effettua un ordine di prova.

7. Inserisci nome utente e password live del Klarna Merchant Portal, deseleziona Test mode e scegli quando gli ordini vengono acquisiti (predefinito: quando l'ordine viene segnato come Completato).

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Klarna Payments. Accanto al titolo della pagina compare un badge con TEST MODE o LIVE. La pagina ti avvisa quando nome utente o password del modo attivo mancano (in tal caso Klarna è nascosto nel checkout) e quando la valuta del negozio non è venduta da Klarna nella regione API selezionata. Nell'elenco dei metodi di pagamento, Klarna è segnato come da configurare finché non vengono inserite le credenziali del modo attivo, e mostra un badge di modalità test finché la modalità test è attiva.

Generale

Enable/Disable: Enable Klarna Payments attiva o disattiva il metodo di pagamento. Predefinito: disattivo.

Title: il nome del metodo di pagamento che il cliente vede nel checkout. Predefinito: Klarna.

Description: il testo mostrato al cliente sopra il widget Klarna. Predefinito: Pay now, later or in instalments with Klarna.

Credenziali API

Le credenziali API Klarna (nome utente e password) si creano nel Klarna Merchant Portal (portal.klarna.com) in Settings > Klarna API credentials. Le credenziali di test provengono dal portale di test: playground.eu.portal.klarna.com per l'Europa, playground.us.portal.klarna.com per Nord America e Oceania.

Test mode: Use the Klarna playground (test credentials, no real payments). Predefinito: attivo. Mentre la modalità test è attiva, il checkout mostra TEST MODE: Klarna playground, no real payment is made. Gli ordini mantengono l'ambiente in cui sono stati effettuati: acquisizioni e rimborsi degli ordini di test usano sempre le credenziali di test.

API region: la regione del tuo account commerciante Klarna. I clienti possono pagare con Klarna solo dai paesi di questa regione, nella valuta del proprio paese.

Live username (UID): il nome utente API di produzione, per esempio PK12345_abcdef012345.

Live password: la password API di produzione (segreto condiviso).

Test username (UID): il nome utente API dell'ambiente di test.

Test password: la password API dell'ambiente di test (segreto condiviso).

Gestione degli ordini

Un ordine Klarna effettuato è un'autorizzazione: il cliente viene addebitato solo quando l'ordine viene acquisito. Le autorizzazioni non acquisite scadono, di solito dopo 28 giorni, quindi evadi (spedisci) gli ordini in tempo oppure usa l'acquisizione automatica.

Capture: quando il cliente viene addebitato. I rimborsi sono possibili solo per gli importi acquisiti. Se un'acquisizione non riesce, l'ordine viene messo in sospeso con una nota.

Cancellation: Cancel the Klarna order (release the authorization) when a not yet captured order is Cancelled. Predefinito: attivo.

Notifiche

Klarna comunica l'esito di una verifica antifrode (ordini registrati come "pending") all'URL di notifica mostrato in questa sezione. Ha questo aspetto: https://your-site/wc-api/wc_kl_payment/. L'URL viene inviato automaticamente con ogni ordine, quindi non c'è nulla da configurare in Klarna. Il contenuto della notifica non viene mai considerato attendibile: ogni notifica viene verificata con la Order Management API di Klarna, e l'ordine Klarna deve riferirsi a questo ordine del negozio. Il plugin agisce in base a quanto comunica Klarna:

Se Klarna accetta un acquisto dopo che hai annullato o rimborsato l'ordine, l'ordine non viene riaperto e l'autorizzazione Klarna viene rilasciata.

Avanzate

Debug log: Log API calls and payment events in WooCommerce > Status > Logs, origine wcp_klarna_payment. Gli errori vengono sempre registrati. I log non contengono mai credenziali o dati dei clienti. Predefinito: disattivo.

Uninstall: Delete the plugin settings and logs when the plugin is deleted. I dati degli ordini (ID ordine Klarna) vengono sempre conservati. Predefinito: disattivo.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Klarna) e il widget Klarna si carica nel checkout. Lì il cliente sceglie se pagare subito, dopo o a rate, come proposto da Klarna. Quando il cliente fa clic su "Effettua ordine", Klarna autorizza l'acquisto nel widget. Nel blocco Checkout la sessione Klarna viene prima aggiornata con il carrello finale, così che modifiche successive di spedizione o totali non portino Klarna a rifiutare l'ordine. Il plugin crea poi l'ordine Klarna lato server con righe, totali e indirizzi dell'ordine WooCommerce.

Il risultato dipende dallo stato antifrode di Klarna:

Se Klarna non può accettare l'ordine, il cliente vede un breve messaggio, per esempio 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. oppure, quando l'autorizzazione è scaduta, una richiesta di fare di nuovo clic su "Effettua ordine". I dettagli vengono aggiunti alle note dell'ordine e al log. Se il paese di fatturazione e la valuta del cliente non corrispondono a un mercato Klarna della tua regione, il cliente vede Klarna is not available for your billing country and currency. Please choose another payment method.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).

Il plugin non prevede Klarna Checkout (KCO, sostituzione completa del checkout), pulsanti Klarna Express Checkout, On-site messaging né Sign in with Klarna, né abbonamenti o metodi di pagamento salvati, né acquisizioni parziali per riga d'ordine. Le righe d'ordine non vengono inviate di nuovo a Klarna quando modifichi un ordine dopo che è stato effettuato.

Ordini e rimborsi

Stati dell'ordine

Processing or Completed: Klarna ha accettato l'acquisto. WooCommerce imposta lo stato usuale per un ordine pagato. La nota dell'ordine mostra l'ID dell'ordine Klarna e quando verrà acquisito. L'ID transazione è l'ID dell'ordine Klarna. Quando l'ordine viene acquisito, una nota mostra l'importo acquisito e l'ID dell'acquisizione.

On hold: l'acquisto è in attesa della verifica antifrode, Klarna ha restituito uno stato antifrode inatteso, l'importo o la valuta comunicati da Klarna non corrispondevano all'ordine, oppure un'acquisizione non è riuscita. Le note dell'ordine indicano quale.

Failed: Klarna ha rifiutato l'acquisto o lo ha interrotto dopo la verifica antifrode. Non spedire l'ordine.

Cancelled: hai annullato l'ordine, oppure Klarna comunica che l'ordine Klarna è annullato, scaduto o chiuso. Con Cancellation attivo, annullare un ordine non ancora acquisito annulla l'ordine Klarna e rilascia l'autorizzazione, quindi il cliente non viene addebitato. Un ordine già acquisito non viene annullato da Klarna: rimborsalo per restituire il denaro.

Acquisizione

Con When the order is Completed, segnare l'ordine come Completato acquisisce il totale dell'ordine. Se l'acquisizione non riesce, per esempio perché il totale dell'ordine ha superato l'importo autorizzato dopo una modifica, l'ordine viene messo in sospeso con una nota che indica che il cliente NON è stato addebitato, e il cliente non riceve l'e-mail "Ordine completato". Risolvi il problema e segna di nuovo l'ordine come Completato per riprovare, oppure acquisisci nel Klarna Merchant Portal.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Klarna Payments. Sono supportati rimborsi totali e parziali degli importi acquisiti, fino all'importo acquisito meno quanto già rimborsato. Il rimborso viene inviato all'ambiente e alla regione in cui l'ordine è stato effettuato, quindi devono essere impostate le credenziali di quell'ambiente. Se Klarna non accetta il rimborso, WooCommerce mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID del rimborso Klarna. Un rimborso ripetuto non viene mai eseguito due volte.

Un ordine non ancora acquisito non può essere rimborsato: annullalo per rilasciare l'autorizzazione. I rimborsi effettuati nel Klarna Merchant Portal non vengono sincronizzati con WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Klarna Payments. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un dominio. Rimuovere la chiave da un sito non libera il suo posto per il dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Klarna non viene mostrato ai clienti nel checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio con accesso vedono ancora il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Nella pagina Plugin e nelle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: le notifiche continuano a essere elaborate e acquisizioni, annullamenti e rimborsi continuano a funzionare.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Klarna non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che le credenziali del modo attivo siano compilate: nome utente e password di test in modalità test, quelle live in modalità live. Il paese di fatturazione del cliente deve essere un paese Klarna della tua API region, e il cliente deve pagare nella valuta di quel paese (per esempio un cliente dalla Svezia deve pagare in SEK).

Il pagamento è andato a buon fine, ma l'ordine resta On hold: l'acquisto è in attesa della verifica antifrode di Klarna, e l'ordine viene aggiornato quando arriva la notifica di Klarna. Verifica che il tuo sito possa ricevere richieste da Klarna all'URL di notifica mostrato nelle impostazioni, e che le credenziali dell'ambiente in cui è stato effettuato l'ordine siano ancora inserite. Controlla WooCommerce > Status > Logs, origine wcp_klarna_payment.

La notifica risponde Not configured: mancano le credenziali dell'ambiente (test o live) in cui è stato effettuato l'ordine, quindi la notifica non può essere verificata. Inseriscile.

La notifica risponde Verification failed: l'ordine Klarna non è stato letto dalla Order Management API. Klarna ripete la notifica.

La notifica risponde mismatch_ref: l'ordine Klarna non si riferisce a questo ordine del negozio. L'ordine non viene modificato.

Il widget non si carica: il cliente vede Klarna could not be loaded. Please try again or choose another payment method. oppure Klarna is not available for this purchase. Verifica le credenziali del modo attivo e il paese e la valuta del cliente.

Acquisizione non riuscita, ordine On hold: leggi la nota dell'ordine. Il totale dell'ordine potrebbe richiedere più di quanto ancora autorizzato, l'ordine Klarna potrebbe non essere ancora accettato, oppure l'autorizzazione potrebbe essere scaduta. Risolvi e segna di nuovo l'ordine come Completato, oppure acquisisci nel Klarna Merchant Portal.

Rimborso non riuscito: leggi il messaggio. L'ordine potrebbe non essere ancora acquisito (annullalo invece), l'importo potrebbe superare quanto ancora rimborsabile, oppure potrebbero mancare le credenziali dell'ambiente dell'ordine.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave sul nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i log (origine wcp_klarna_payment) vengono rimossi solo se Uninstall (Delete the plugin settings and logs when the plugin is deleted) era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.

Klarna è un marchio del rispettivo titolare. Questo plugin non è affiliato a Klarna né approvato da Klarna.