VibeFox Stripe 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 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 servono, 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. 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 Stripe Gateway 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. Incolla le chiavi segrete Stripe, configura il webhook nello Stripe Dashboard e incolla i suoi segreti di firma (vedi Configurazione).

5. Attiva Enable/Disable e fai clic su Save. Prova un pagamento in modalità di test con la carta 4242 4242 4242 4242, poi disattiva Test Mode.

All'installazione il modulo crea due stati dell'ordine: Awaiting Stripe payment e Stripe payment on hold. PrestaShop attiva il nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Stripe Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando la modalità corrente non ha una chiave segreta (il metodo di pagamento viene allora nascosto al checkout) o un segreto di firma del webhook (gli ordini vengono allora confermati solo quando il cliente torna nel negozio). Finché la modalità di test è attiva, mostra anche La modalità di test è attiva: non viene addebitato alcun pagamento reale.

Stripe Checkout

Enable/Disable: Enable Stripe Gateway attiva o disattiva il metodo di pagamento. Default: off.

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Default: Stripe. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Default: Pay securely with your credit or debit card via Stripe.

Chiavi API

Copia le chiavi segrete da 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 quelle reali. Al salvataggio il modulo ti avvisa se un valore non inizia con il prefisso previsto, ad esempio quando è stata incollata una chiave pubblicabile al posto di una chiave segreta.

Test Mode: usa le chiavi di test di Stripe. Non viene addebitato denaro reale; paga con carte di test di Stripe come 4242 4242 4242 4242. Default: on. Disattivalo per accettare pagamenti reali. Finché è attivo, i clienti vedono Modalità di test: non viene effettuato alcun pagamento reale. sotto il metodo di pagamento.

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.

Le chiavi e i segreti salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Salvato — lascia vuoto per mantenerlo. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved secrets: seleziona una chiave o un segreto e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

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 Endpoint URL in questa sezione. Con URL user-friendly ha questo aspetto: https://your-shop/module/wcp_stripe_gateway/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni, perché Stripe non segue i reindirizzamenti.

Seleziona questi eventi per ogni endpoint (sono elencati anche in questa sezione):

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. Un evento deve essere firmato con il segreto della modalità in cui è stato effettuato il pagamento, quindi un segreto di test non conferma mai un pagamento reale. Senza il webhook, un ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato.

Ordini

Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento riuscito.

I pagamenti differiti attendono in Awaiting Stripe payment. Le discrepanze di importo o valuta vanno sempre in Stripe payment on hold.

Avanzate

Logging: scrive le richieste a Stripe e i webhook nel file logs/strg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi e dati dei clienti non vengono registrati. Default: off. Finché è disattivato non viene scritto nulla.

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

Delete Data on Uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni del gateway e il log. Le transazioni e i rimborsi Stripe e gli stati dell'ordine del modulo restano sempre, così gli ordini esistenti continuano a funzionare. Default: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (di default Stripe) e vede la nota Verrai reindirizzato a Stripe per completare il pagamento in modo sicuro. Dopo la conferma, il modulo crea una sessione di Stripe Checkout per il totale del carrello nella valuta del carrello e invia il cliente alla pagina di pagamento di Stripe. Lì il cliente paga con carta di credito o di debito. L'e-mail del cliente viene passata a Stripe e il pagamento compare sulla pagina di Stripe come Cart # seguito dal numero del carrello. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Stripe: tramite il webhook firmato o tramite una richiesta lato server a Stripe quando il cliente torna. L'ordine viene quindi creato e il cliente vede la normale pagina di conferma dell'ordine con Il tuo pagamento con Stripe è stato ricevuto. Per un pagamento differito la pagina mostra Il tuo pagamento è in fase di conferma da parte di Stripe. Riceverai un'e-mail non appena sarà confermato. Se un pagamento differito fallisce in seguito, la pagina mostra Il tuo pagamento con Stripe non è stato completato. Contattaci per questo ordine. Se Stripe non ha ancora confermato il pagamento quando il cliente torna, una pagina Conferma del pagamento mostra lo stesso testo e un pulsante Check again; il webhook crea l'ordine appena arriva.

Se il cliente annulla sulla pagina di Stripe, la sessione di Stripe viene chiusa e il cliente torna al checkout con Il pagamento è stato annullato. Puoi riprovare o scegliere un altro metodo di pagamento. Se il pagamento non è stato completato, il messaggio è Il pagamento non è stato completato. Puoi riprovare o scegliere un altro metodo di pagamento. Il carrello viene conservato. Ogni nuovo tentativo chiude la sessione Stripe precedente, così il carrello non può essere pagato due volte. Se la sessione precedente risulta già pagata, viene creato l'ordine invece di un nuovo pagamento.

Se Stripe non riesce ad avviare il pagamento, il cliente resta al checkout con un messaggio breve, ad esempio L'importo dell'ordine è inferiore al minimo che Stripe può addebitare in questa valuta. Scegli un altro metodo di pagamento. Il motivo tecnico viene scritto nel log.

Se un buono sconto nel carrello smette di essere valido tra il pagamento e la sua conferma, PrestaShop lo rimuove dall'ordine. L'ordine passa quindi a Stripe payment on hold con una nota, perché il cliente ha pagato il prezzo con lo sconto.

Il webhook funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo accetta solo pagamenti con carta, addebitati subito sulla 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

Nessun ordine ancora: il cliente è stato inviato a Stripe e non ha pagato, oppure Stripe non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted, Delivered or Stripe payment on hold: il pagamento è stato confermato. Lo stato segue Order Status After Payment. Il pagamento viene registrato con l'ID di pagamento Stripe (pi_...) come ID transazione, e una nota mostra il pagamento Stripe, la sessione e come è stato confermato (webhook o ritorno).

Awaiting Stripe payment: il cliente ha completato il checkout con un metodo di pagamento differito. L'ordine passa allo stato pagato quando Stripe conferma il pagamento.

Stripe payment on hold after payment: Stripe ha comunicato un importo o una valuta diversi dal totale dell'ordine (ad esempio il carrello è stato modificato dopo l'avvio del pagamento), un buono sconto è stato rimosso oppure il pagamento è arrivato dopo l'annullamento dell'ordine. La nota lo spiega. Controlla l'ordine e completalo oppure rimborsa il pagamento.

Payment error: un pagamento differito non è riuscito.

Refunded: il pagamento è stato rimborsato interamente tramite il modulo.

Se arriva un secondo pagamento per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di verificarlo e di rimborsare il duplicato nello Stripe Dashboard.

Blocco Stripe payment

La pagina dell'ordine mostra un blocco Stripe payment con l'ID di pagamento Stripe (collegato al pagamento nello Stripe Dashboard), la Checkout Session, lo stato del pagamento, l'importo addebitato da Stripe e l'importo rimborsato, un badge Test mode per i pagamenti di test, lo storico dei rimborsi e le Stripe notes dell'ordine.

Rimborsi

Nel blocco Stripe payment inserisci l'importo (viene precompilato quello non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Stripe. Conferma la domanda Rimborsare questo importo tramite Stripe? Non è possibile annullare l'operazione. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da Stripe, quindi dopo una discrepanza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non il totale dell'ordine. Il rimborso viene inviato nella modalità in cui è stato effettuato il pagamento (test o reale), quindi la chiave segreta di quella modalità deve essere impostata. Se Stripe non accetta il rimborso, il blocco mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con l'ID di rimborso Stripe. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non modifica lo stato. I rimborsi sono disponibili dopo la conferma del pagamento da parte di Stripe.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Stripe.

I rimborsi effettuati nello Stripe Dashboard arrivano tramite il webhook charge.refunded e vengono aggiunti alle note con il totale rimborsato in Stripe. Lo stato dell'ordine e le note di credito non vengono modificati automaticamente. Aggiornali manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Stripe Gateway è il primo blocco di Modules > Module Manager > VibeFox Stripe Gateway > Configure, sopra le impostazioni. Incolla la chiave in License key e fai clic su Activate. Dopo di che il blocco mostra la chiave mascherata, lo stato (ad 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 si trovano la riga Product: presta-payment-stripe 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 cambiare 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 una modifica dell'indirizzo del negozio, o dopo aver liberato uno slot di 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 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. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo al checkout. Un promemoria compare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono ancora confermati e i rimborsi funzionano.

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

Stripe non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente 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 manca la chiave. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: il webhook non funziona. Nello Stripe Dashboard verifica che l'endpoint esista nella modalità che usi (test o reale), che il suo URL sia esattamente quello mostrato in Endpoint URL e che i quattro eventi siano selezionati. Verifica 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 creato anche quando il cliente torna nel negozio dopo il pagamento.

Il webhook risponde Webhook secret not configured: non è impostato alcun segreto del 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. La risposta è Invalid signature anche quando un evento di un pagamento reale è firmato con il segreto di test o viceversa: verifica che i segreti di test e reali non siano scambiati.

Il webhook risponde Busy, retry: l'ordine era in fase di conferma da un'altra richiesta nello stesso momento, oppure l'ordine non è stato possibile crearlo (ad esempio perché il modulo è disattivato). Stripe ritenta automaticamente il webhook. Attiva Logging per vedere il motivo.

L'URL del webhook mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste da Stripe.

Avviso che il valore non sembra corretto al salvataggio: 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 sceglie Stripe: attiva Logging e controlla il campo Log nella pagina del modulo. Una chiave errata dà il messaggio che il metodo di pagamento non è configurato correttamente. Un totale d'ordine inferiore al minimo di Stripe per la valuta (ad esempio 0.50 EUR) non può essere pagato con Stripe.

I pagamenti di test non confermano un pagamento reale: i pagamenti di test e quelli reali sono separati. Imposta Test Mode sulla modalità che vuoi usare e utilizza le chiavi e il webhook di quella modalità.

L'ordine è in Stripe payment on hold dopo il pagamento: leggi le note nel blocco Stripe payment (vedi Stati dell'ordine), poi completa 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.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Stripe Gateway e scegli Uninstall. La chiave di licenza e lo stato di licenza di questo modulo vengono sempre rimossi. Se Delete Data on Uninstall è attivo, vengono rimosse le impostazioni del gateway e il log. Se è disattivo, tutte le impostazioni vengono mantenute per una reinstallazione successiva. Le transazioni e i rimborsi Stripe e gli stati dell'ordine Awaiting Stripe payment e Stripe payment on hold vengono sempre mantenuti, così gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le note di pagamento e gli ID delle transazioni.

Stripe è un marchio del rispettivo titolare. Questo modulo non è affiliato a Stripe né approvato da Stripe.