VibeFox Stripe for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza WooCommerce.
PHP: 8.0 o successivo.
HTTPS: il tuo sito dovrebbe usare HTTPS per i pagamenti reali.
Account Stripe: ti servono le chiavi API segrete del tuo account Stripe e un endpoint webhook nello Stripe Dashboard (vedi Configurazione). Vengono usate solo le chiavi segrete e i segreti di firma dei webhook. Le chiavi pubblicabili (pk_...) non sono necessarie, perché Stripe Checkout è una pagina ospitata da Stripe.
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.
Installazione
1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e clicca su Install Now. Puoi anche caricare la cartella wcp_stripe_gateway in /wp-content/plugins/ tramite FTP.
2. Clicca su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Stripe > Manage, oppure clicca su Settings sotto il nome del plugin nella pagina Plugins.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e clicca su Activate.
5. Incolla le tue chiavi segrete Stripe, configura il webhook nello Stripe Dashboard e incolla i suoi segreti di firma (vedi Configurazione).
6. Attiva Enable/Disable. Prova un pagamento in modalità di test con la carta 4242 4242 4242 4242, poi deseleziona Test Mode.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Stripe. Sopra i campi, la pagina ti avvisa quando la modalità attuale non ha una chiave segreta (il metodo di pagamento viene quindi nascosto al checkout) o un segreto di firma del webhook, e mostra Test mode is on: no real payments are taken. mentre la modalità di test è attiva. Nell'elenco dei metodi di pagamento, Stripe è segnalato come da configurare finché la modalità attuale non ha una chiave segreta.
Generale
Enable/Disable: Enable Stripe Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Stripe.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with your credit or debit card via Stripe.
Chiavi API
Copia le chiavi segrete dallo Stripe Dashboard > Developers > API keys. Le chiavi di test e quelle reali sono separate. La modalità di test usa solo le chiavi di test, la modalità reale solo le chiavi reali. Al salvataggio, il plugin ti avvisa se un valore non inizia con il prefisso previsto, per esempio quando al posto di una chiave segreta è stata incollata una chiave pubblicabile.
Test Mode: Enable test mode usa le chiavi di test di Stripe. Non viene addebitato denaro reale; paga con le carte di test di Stripe, come 4242 4242 4242 4242. Predefinito: attivo. Deselezionalo per accettare pagamenti reali.
Test Secret Key: la chiave segreta della modalità di test. Inizia con sk_test_ (o rk_test_ per una chiave con restrizioni).
Test Webhook Secret: il segreto di firma (whsec_...) dell'endpoint webhook creato in modalità di test.
Live Secret Key: la chiave segreta della modalità reale. Inizia con sk_live_ (o rk_live_ per una chiave con restrizioni).
Live Webhook Secret: il segreto di firma (whsec_...) dell'endpoint webhook creato in modalità reale.
Webhook
Il webhook comunica al tuo negozio che un pagamento è stato effettuato. Nello Stripe Dashboard > Developers > Webhooks aggiungi un endpoint in modalità di test e un altro in modalità reale. Usa l'URL mostrato in questa sezione delle impostazioni. Ha un aspetto del tipo https://your-site/wc-api/strg_stripe_webhook/. Se il tuo sito usa un prefisso di lingua negli URL, copia l'URL esattamente come lo mostrano le impostazioni, perché Stripe non segue i reindirizzamenti.
Seleziona questi eventi per ogni endpoint:
Dopo aver creato ogni endpoint, copia il suo segreto di firma (whsec_...) da Stripe e incollalo in Test Webhook Secret o Live Webhook Secret. I webhook senza una firma valida vengono rifiutati. Senza il webhook, un ordine viene confermato solo quando il cliente torna nel negozio dopo aver pagato.
Ordini
Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento riuscito. Lo stato viene impostato subito, senza un secondo cambio di stato.
Avanzate
Logging: Enable logging scrive le richieste e i webhook di Stripe in WooCommerce > Status > Logs, origine wcp_stripe_gateway. Chiavi e dati dei clienti non vengono registrati. Predefinito: disattivato.
Delete Data on Uninstall: se attivo, eliminando il plugin vengono rimosse le impostazioni del gateway, i dati Stripe salvati sugli ordini e i log. Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Stripe) ed effettua l'ordine. Il plugin crea una sessione Stripe Checkout per il totale dell'ordine nella valuta dell'ordine e invia il cliente alla pagina di pagamento di Stripe. Lì il cliente paga con carta di credito o di debito. L'e-mail di fatturazione del cliente viene passata a Stripe e il pagamento compare sulla pagina di Stripe come Order # seguito dal numero dell'ordine.
Dopo il pagamento, il cliente torna alla pagina di ordine ricevuto del tuo negozio. L'ordine viene segnato come pagato solo quando Stripe lo conferma: tramite il webhook firmato o tramite una richiesta lato server a Stripe quando il cliente arriva su quella pagina. Se il pagamento non è ancora confermato, la pagina mostra Your payment is being confirmed by Stripe. You will receive an e-mail as soon as it is confirmed.
Se il cliente annulla nella pagina di Stripe, l'ordine viene annullato nel modo standard di WooCommerce. Un cliente può pagare di nuovo un ordine non pagato, per esempio dalla pagina Pay for order. Ogni nuovo tentativo chiude la sessione Stripe precedente, quindi l'ordine non può essere pagato due volte.
Se Stripe non riesce ad avviare il pagamento, il cliente vede un breve messaggio, per esempio che il totale dell'ordine è inferiore all'importo minimo che Stripe può addebitare in questa valuta, e può scegliere un altro metodo di pagamento. Il motivo tecnico viene aggiunto alle note dell'ordine e al log. Anche i gestori del negozio che hanno effettuato l'accesso lo vedono nel messaggio.
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).
Il plugin accetta solo pagamenti con carta, incassati subito nella pagina di Stripe. Non prevede carte salvate, abbonamenti o pagamenti ricorrenti, né modulo per la carta sul sito, né pulsanti Apple Pay o Google Pay sul tuo sito, né autorizzazione e cattura separate.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a Stripe e non ha ancora pagato, oppure Stripe non ha ancora confermato il pagamento.
Processing, Completed or On Hold: il pagamento è stato confermato. Lo stato segue Order Status After Payment. La nota dell'ordine mostra il pagamento Stripe e come è stato confermato (webhook o ritorno). L'ID della transazione è l'ID del pagamento Stripe (pi_...) e, nella schermata dell'ordine, rimanda al pagamento nello Stripe Dashboard.
On hold after payment: Stripe ha segnalato un importo o una valuta diversi dal totale dell'ordine (per esempio, l'ordine è stato modificato dopo l'avvio del pagamento), oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota dell'ordine lo spiega. Controlla l'ordine ed evadilo oppure rimborsa il pagamento.
Failed: un pagamento differito non è riuscito.
Cancelled: il cliente ha annullato nella pagina di Stripe, oppure l'ordine è stato annullato da te o dal timeout di riserva delle scorte di WooCommerce. La sessione Stripe aperta dell'ordine viene chiusa, quindi non può più essere pagato.
Se arriva un secondo pagamento per un ordine già pagato, l'ordine non viene modificato di nuovo. Una nota ti chiede di verificarlo e di rimborsare il duplicato nello Stripe Dashboard.
Rimborsi
Apri l'ordine, clicca su Refund, inserisci l'importo e clicca su Refund via Stripe. Sono supportati rimborsi totali e parziali. Il rimborso viene inviato nella modalità in cui è stato effettuato il pagamento (test o reale), quindi deve essere impostata la chiave segreta di quella modalità. Se Stripe 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 Stripe.
I rimborsi effettuati nello Stripe Dashboard arrivano tramite il webhook charge.refunded e vengono aggiunti alle note dell'ordine. Non vengono registrati automaticamente come rimborsi WooCommerce. Se necessario, crea un rimborso manuale in WooCommerce senza usare Refund via Stripe.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Stripe. Incolla la chiave in License key e clicca 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 solo dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, Stripe 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. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Nella pagina Plugins e nelle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente in background.
Risoluzione dei problemi
Stripe non compare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità attuale abbia una chiave segreta: Test Secret Key in modalità di test, Live Secret Key in modalità reale. La pagina delle impostazioni mostra un avviso quando la chiave manca.
Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: il webhook non funziona. Nello Stripe Dashboard controlla che l'endpoint esista nella modalità che usi (test o reale), che il suo URL sia esattamente quello mostrato nelle impostazioni e che siano selezionati i quattro eventi. Controlla che il segreto di firma di quell'endpoint sia nel campo giusto (Test Webhook Secret o Live Webhook Secret). Lo Stripe Dashboard mostra la risposta del tuo negozio per ogni webhook. L'ordine viene confermato anche quando il cliente torna nel negozio dopo aver pagato.
Il webhook risponde Webhook secret not configured: non è impostato nessuno dei due segreti dei webhook. Incolla il segreto di firma nelle impostazioni.
Il webhook risponde Invalid signature: il segreto di firma appartiene a un altro endpoint o a un'altra modalità, oppure l'orologio del server è sbagliato. Le firme Stripe vengono accettate entro 5 minuti dall'ora del server.
Il webhook risponde Busy, retry: l'ordine era in fase di conferma da un'altra richiesta nello stesso momento. Stripe ripete automaticamente il webhook.
Avviso al salvataggio: il valore non sembra corretto: una chiave è stata incollata nel campo sbagliato. Le chiavi segrete iniziano con sk_test_ / rk_test_ o sk_live_ / rk_live_, i segreti dei webhook con whsec_.
Il cliente vede un errore quando effettua l'ordine: apri le note dell'ordine oppure attiva Logging e controlla WooCommerce > Status > Logs, origine wcp_stripe_gateway. Una chiave sbagliata o mancante dà il messaggio che il metodo di pagamento non è configurato correttamente. Un totale dell'ordine inferiore al minimo Stripe per la valuta (per esempio 0,50 EUR) non può essere pagato con Stripe.
I pagamenti di test non confermano un ordine reale: i pagamenti di test e quelli reali sono tenuti separati. Un pagamento di test non conferma mai un ordine reale, e viceversa. Imposta Test Mode sulla modalità che vuoi e usa le chiavi e il webhook di quella modalità.
L'ordine è On hold after payment: leggi la nota dell'ordine. L'importo o la valuta pagati erano diversi dall'ordine, oppure il pagamento è arrivato dopo che l'ordine era stato annullato. Evadi l'ordine o rimborsa il pagamento.
Il rimborso fallisce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità di test o reale, e la chiave segreta di quella modalità non è impostata. Inseriscila e riprova.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e clicca su Check now. Se l'indirizzo del sito è cambiato, clicca 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 mantiene 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, i dati Stripe salvati sugli ordini e i log vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID delle transazioni.
Stripe è un marchio dei rispettivi proprietari. Questo plugin non è affiliato a Stripe né approvato da Stripe.