VibeFox Klarna for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

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

Valuta: 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: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox Klarna Payments nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e fai clic su Activate (vedi Chiave di licenza).

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

5. Inserisci nome utente e password di test dal portale playground di Klarna, lascia attivo Test mode, attiva Enable/Disable, fai clic su Save ed effettua un ordine di prova.

6. Inserisci nome utente e password live dal Klarna Merchant Portal, disattiva Test mode e scegli quando vengono acquisiti gli ordini (predefinito: alla spedizione).

All'installazione il modulo crea due stati dell'ordine: Awaiting Klarna fraud review e Klarna payment on hold. Nessuno dei due conta come pagato né invia un'e-mail. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Klarna Payments > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra TEST MODE: Klarna playground, no real payments. oppure LIVE: real Klarna payments. Avvisa quando mancano nome utente o password della modalità attiva (in tal caso Klarna è nascosto al checkout) e quando la valuta predefinita del negozio non è venduta da Klarna nella regione API selezionata.

Klarna Payments

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

Title: il nome del metodo di pagamento che il cliente vede al pagamento. È anche il nome del metodo di pagamento memorizzato nell'ordine. Predefinito: Klarna. Obbligatorio.

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 playground: playground.eu.portal.klarna.com per l'Europa, playground.us.portal.klarna.com per il Nord America e l'Oceania.

Test mode: usa il playground di Klarna (credenziali di test, nessun pagamento reale). Predefinito: attivo. Mentre la modalità test è attiva, il cliente vede TEST MODE: Klarna playground, no real payment is made. sotto il metodo di pagamento. 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. Il paese viene preso dall'indirizzo di fatturazione del carrello.

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 del playground.

Test password: la password API del playground (segreto condiviso).

Le password salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

Clear saved passwords: seleziona una password e fai clic su Save per eliminarla. Un campo vuoto mantiene il valore salvato.

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 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.

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

Notifiche

Klarna comunica l'esito della verifica antifrode (ordini inviati come "pending") all'indirizzo mostrato in Notification URL. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_klarna_payment/notification, eventualmente con un codice lingua come /en/. L'URL viene inviato automaticamente con ogni ordine, quindi non c'è nulla da configurare in Klarna. Il contenuto della notifica non è mai considerato attendibile: ogni notifica viene verificata con la Klarna Order Management API, usando le credenziali dell'ambiente e della regione in cui è stato effettuato l'ordine, e l'ordine Klarna deve riferirsi al carrello di questo negozio. Il modulo 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. La notifica funziona mentre il negozio è in modalità manutenzione e non è bloccata dalla restrizione per paese del negozio.

Avanzate

Debug log: registra le chiamate API e gli eventi di pagamento in logs/wc_kl_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati. Il registro non contiene mai credenziali, token di autorizzazione o dati dei clienti. Predefinito: disattivato.

Log: mostra la dimensione e le ultime voci del registro, con un pulsante per svuotarlo.

Uninstall: alla disinstallazione del modulo elimina le impostazioni del modulo e il registro. I dati degli ordini (ID ordini Klarna, rimborsi) vengono sempre conservati. Predefinito: disattivato.

Checkout

Al passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Klarna, con il badge Klarna) e il widget Klarna si carica all'interno del passaggio di pagamento. Il modulo crea la sessione Klarna dal carrello sul server. Nel widget il cliente sceglie pagamento immediato, differito o a rate, come li offre Klarna. Quando il cliente effettua l'ordine, la sessione Klarna viene prima aggiornata con il carrello definitivo, e Klarna autorizza l'acquisto nel widget. Il modulo crea poi l'ordine Klarna lato server con le righe, i totali e gli indirizzi del carrello. Gli sconti del carrello vengono inviati a Klarna come riga separata. Nessun ordine esiste prima della risposta di Klarna.

Il risultato dipende dallo stato antifrode di Klarna:

Se Klarna non può accettare l'ordine, il cliente resta al checkout con 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, l'invito a fare di nuovo clic su "Place order". I dettagli vengono scritti nel registro. Se il paese e la valuta di fatturazione 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 doppio clic non crea mai un secondo ordine Klarna per lo stesso carrello. Se il carrello cambia mentre Klarna risponde, per esempio in un'altra scheda del browser, l'ordine viene creato come Klarna payment on hold con una nota. Se Klarna ha approvato l'acquisto ma l'ordine non ha potuto essere creato, il cliente vede Your Klarna purchase was approved, but the order could not be completed automatically. Please contact us — do not pay again. Il tentativo successivo o la notifica di Klarna crea l'ordine dall'ordine Klarna memorizzato, senza una nuova autorizzazione.

L'ordine Klarna nel Klarna Merchant Portal riporta il numero del carrello come riferimento commerciante, perché l'ordine PrestaShop non esiste ancora quando viene effettuato.

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

Ordini e rimborsi

Order statuses

No order yet: il cliente non ha completato l'autorizzazione Klarna, oppure Klarna ha rifiutato l'acquisto. Esiste solo il carrello.

Payment accepted: Klarna ha accettato l'acquisto. Il pagamento viene registrato con l'ID dell'ordine Klarna come ID transazione, e una nota privata mostra l'ID dell'ordine Klarna e quando verrà acquisito.

Awaiting Klarna fraud review: l'acquisto è in attesa della verifica antifrode di Klarna. La notifica di Klarna sposta l'ordine su Payment accepted, Payment error o Canceled.

Klarna payment on hold: Klarna ha restituito uno stato antifrode inatteso, oppure l'importo o la valuta segnalati da Klarna non corrispondono all'ordine. La nota lo spiega. Controlla l'ordine nel Klarna Merchant Portal.

Payment error: Klarna ha rifiutato o bloccato l'acquisto dopo la verifica antifrode. Non spedire l'ordine.

Canceled: hai annullato l'ordine, oppure Klarna segnala l'ordine Klarna come annullato, scaduto o chiuso. Con Cancellation attivo, annullare un ordine non ancora acquisito annulla anche l'ordine Klarna e rilascia l'autorizzazione, così il cliente non viene addebitato. Un ordine già acquisito non viene annullato su Klarna: rimborsalo per restituire il denaro.

Refunded: l'importo acquisito è stato rimborsato interamente tramite il modulo.

Capture

Con When the order is shipped, portare l'ordine a uno stato di spedizione acquisisce il totale dell'ordine prima del salvataggio del nuovo stato. Se Klarna rifiuta l'acquisizione, per esempio perché il totale dell'ordine ha superato l'importo autorizzato dopo una modifica, lo stato non cambia, non viene inviata alcuna e-mail e il motivo viene mostrato nella pagina dell'ordine e in una nota: il cliente NON è stato addebitato. Risolvi il problema e cambia di nuovo lo stato per riprovare, oppure acquisisci nel Klarna Merchant Portal e imposta Capture su manuale. Su PrestaShop 8 in modalità produzione il back office potrebbe salvare comunque lo stato; in tal caso il modulo imposta invece Klarna payment on hold con una nota, così l'ordine non risulta mai spedito senza acquisizione. Un'acquisizione riuscita aggiunge una nota con l'importo acquisito e l'ID dell'acquisizione.

Blocco Klarna payment

La pagina dell'ordine mostra un blocco Klarna payment con l'ID dell'ordine Klarna, il suo ambiente e la sua regione, un badge Playground per gli ordini di test, lo stato antifrode e lo stato Klarna, l'importo autorizzato, gli importi acquisito e rimborsato e lo storico dei rimborsi.

Rimborsi

Nel blocco Klarna payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Klarna. Conferma la domanda Refund this amount through Klarna? This cannot be undone. Sono supportati rimborsi totali e parziali per gli importi acquisiti, fino a quanto Klarna indica come acquisito meno quanto già rimborsato. Ti serve il permesso di modificare gli ordini; l'accesso ai moduli non è necessario. Il rimborso viene inviato all'ambiente e alla regione in cui è stato effettuato l'ordine, quindi devono essere impostate le credenziali di quell'ambiente. Se Klarna non accetta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note, con l'ID del rimborso Klarna. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale non cambia lo stato. Un rimborso ripetuto non viene mai eseguito due volte.

Un ordine non ancora acquisito non può essere rimborsato: annullalo, per rilasciare l'autorizzazione. Con Capture impostato su manuale, il negozio non sa cosa hai acquisito nel Klarna Merchant Portal. Il modulo di rimborso viene mostrato con l'importo vuoto, e Klarna verifica l'importo quando lo invii.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Klarna. I rimborsi effettuati nel Klarna Merchant Portal non vengono aggiunti al blocco, ma contano nell'importo che Klarna consente ancora di rimborsare.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Klarna Payments è il primo blocco della pagina Modules > Module Manager > VibeFox Klarna Payments > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo, il blocco mostra la chiave mascherata, lo stato (per esempio la data fino alla quale la licenza è attiva e il tuo dominio) e i pulsanti Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto compaiono la riga Product: presta-payment-klarna e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono modificare la chiave. I testi del blocco seguono la lingua del back office (sono inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo un cambio di indirizzo del negozio, o dopo aver liberato un posto dominio nel tuo account, fai clic su Check now. Se il server delle licenze non è raggiungibile, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Klarna non viene mostrato ai clienti al checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non sono interessati: le notifiche Klarna continuano a essere elaborate, e gli ordini possono ancora essere acquisiti, annullati e rimborsati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Klarna non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che le credenziali della modalità attiva siano compilate: nome utente e password di test in modalità test, quelle live in modalità live. La pagina delle impostazioni mostra un avviso quando mancano. 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 svedese deve pagare in SEK). In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo clienti.

Il pagamento è andato a buon fine, ma l'ordine resta in Awaiting Klarna fraud review: l'acquisto è in attesa della verifica antifrode di Klarna, e l'ordine viene aggiornato quando arriva la notifica di Klarna. Verifica che il tuo negozio possa ricevere le richieste di Klarna all'indirizzo Notification URL mostrato nelle impostazioni, e che le credenziali dell'ambiente in cui è stato effettuato l'ordine siano ancora inserite. Attiva Debug log e controlla il campo Log nella pagina del modulo.

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. Klarna ritenta la notifica.

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

La notifica risponde Busy: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. Klarna ritenta la notifica.

La notifica risponde mismatch_ref o Unknown order: l'ordine Klarna non si riferisce al carrello di questo negozio, oppure il modulo non lo conosce. 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 della modalità attiva e il paese e la valuta del cliente.

Il cambio di stato a Shipped viene rifiutato: l'acquisizione Klarna non è riuscita. Leggi il motivo nel blocco Klarna payment o nella nota. 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 il problema e cambia di nuovo lo stato, oppure acquisisci nel Klarna Merchant Portal.

Il rimborso non riesce: leggi il messaggio nel blocco. L'ordine potrebbe non essere ancora acquisito (in tal caso annullalo), l'importo potrebbe superare quanto ancora rimborsabile, oppure potrebbero mancare le credenziali dell'ambiente dell'ordine.

Il cliente vede This order is already being paid: è in corso un'altra richiesta per lo stesso carrello, per esempio un doppio clic. Attendi un momento e verifica se l'ordine è stato creato.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Klarna Payments e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Uninstall è attivo nella sezione Advanced, vengono rimosse le impostazioni del modulo, il registro e le sessioni temporanee del widget. Se è disattivato, tutte le impostazioni vengono conservate per una successiva reinstallazione. Gli ordini e i rimborsi Klarna e gli stati dell'ordine Awaiting Klarna fraud review e Klarna payment on hold vengono sempre conservati, quindi gli ordini effettuati prima possono essere acquisiti e rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID delle transazioni.

Klarna è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Klarna né approvato da Klarna.