VibeFox PayPal for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

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

PHP: 8.0 o successivo.

HTTPS: il tuo sito dovrebbe usare HTTPS per i pagamenti live.

Account PayPal: un account PayPal Business con un'app REST API nel PayPal Developer Dashboard. Ti servono il Client ID e il Secret dell'app. Le app sandbox e live hanno credenziali diverse. Non serve alcun webhook: il plugin conferma ogni pagamento sul tuo server mentre il cliente è al 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 dominio.

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e clicca su Install Now. In alternativa puoi caricare la cartella wcp_paypal_gateway in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

3. Nel PayPal Developer Dashboard crea un'app REST API (sandbox e/o live) e copia il suo Client ID e il suo Secret.

4. Apri le impostazioni: WooCommerce > Settings > Payments > PayPal (Smart Buttons) > Manage, oppure clicca su Settings sotto il nome del plugin nella pagina Plugins.

5. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e clicca su Activate.

6. Inserisci le credenziali della modalità che usi, scegli Capture o Authorize, attiva Enable/Disable e salva.

7. Esegui un test con un account acquirente sandbox di PayPal, poi deseleziona Sandbox mode e inserisci le credenziali live.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > PayPal (Smart Buttons). 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 del negozio. In entrambi i casi il metodo di pagamento viene nascosto al checkout. Nell'elenco dei metodi di pagamento PayPal mostra un badge Test mode in modalità sandbox ed è contrassegnato come da configurare finché non vengono inserite le credenziali della modalità selezionata.

Generale

Enable/Disable: Enable PayPal Gateway attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: PayPal.

Description: il testo mostrato sotto il metodo di pagamento al 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 link alle app sandbox e alle app live. Vengono mostrati solo i campi della modalità selezionata.

Sandbox mode: Enable sandbox (test) mode. I pagamenti vanno alla sandbox di PayPal con le credenziali sandbox; non viene movimentato denaro reale. Predefinito: on. Deselezionala per accettare pagamenti live.

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.

Pagamento

Payment action: cosa succede quando il cliente approva il pagamento. Predefinito: Capture.

Capture: il cliente viene addebitato subito e l'ordine passa a In lavorazione.

Authorize: i fondi vengono solo riservati e l'ordine viene messo In attesa. Acquisisci o annulla il pagamento dalla schermata dell'ordine con il menu Order actions. Le autorizzazioni PayPal possono essere acquisite entro 29 giorni.

Avanzate

Debug log: Log API requests (errors are always logged). Le voci vengono salvate in WooCommerce > Status > Logs, origine wcp_paypal_gateway. Credenziali e dati degli acquirenti non vengono mai registrati. Predefinito: off.

Delete data on uninstall: Delete the gateway settings when the plugin is deleted. I dati di pagamento degli ordini (gli ID PayPal memorizzati negli ordini) vengono sempre conservati. Predefinito: off.

Checkout

Quando il cliente sceglie PayPal (per impostazione predefinita PayPal), il pulsante PayPal sostituisce Place order. In modalità sandbox il checkout mostra Modalità sandbox: paga con un account acquirente sandbox di PayPal. Non viene addebitato denaro reale. Un clic sul pulsante crea sul tuo server un ordine PayPal per il totale del carrello (o per il totale dell'ordine nella pagina Pay for order). L'importo viene sempre calcolato sul server, mai nel browser.

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 poi Pagamento PayPal approvato. Completamento dell'ordine in corso… e invia l'ordine. Il tuo server legge l'ordine PayPal e verifica che sia approvato, che sia stato creato in questo checkout, che non sia usato da un altro ordine e che importo e valuta corrispondano all'ordine. Solo a quel punto il pagamento viene acquisito (o autorizzato) e il cliente arriva alla pagina di conferma dell'ordine.

Se il totale del carrello cambia dopo l'approvazione, non viene acquisito nulla. Il cliente vede Il totale dell'ordine è cambiato dopo che hai approvato il pagamento in PayPal. Clicca di nuovo sul pulsante PayPal per approvare il nuovo totale. Se manca un campo del checkout, l'approvazione viene conservata: dopo la correzione il cliente clicca su Place order per completare il pagamento. Se PayPal rifiuta il pagamento, al cliente viene chiesto di cliccare sul pulsante PayPal e scegliere un altro metodo di pagamento. Se il cliente chiude la finestra di PayPal, il checkout mostra Hai annullato il pagamento PayPal.

Se PayPal non risponde durante l'acquisizione, il cliente vede Non siamo ancora riusciti a confermare il tuo pagamento PayPal. Riprova tra un momento: non verrai addebitato due volte. Un nuovo tentativo usa la stessa approvazione e, se PayPal aveva completato il tentativo precedente, viene usato quel pagamento e la nuova approvazione non viene acquisita.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. Lo script di PayPal viene caricato nel proprio namespace, quindi non entra in conflitto con altri plugin PayPal presenti nella pagina. È compatibile con High-Performance Order Storage (HPOS) di WooCommerce.

Il plugin non ha webhook di PayPal, messaggi Pay Later, campi per carte, impostazioni Venmo, Apple Pay, Google Pay o Fastlane, metodi di pagamento salvati o abbonamenti, né pulsanti nelle pagine di prodotto o del carrello. Viene usato l'indirizzo di spedizione inserito nel checkout di WooCommerce, non un indirizzo di PayPal.

Ordini e rimborsi

Order statuses

Pending payment: l'ordine è stato creato, ma il pagamento non è ancora acquisito, per esempio dopo una risposta sconosciuta di PayPal.

Processing: l'acquisizione è completata. Gli ordini con soli prodotti virtuali scaricabili passano a Completato, il valore predefinito di WooCommerce. La nota dell'ordine mostra importo, ordine PayPal e acquisizione. L'ID transazione è l'ID di acquisizione PayPal e, nella schermata dell'ordine, collega al pagamento nel tuo account PayPal (sandbox o live).

On hold: il pagamento è stato autorizzato e attende l'acquisizione (azione di pagamento Authorize); oppure l'acquisizione è PENDING presso PayPal, per esempio in verifica del pagamento; oppure l'importo o la valuta pagati non corrispondono all'ordine; oppure il pagamento non è stato leggibile nella risposta di PayPal. La nota dell'ordine spiega il motivo.

Failed: PayPal ha rifiutato l'acquisizione o l'autorizzazione.

Cancelled: l'autorizzazione è stata annullata con Void PayPal authorization.

Azioni sull'ordine

Apri l'ordine, scegli un'azione in Order actions e clicca sulla freccia.

Capture PayPal payment: acquisisce un pagamento autorizzato per il totale dell'ordine. Un'acquisizione completata porta l'ordine a In lavorazione. Visibile finché l'autorizzazione non è acquisita.

Void PayPal authorization: libera i fondi riservati e annulla l'ordine.

Check PayPal payment status: rilegge un'acquisizione PENDING. COMPLETED porta l'ordine allo stato In lavorazione, DECLINED o FAILED allo stato Non riuscito. Un'acquisizione completata per un importo o una valuta diversi lascia l'ordine In attesa con una nota di discrepanza.

Rimborsi

Apri l'ordine, clicca su Refund, inserisci l'importo e clicca su Refund via PayPal (il pulsante mostra il titolo del tuo metodo di pagamento). Sono supportati rimborsi totali e parziali. Il rimborso viene inviato all'ambiente PayPal in cui è stato effettuato il pagamento (sandbox o live), quindi devono essere impostate le credenziali di quell'ambiente. Il motivo viene passato a PayPal come nota per l'acquirente. Se PayPal non accetta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID e lo stato del rimborso PayPal; un rimborso PENDING viene completato da PayPal in seguito.

Un pagamento solo autorizzato non può essere rimborsato: usa invece Void PayPal authorization. Rimborsi, contestazioni e storni effettuati nel tuo account PayPal non vengono sincronizzati con WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > PayPal (Smart Buttons). Incolla la chiave in License key e clicca su Activate. Il blocco mostra lo stato, per esempio la data fino a cui 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 lo slot del dominio: liberalo dal tuo account vibefox.net.

Senza una chiave attiva, PayPal 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 con accesso effettuato vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così possono configurare e testare il plugin prima di acquistare una chiave. Un avviso compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: rimborsi e azioni sugli ordini continuano a funzionare.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

PayPal non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che Client ID e Secret della modalità selezionata siano compilati, che la valuta del negozio sia supportata da PayPal e che il totale del carrello sia superiore a zero. La pagina delle impostazioni mostra un avviso quando il problema riguarda credenziali o valuta. Un'estensione del browser che blocca www.paypal.com nasconde anch'essa il pulsante.

Il pagamento è andato a buon fine, ma l'ordine resta in Attesa di pagamento: il plugin non ha webhook, quindi il pagamento viene confermato solo durante il checkout. Succede quando PayPal non ha risposto durante l'acquisizione. Leggi la nota dell'ordine, verifica il pagamento nel tuo account PayPal e completa l'ordine manualmente, oppure lascia che il cliente riprovi: un nuovo tentativo non addebita mai due volte.

PayPal non è disponibile al momento: le credenziali sono errate o appartengono all'altra modalità. Copia di nuovo Client ID e Secret dell'app giusta.

La tua approvazione PayPal non può essere associata a questo checkout: l'ordine PayPal non è stato creato in questa sessione di checkout, per esempio perché la sessione è scaduta. Il cliente clicca di nuovo sul pulsante PayPal.

L'ordine è In attesa dopo il pagamento: leggi la nota dell'ordine. 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.

L'acquisizione di un'autorizzazione non riesce: l'autorizzazione potrebbe avere più di 29 giorni o essere già annullata. La nota dell'ordine mostra l'errore di PayPal.

Il rimborso non riesce: l'ordine non ha un'acquisizione PayPal (solo un'autorizzazione), oppure mancano le credenziali dell'ambiente in cui è stato effettuato il pagamento. Gli sviluppatori possono modificare l'elenco delle valute con il filtro wc_plg_supported_currencies.

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 sul 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 e poi 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 token di accesso PayPal in cache vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento, gli ID di transazione e gli ID PayPal.

PayPal è un marchio del rispettivo proprietario. Questo plugin non è affiliato a PayPal né approvato da PayPal.