VibeFox Kushki for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Valuta dello shop: USD (Ecuador) o COP (Colombia). Per altre valute il metodo di pagamento viene nascosto al 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, in Developers > Credentials. Per il webhook facoltativo ti serve anche la chiave di firma del webhook di ciascun account (vedi Configurazione).

Chiave di licenza VibeFox: acquistata 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. Puoi anche caricare la cartella wcp_kushki_payment in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Kushki > 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. Inserisci i Merchant ID pubblici e privati di test e lascia attivo Test mode. Facoltativamente, configura il webhook nella Kushki Console e incolla la sua chiave di firma (vedi Configurazione).

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

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Kushki. Sopra i campi la pagina ti avvisa quando il metodo di pagamento è attivo ma mancano i Merchant ID della modalità corrente (il metodo di pagamento viene allora nascosto al checkout), quando la valuta dello shop non è supportata, quando la modalità live viene usata senza HTTPS e quando la modalità corrente non ha una firma per il webhook. Mentre la modalità test è attiva, mostra Test mode is on: the Kushki test environment is used, no real money is charged. Quando salvi con il metodo di pagamento attivo ma senza i Merchant ID della modalità corrente, un errore ti ricorda di inserirli. Gli spazi attorno agli ID vengono rimossi al salvataggio.

Generali

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 al checkout. Predefinito: Credit / debit card (Kushki).

Description: il testo mostrato sopra il modulo carta al 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 gli ID live.

Test mode: Use the Kushki test (UAT) environment passa insieme Merchant ID, modulo carta e API all'ambiente di test di Kushki. Non viene addebitato denaro reale e al checkout compare un badge TEST MODE. Predefinito: attivo. Disattivalo per accettare pagamenti reali.

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.

Webhook (consigliato)

I pagamenti vengono confermati subito dalla risposta delle API di Kushki, quindi il webhook non è obbligatorio. Serve inoltre a confermare i pagamenti la cui risposta è andata persa (ad esempio per un timeout) e a segnalare annullamenti e rimborsi effettuati nella Kushki Console. Nella Kushki Console (Webhooks) aggiungi l'URL mostrato in questa sezione delle impostazioni per i pagamenti con carta. Ha questo aspetto: https://your-site/wc-api/webhook_kushki_p/. Fallo sia per l'account di test sia per quello di produzione.

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

I webhook senza una firma valida vengono rifiutati. 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: Log API calls and webhooks scrive richieste e webhook Kushki in WooCommerce > Status > Logs, origine wcp_kushki_payment. Gli errori vengono sempre registrati. I registri non contengono mai Merchant ID, token di carta o email dei clienti. Predefinito: disattivato.

Delete data on uninstall: se attivo, eliminando il plugin vengono rimosse impostazioni e registri. Ordini e relativi riferimenti Kushki vengono conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit / debit card (Kushki)). Sotto appare il modulo carta Kushki con il totale dell'ordine nella valuta dell'ordine. Nella pagina Pay for order il modulo usa il totale dell'ordine. 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.

Nel checkout classico il pulsante Place order di WooCommerce viene nascosto mentre è selezionato Kushki: dopo che la carta è stata accettata, l'ordine viene inviato automaticamente. Nel blocco Checkout il cliente preme comunque il pulsante di pagamento all'interno del modulo Kushki. Se il cliente prova a inviare l'ordine senza farlo, viene mostrato il messaggio Please enter your card details in the Kushki form and press its pay button.

Il tuo shop addebita poi la carta lato server. L'ordine viene segnato come pagato solo dopo che Kushki lo conferma con un numero di ticket, e il cliente passa direttamente alla pagina di ordine ricevuto. Se Kushki riporta un importo o una valuta approvati, questi vengono confrontati con l'ordine.

Se la carta viene rifiutata, il cliente vede Your payment was declined con il motivo fornito da Kushki e può provare un'altra carta nello stesso modulo. Per problemi di rete, di chiavi o del server il cliente vede The payment could not be processed right now. Please try again in a moment or choose another payment method. Il motivo tecnico viene aggiunto alle note dell'ordine e al registro. Un secondo clic mentre un pagamento è in elaborazione mostra A payment for this order is already being processed. Please wait a moment and check your order status.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS). 3-D Secure, regole antifrode e rate offerte si configurano nella Kushki Console.

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

Ordini e rimborsi

Stati dell'ordine

Pending payment: l'ordine è stato creato e la carta non è ancora stata addebitata.

Processing: Kushki ha confermato l'addebito (con la risposta API o con il webhook). Gli ordini con soli prodotti virtuali scaricabili passano a Completed, il valore predefinito di WooCommerce. La nota dell'ordine mostra la modalità, il numero di ticket Kushki e il riferimento. L'ID transazione è il riferimento transazione Kushki (o il numero di ticket).

On hold: Kushki ha restituito un successo senza numero di ticket, oppure ha segnalato un importo o una valuta diversi da quelli dell'ordine. La nota dell'ordine lo spiega. Controlla la transazione nella Kushki Console, poi evadi l'ordine oppure rimborsa il pagamento.

Failed: la carta è stata rifiutata o l'addebito non è stato possibile. La nota dell'ordine mostra il codice e il messaggio di Kushki. Il cliente può pagare di nuovo.

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

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci il totale completo dell'ordine e fai clic su Refund via Credit / debit card (Kushki) (il pulsante mostra il tuo Title). Kushki rimborsa l'intero pagamento, quindi vengono accettati solo rimborsi completi. Per un importo parziale il plugin mostra Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. 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, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con il ticket di rimborso Kushki.

Annullamenti e rimborsi effettuati nella Kushki Console arrivano tramite webhook e vengono aggiunti alle note dell'ordine. Non vengono registrati automaticamente come rimborsi di 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 > Kushki. 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 controllare 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, Kushki 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. Gli amministratori dello shop che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i webhook continuano a essere elaborati e i rimborsi funzionano.

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

Kushki non compare al 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 dello shop (o la valuta dell'ordine nella pagina Pay for order) sia USD o COP. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi.

Il pagamento è andato a buon fine, ma l'ordine è Failed o resta in Pending payment: la risposta delle API di Kushki è andata persa, ad esempio per un timeout. Il webhook conferma questi pagamenti. Nella Kushki Console verifica che l'URL del webhook sia esattamente quello mostrato nelle impostazioni, 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 l'importo e la valuta pagati mette invece l'ordine in sospeso.

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 modalità, oppure la notifica è stata modificata durante il percorso.

Il webhook risponde Order mismatch: la notifica non appartiene a questo ordine (chiave ordine o transazione errata). L'ordine non viene modificato.

Il webhook risponde Busy, retry later: l'ordine era in elaborazione da un'altra richiesta nello stesso momento. Kushki può inviare di nuovo la notifica.

Il modulo carta non si carica: il cliente vede The Kushki card form could not be loaded. Please reload the page or choose another payment method. Verifica il Merchant ID pubblico della modalità corrente.

Il cliente vede This payment option is not available in this store. Please pay by card.: nel modulo Kushki è stata scelta un'opzione di pagamento diversa dalla carta. Il plugin addebita solo carte.

Il cliente vede un errore durante il pagamento: apri le note dell'ordine oppure attiva il Debug log e controlla WooCommerce > Status > Logs, origine wcp_kushki_payment. Un Merchant ID privato errato o mancante produce il messaggio generico secondo cui il pagamento non è stato elaborato.

Il rimborso fallisce 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 fallisce con No Kushki ticket number found for this order: l'ordine non ha un addebito Kushki confermato. Rimborsalo nella Kushki Console.

Altre valute: gli sviluppatori possono modificare l'elenco delle valute con il filtro kushki_p_supported_currencies a proprio rischio. La valuta deve essere abilitata sul tuo account Kushki.

Il blocco licenza mostra un errore: segui il messaggio del 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 per il 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 nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i registri vengono rimossi solo se era attiva l'opzione Delete data on uninstall. Altrimenti restano disponibili per una successiva reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento, i numeri di ticket Kushki e gli ID transazione.

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