VibeFox PayPal for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo. Il modulo rifiuta di installarsi su versioni di PHP più vecchie.
Account PayPal: un account PayPal Business con un'app REST API nel PayPal Developer Dashboard. Servono il Client ID e il Secret dell'app. Le app sandbox e live hanno credenziali diverse. Non serve alcun webhook: il modulo conferma ogni pagamento sul tuo server mentre il cliente si trova nel checkout.
Valuta: una delle valute supportate da PayPal: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD o USD.
Chiave di licenza VibeFox: acquistata 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 PayPal Gateway nell'elenco dei moduli e clicca su Configure.
3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in alto nella pagina Configure, poi fai clic su Activate (vedi Chiave di licenza).
4. Nel PayPal Developer Dashboard crea un'app REST API (sandbox e/o live) e copia il suo Client ID e il suo Secret.
5. Inserisci le credenziali della modalità che usi, scegli Capture o Authorize, attiva Enable/Disable e clicca su Save.
6. Prova con un account acquirente sandbox di PayPal, poi disattiva Sandbox mode e inserisci le credenziali live.
All'installazione il modulo crea tre stati dell'ordine: PayPal payment authorized, Awaiting PayPal payment e PayPal payment on hold. PrestaShop attiva il 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 PayPal Gateway > Configure. Ogni sezione ha un proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa quando il metodo di pagamento è attivo ma il Client ID o il Secret della modalità selezionata sono vuoti, e quando PayPal non supporta la valuta predefinita del negozio. In entrambi i casi il metodo di pagamento viene nascosto nel checkout. Finché la modalità sandbox è attiva, la pagina mostra Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. Il salvataggio delle impostazioni elimina i token di accesso PayPal in cache, così le nuove credenziali vengono usate subito.
General
Enable/Disable: Enable PayPal Gateway 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 memorizzato nell'ordine. Predefinito: PayPal. Obbligatorio.
Description: il testo mostrato sotto il metodo di pagamento nel checkout. Predefinito: Pay with your PayPal account or a card via PayPal.
Credenziali API
Crea un'app REST API nel PayPal Developer Dashboard e copia il suo Client ID e il suo Secret. La sezione contiene collegamenti alle app sandbox e alle app live. Vengono mostrati solo i campi della modalità selezionata; le credenziali di entrambe le modalità restano salvate.
Sandbox mode: i pagamenti vanno alla sandbox di PayPal con le credenziali sandbox; non viene spostato denaro reale. Predefinito: attivo. Disattivalo per accettare pagamenti live. Acquisizioni, annullamenti e rimborsi usano sempre l'ambiente in cui è stato pagato l'ordine. Quando è attivo, i clienti vedono Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged. sotto il metodo di pagamento.
Sandbox Client ID: il Client ID della tua app REST API sandbox.
Sandbox Secret: il Secret della tua app REST API sandbox.
Live Client ID: il Client ID della tua app REST API live.
Live Secret: il Secret della tua app REST API live.
I secret salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.
Clear saved secrets: spunta un secret e clicca su Save per eliminarlo. Un campo vuoto mantiene il valore salvato.
Pagamento
Payment action: cosa succede quando il cliente approva il pagamento. Predefinito: Capture.
Avanzate
Debug log: registra le richieste API in logs/wc_plg_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche quando questo interruttore è disattivato. Credenziali, token e dati dell'acquirente non vengono mai registrati. Predefinito: disattivato.
Log: mostra la dimensione e le voci più recenti del log. Clicca su Clear log per svuotarlo.
Delete data on uninstall: se attivo, la disinstallazione del modulo elimina le impostazioni del gateway, i token in cache e il log. I dati di pagamento degli ordini (ID PayPal degli ordini, rimborsi) e gli stati degli ordini vengono sempre conservati. Predefinito: disattivato.
Checkout
Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita PayPal) e il pulsante PayPal compare al posto del modulo di pagamento. Un clic sul pulsante crea sul tuo server un ordine PayPal per il totale del carrello nella valuta del carrello. L'importo viene sempre calcolato sul server, mai nel browser. A questo punto non esiste ancora alcun ordine.
Il cliente approva il pagamento nella finestra di PayPal con un account PayPal o un'altra fonte di finanziamento offerta da PayPal. Il checkout mostra quindi PayPal payment approved. Completing your order… e crea l'ordine. Se i termini del servizio non sono ancora stati accettati, il checkout mostra PayPal payment approved. Click "Place order" to complete it. Se il cliente clicca su Place order senza approvare un pagamento, il messaggio è Please click the PayPal button and approve the payment first.
Il tuo server legge poi l'ordine PayPal e verifica che sia approvato, che sia stato creato per questo carrello, che non sia usato da un altro carrello e che importo e valuta corrispondano al carrello. Solo allora il pagamento viene acquisito (o autorizzato), l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine.
Se il totale del carrello cambia dopo l'approvazione, non viene acquisito nulla. Il cliente vede The order total changed after you approved the payment in PayPal. Please click the PayPal button again to approve the new total. Se PayPal rifiuta il pagamento, il cliente torna alla fase di pagamento e viene invitato a cliccare sul pulsante PayPal e scegliere un altro metodo di pagamento. Non viene creato alcun ordine. Se il cliente chiude la finestra di PayPal, il checkout mostra You cancelled the PayPal payment.
Se PayPal non risponde durante l'acquisizione, il cliente vede We could not confirm your PayPal payment yet. Please try again in a moment — you will not be charged twice. L'approvazione viene conservata, anche dopo un ricaricamento della pagina, e Place order la usa di nuovo. Se PayPal aveva completato il tentativo precedente, si usa quel pagamento e non viene acquisita una nuova approvazione. Se il pagamento è stato incassato ma non è stato possibile creare l'ordine, il cliente vede Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Il tentativo successivo crea l'ordine dal pagamento salvato, senza addebitare di nuovo.
Lo script di PayPal viene caricato solo nella pagina di checkout e nel proprio namespace, quindi non entra in conflitto con un altro modulo PayPal presente nella pagina. Il modulo funziona con i temi Classic e Hummingbird.
Il modulo non ha webhook di PayPal, messaggi Pay Later, campi per carte, Venmo, Apple Pay, Google Pay o Fastlane, metodi di pagamento salvati o abbonamenti, né pulsanti nelle pagine di prodotto o del carrello. Vengono usati gli indirizzi inseriti nel checkout di PrestaShop, non un indirizzo proveniente da PayPal.
Ordini e rimborsi
Stati dell'ordine
No order yet: il cliente non ha approvato il pagamento, oppure PayPal lo ha rifiutato. Esiste solo il carrello.
Payment accepted: l'acquisizione è completata. L'ordine viene segnato come pagato solo dopo la conferma di PayPal. Il pagamento viene registrato con l'ID di acquisizione PayPal come ID transazione, e una nota mostra l'importo, l'ordine PayPal e l'acquisizione.
PayPal payment authorized: il pagamento è stato autorizzato e attende l'acquisizione (azione di pagamento Authorize).
Awaiting PayPal payment: l'acquisizione è PENDING presso PayPal, per esempio in fase di verifica del pagamento.
PayPal payment on hold: l'importo o la valuta pagati non corrispondono all'ordine, oppure il pagamento non è stato possibile leggerlo dalla risposta di PayPal. La nota lo spiega. Quando PayPal ha addebitato nella valuta dell'ordine, l'importo effettivamente pagato viene registrato come pagamento. Controlla l'ordine ed evadilo, oppure rimborsa il pagamento.
Canceled: l'autorizzazione è stata annullata con Void PayPal authorization.
Payment error: un'acquisizione in sospeso è stata rifiutata o non è riuscita.
Refunded: il pagamento è stato rimborsato integralmente tramite il modulo.
Se arriva un secondo pagamento per un carrello che ha già un ordine, l'ordine non viene modificato. Una nota ti chiede di verificarlo nel tuo account PayPal e di rimborsarlo.
Blocco pagamento PayPal
La pagina dell'ordine mostra un blocco PayPal payment con l'ID dell'ordine PayPal e l'intent, l'ID di acquisizione (collegato al pagamento nel tuo account PayPal, sandbox o live), l'ID di autorizzazione, lo stato del pagamento, l'importo, gli importi pagato e rimborsato, un badge Sandbox per i pagamenti sandbox, la cronologia dei rimborsi e le PayPal notes dell'ordine. I pulsanti del blocco richiedono il permesso di modificare gli ordini, ma non l'accesso alle pagine dei moduli. Il risultato di ogni azione viene mostrato nel blocco.
Rimborsi
Nel blocco PayPal payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via PayPal. Conferma la domanda Refund this amount through PayPal? This cannot be undone. Sono supportati rimborsi totali e parziali. Il motivo viene passato a PayPal come nota per l'acquirente. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da PayPal, quindi dopo una discrepanza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato all'ambiente PayPal in cui è stato effettuato il pagamento (sandbox o live), quindi le credenziali di quell'ambiente devono essere impostate. Se PayPal non accetta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e alle note con l'ID e lo stato del rimborso PayPal; un rimborso PENDING viene completato da PayPal più tardi. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.
Un pagamento solo autorizzato non può essere rimborsato: usa invece Void PayPal authorization. Il modulo non crea note di credito. I pulsanti standard di rimborso di PrestaShop nella pagina dell'ordine non rimandano denaro tramite PayPal. Rimborsi, contestazioni e storni effettuati nel tuo account PayPal non vengono sincronizzati con PrestaShop.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox PayPal Gateway è il primo blocco della pagina Modules > Module Manager > VibeFox PayPal Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo di ciò il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui la licenza è attiva e il tuo dominio) e i pulsanti Check now per verificare 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-paypal 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 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. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, PayPal non viene mostrato ai clienti nel checkout. Se un pagamento viene avviato comunque, il negozio rifiuta di creare l'ordine PayPal e il cliente vede An error occurred during PayPal checkout. Please try again. Lo storefront di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento è 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 rimborsi e le azioni del blocco PayPal continuano a funzionare.
Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo 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
PayPal does not appear at checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che il Client ID e il Secret della modalità selezionata siano compilati, che la valuta del carrello sia supportata da PayPal e che il totale del carrello sia superiore a zero. La pagina delle impostazioni mostra un avviso quando il problema è nelle credenziali o nella valuta. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente. Un'estensione del browser che blocca www.paypal.com nasconde comunque il pulsante.
The payment went through, but no order was created: il modulo non ha webhook, quindi il pagamento viene confermato solo durante il checkout. Succede quando PayPal non ha risposto durante l'acquisizione o quando non è stato possibile creare l'ordine. Attiva Debug log e controlla il campo Log, verifica il pagamento nel tuo account PayPal, oppure lascia che il cliente riprovi: un nuovo tentativo non addebita mai due volte e crea l'ordine dal pagamento salvato.
PayPal could not be loaded: lo script di PayPal non è stato caricato nel browser, per esempio a causa di un blocco o di un problema di rete.
PayPal is not available right now: le credenziali sono errate oppure appartengono all'altra modalità. Copia di nuovo il Client ID e il Secret dell'app giusta.
Your PayPal approval could not be matched to this checkout: l'ordine PayPal non è stato creato per questo carrello, per esempio dopo la scadenza della sessione. Il cliente clicca di nuovo sul pulsante PayPal.
This payment is already being processed: lo stesso carrello è stato inviato due volte nello stesso momento. Il cliente attende un momento e controlla l'e-mail prima di riprovare.
The order is on hold after payment: leggi le note nel blocco PayPal payment. Il pagamento è stato autorizzato (acquisiscilo con Capture PayPal payment), l'acquisizione è PENDING presso PayPal (usa più tardi Check PayPal payment status), oppure l'importo o la valuta pagati non corrispondevano all'ordine (evadi l'ordine o rimborsa quanto pagato).
Capture of an authorization fails: l'autorizzazione potrebbe avere più di 29 giorni o essere già stata annullata. Il blocco e le note mostrano l'errore di PayPal.
Refund fails: l'ordine non ha un'acquisizione PayPal (solo un'autorizzazione), l'importo supera quanto resta da rimborsare, oppure mancano le credenziali dell'ambiente in cui è stato effettuato il pagamento. Il blocco indica quale caso si applica.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox PayPal Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre eliminati. Se Delete data on uninstall è attivo, vengono eliminate le impostazioni del gateway, i token di accesso PayPal in cache e il log. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le transazioni e i rimborsi PayPal e gli stati degli ordini PayPal payment authorized, Awaiting PayPal payment e PayPal payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID di transazione.
PayPal è un marchio di proprietà del suo titolare. Questo modulo non è affiliato a PayPal né approvato da PayPal.