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

Valuta: USD (Ecuador) o COP (Colombia). Per i carrelli in altre valute il metodo di pagamento viene nascosto nel checkout.

HTTPS: Kushki richiede che il checkout sia servito tramite HTTPS in modalità live.

Account Kushki: ti servono i Merchant ID pubblici e privati del tuo account di test (UAT) Kushki e del tuo account di produzione. Si trovano nella Kushki Console alla voce Developers > Credentials. Per il webhook facoltativo ti serve anche la chiave di firma del webhook di ciascun account (vedi Configurazione).

VibeFox license key: acquistabile su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

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

2. Al termine del caricamento, clicca su Configure, oppure trova più tardi VibeFox Kushki Payment nell'elenco dei moduli e clicca su Configure.

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

4. Inserisci i Merchant ID pubblici e privati di test e lascia attiva la voce Test mode. Facoltativamente, configura il webhook nella Kushki Console e incolla la sua chiave di firma (vedi Configurazione).

5. Attiva Enable / Disable, clicca su Save ed effettua un ordine di prova. Quando sei pronto, inserisci i Merchant ID live (e la firma del webhook live) e disattiva Test mode.

All'installazione il modulo crea lo stato dell'ordine Kushki payment on hold. PrestaShop assegna un nuovo modulo di pagamento alle valute, ai paesi e ai gruppi di clienti del tuo negozio. In Payment > Preferences verifica che il modulo sia consentito per USD o COP e per Ecuador o Colombia.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Kushki Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando il metodo di pagamento è attivo ma mancano i Merchant ID della modalità corrente (in tal caso il metodo di pagamento viene nascosto nel checkout), quando la valuta predefinita del tuo negozio non è USD o COP, quando la modalità live viene usata senza HTTPS e quando la modalità corrente non ha una firma del webhook. Finché la modalità test è attiva, mostra Modalità test attiva: viene usato l'ambiente di test di Kushki, non viene addebitato denaro reale. Se salvi con il metodo di pagamento attivo ma senza i Merchant ID della modalità corrente, le impostazioni vengono salvate e un messaggio ti ricorda di inserirli. Gli spazi attorno agli ID vengono rimossi al salvataggio.

Kushki

Enable / Disable: Enable Kushki card payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono nel checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Credit / debit card (Kushki). Obbligatorio.

Description: il testo mostrato sopra il modulo carta nel checkout. Predefinito: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

Credenziali API

Copia i Merchant ID pubblici e privati dalla Kushki Console (Developers > Credentials). Gli account di test (UAT) e di produzione hanno ID diversi. La modalità test usa solo gli ID di test, la modalità live solo quelli live.

Test mode: usa l'ambiente di test (UAT) di Kushki: i Merchant ID di test, il modulo carta di test e le API di test insieme. Non viene addebitato denaro reale e nel checkout compare il badge TEST MODE. Predefinito: attivo. Disattivalo per accettare pagamenti reali. I rimborsi vanno sempre nell'ambiente in cui è stato effettuato il pagamento.

Test Public Merchant ID: il Merchant ID pubblico del tuo account di test Kushki. Carica il modulo carta.

Test Private Merchant ID: il Merchant ID privato del tuo account di test Kushki. Viene usato sul server per addebiti e rimborsi.

Live Public Merchant ID: il Merchant ID pubblico del tuo account di produzione Kushki.

Live Private Merchant ID: il Merchant ID privato del tuo account di produzione Kushki. Tienilo segreto.

I Merchant ID privati e le firme dei webhook salvati non vengono più mostrati. Il campo resta vuoto e mostra Salvato: lascia vuoto per mantenerlo. Inserisci un nuovo valore solo se vuoi cambiarlo.

Webhook (consigliato)

I pagamenti vengono confermati subito dalla risposta delle API di Kushki, quindi il webhook non è obbligatorio. Inoltre crea l'ordine per un pagamento la cui risposta è andata persa (ad esempio per un timeout) e segnala annullamenti e rimborsi effettuati nella Kushki Console. Nella Kushki Console (Webhooks) aggiungi l'URL mostrato in Webhook URL per i pagamenti con carta. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_kushki_payment/webhook, eventualmente con un codice lingua come /es/. Copia l'URL esattamente come lo mostrano le impostazioni. Fallo per l'account di test e per quello di produzione.

Il modulo gestisce queste notifiche di carta:

Test webhook signature: la chiave di firma del webhook dell'account di test Kushki (Console > Webhooks).

Live webhook signature: la chiave di firma del webhook dell'account di produzione Kushki.

Clear saved secrets: spunta un Merchant ID privato o una firma del webhook e clicca su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

I webhook senza una firma valida vengono rifiutati. Una notifica deve essere firmata con la chiave della modalità in cui è stato effettuato il pagamento, quindi una notifica di test non conferma mai un pagamento reale. Senza una chiave di firma, tutte le notifiche webhook vengono rifiutate, ma i pagamenti continuano a funzionare, perché vengono confermati dalla risposta delle API.

Avanzate

Debug log: scrive le richieste e i webhook di Kushki in logs/kushki_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati. I log non contengono mai Merchant ID, token di carta o email dei clienti. Predefinito: disattivato.

Log: mostra la dimensione e le ultime voci del log. Clicca su Clear log per svuotarlo.

Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni e i log. I record dei pagamenti Kushki (addebiti e rimborsi) e lo stato dell'ordine Kushki payment on hold restano sempre, così i vecchi ordini possono essere rimborsati anche dopo una reinstallazione. Predefinito: disattivato.

Checkout

Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit / debit card (Kushki)). Sotto compare il modulo carta Kushki, con il totale del carrello nella valuta del carrello. Il cliente inserisce la carta, sceglie le rate se il modulo Kushki le offre e preme il pulsante di pagamento all'interno del modulo Kushki.

Il pulsante Place order di PrestaShop resta visibile, perché riporta i termini di servizio. Se i termini sono già accettati, il pagamento viene inviato automaticamente dopo il pulsante di pagamento di Kushki. Altrimenti il cliente vede La tua carta è stata accettata da Kushki. Accetta i termini di servizio e premi "Place order" per pagare. Se il cliente preme Place order senza usare il modulo Kushki, compare il messaggio Inserisci i dati della carta nel modulo Kushki e premi il suo pulsante di pagamento.

Il tuo shop addebita poi la carta lato server. L'ordine viene segnato come pagato solo quando Kushki lo conferma con un numero di ticket. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Il pagamento con carta è stato ricevuto. Se Kushki segnala un importo o una valuta, questi vengono confrontati con il carrello. Un ordine in sospeso mostra Il tuo pagamento è in fase di verifica. Aggiorneremo il tuo ordine non appena la verifica sarà completata.

Se la carta viene rifiutata, non viene creato alcun ordine e il cliente torna al passaggio di pagamento con Il tuo pagamento è stato rifiutato e il motivo indicato da Kushki, e può provare un'altra carta. In caso di problemi di rete, di chiavi o del server, il cliente vede Al momento non è possibile elaborare il pagamento. Riprova tra poco o scegli un altro metodo di pagamento. Il motivo tecnico viene scritto nel log. Un secondo clic mentre un pagamento è in elaborazione mostra Un pagamento per questo ordine è già in elaborazione. Attendi un momento e controlla lo stato del tuo ordine.

Se la risposta di Kushki va persa (ad esempio per un timeout), il cliente vede il messaggio generale, ma il tentativo di addebito viene conservato. Quando il webhook firmato segnala l'addebito approvato, l'ordine viene creato. Un carrello che ha già un ordine, o un addebito approvato di cui l'ordine non è ancora stato creato, non viene mai addebitato di nuovo: il cliente vede la conferma di quell'ordine. Se il cliente paga di nuovo prima che arrivi un webhook, si tratta di un nuovo addebito; un'approvazione tardiva del primo addebito aggiunge allora solo una nota su un possibile doppio addebito.

Il webhook funziona anche quando lo shop è in modalità manutenzione e non viene bloccato dalla restrizione per paese del tuo shop. 3-D Secure, le regole antifrode e le rate offerte si configurano nella Kushki Console.

Il modulo accetta solo pagamenti con carta in un unico passaggio. Non prevede rimborsi parziali, carte salvate o abbonamenti, né pagamenti in contanti, bonifici bancari (PSE) o con carta di debito tramite reindirizzamento, né autorizzazione e cattura separate.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente non ha pagato, la carta è stata rifiutata, oppure la risposta di Kushki è andata persa e il webhook non è ancora arrivato. Esiste solo il carrello.

Payment accepted: Kushki ha confermato l'addebito (con la risposta API o con il webhook). Il pagamento viene registrato con il riferimento di transazione Kushki (o il numero di ticket) come ID transazione. Una nota mostra la modalità, il numero di ticket Kushki e il riferimento.

Kushki payment on hold: Kushki ha restituito un esito positivo senza numero di ticket, ha segnalato un importo o una valuta diversi da quelli del carrello, oppure il carrello è stato modificato durante il pagamento. La nota lo spiega. Verifica la transazione nella Kushki Console ed evadi l'ordine oppure rimborsa il pagamento. Un'approvazione firmata successiva con numero di ticket e importo corrispondente imposta l'ordine su Payment accepted.

Payment error: il webhook ha segnalato che l'addebito di un ordine in sospeso è stato rifiutato.

Refunded: il pagamento è stato rimborsato tramite il modulo.

Se Kushki segnala un ulteriore addebito approvato per un ordine già pagato, annullato o rimborsato, l'ordine non viene modificato. Una nota ti invita a verificare un possibile doppio addebito e a rimborsarlo nella Kushki Console. Un webhook dall'ambiente di test per un pagamento live (o viceversa) viene ignorato con una nota.

Blocco Kushki payment

La pagina dell'ordine mostra un blocco Kushki payment con il numero di ticket, il riferimento di transazione, l'ambiente (con un badge Test per i pagamenti di test), lo stato dell'addebito, l'importo addebitato e il totale dell'ordine, il modulo di rimborso, la cronologia dei rimborsi e le Kushki notes dell'ordine.

Rimborsi

Kushki rimborsa l'intero addebito, quindi sono possibili solo rimborsi completi. Nel blocco Kushki payment viene già inserito l'importo addebitato da Kushki. Facoltativamente inserisci un motivo e clicca su Refund via Kushki, poi conferma la domanda Rimborsare l'intero pagamento tramite Kushki? Questa operazione non può essere annullata. Ti serve il permesso di modificare gli ordini. Per qualsiasi altro importo il modulo mostra Kushki rimborsa solo l'intero pagamento. Inserisci l'intero importo addebitato insieme all'importo, e non viene inviato nulla. Il rimborso avviene nell'importo e nella valuta addebitati da Kushki: in caso di differenza di importo, il cliente riceve quindi ciò che è stato effettivamente addebitato, non il totale dell'ordine. Un pagamento può essere rimborsato una sola volta.

Il rimborso viene inviato nella modalità in cui è stato effettuato il pagamento (test o live), quindi deve essere impostato il Merchant ID privato di quella modalità. Se Kushki non accetta il rimborso, il blocco mostra Rimborso Kushki non riuscito con il codice e il messaggio di Kushki, e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e alle note con il ticket di rimborso Kushki, e l'ordine passa a Refunded. I rimborsi richiedono un addebito Kushki confermato con numero di ticket.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Kushki. Gli annullamenti e i rimborsi effettuati nella Kushki Console arrivano tramite il webhook e vengono aggiunti alle note. Lo stato dell'ordine non cambia automaticamente.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Kushki Payment è il primo blocco di Modules > Module Manager > VibeFox Kushki Payment > Configure, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad esempio la data fino a cui 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 di essi ci sono la riga Product: presta-payment-kushki 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, ad esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on seguito da una data. Dopo che l'indirizzo del negozio cambia, o dopo che liberi uno slot di dominio nel tuo account, clicca 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Kushki 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. La vetrina di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo nel checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un 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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Kushki non compare nel checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che la modalità corrente abbia entrambi i Merchant ID: gli ID di test in modalità test, gli ID live in modalità live. Verifica che la valuta del carrello sia USD o COP. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente. La pagina delle impostazioni mostra un avviso quando gli ID mancano.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: la risposta delle API di Kushki è andata persa, ad esempio per un timeout. Il webhook crea l'ordine per questi pagamenti. Nella Kushki Console verifica che l'URL del webhook sia esattamente quello mostrato in Webhook URL, per l'account della modalità che usi, e che la chiave di firma di quell'account sia nel campo corrispondente (Test webhook signature o Live webhook signature). Un addebito approvato senza importo e valuta pagati crea l'ordine in Kushki payment on hold.

Il webhook risponde Webhook signature not configured: nessuna delle due firme del webhook è impostata. Incolla la chiave di firma nelle impostazioni.

Il webhook risponde Invalid signature: la chiave di firma appartiene a un altro account o a un'altra modalità, oppure la notifica è stata modificata durante il percorso.

Il webhook risponde Order mismatch: la notifica non appartiene a un addebito di questo carrello (chiave di tentativo o transazione errata). Non viene modificato nulla.

Il webhook risponde Busy, retry later: l'ordine era in elaborazione da un'altra richiesta nello stesso momento, oppure l'ordine non è stato creato (ad esempio perché il modulo è disattivato). Kushki può inviare di nuovo la notifica. Gli errori vengono sempre scritti nel log.

L'URL del webhook mostra solo POST nel browser: è normale. L'URL accetta solo notifiche da Kushki.

Il modulo carta non si carica: il cliente vede Non è stato possibile caricare il modulo carta Kushki. Ricarica la pagina o scegli un altro metodo di pagamento. Verifica il Merchant ID pubblico della modalità corrente.

Il cliente vede Questa opzione di pagamento non è disponibile in questo negozio. Paga con la carta.: nel modulo Kushki è stata scelta un'opzione di pagamento diversa dalla carta. Il modulo addebita solo carte.

Il cliente vede un errore durante il pagamento: attiva il Debug log e controlla il campo Log nella pagina del modulo. Un Merchant ID privato errato o mancante produce il messaggio generale che il pagamento non è stato elaborato.

Il cliente vede Il pagamento è stato ricevuto, ma non è stato possibile completare l'ordine automaticamente: Kushki ha approvato l'addebito, ma PrestaShop non è riuscito a creare l'ordine. Il log mostra il motivo. Il tentativo di pagamento successivo dello stesso carrello crea l'ordine senza un nuovo addebito.

Il rimborso non riesce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità test o live, e il Merchant ID privato di quella modalità non è impostato. Inseriscilo e riprova.

Il rimborso non viene offerto e compare il messaggio: Nessun numero di ticket Kushki trovato per questo ordine: l'ordine non ha un addebito Kushki confermato. Rimborsalo nella Kushki Console.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Kushki Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, le impostazioni e i log vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una futura reinstallazione. I record dei pagamenti Kushki (addebiti e rimborsi) e lo stato dell'ordine Kushki payment on hold restano sempre, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le note di pagamento, i numeri di ticket Kushki e gli ID transazione.

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