VibeFox PayPlug 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.

Valuta e importi: euro (EUR), da 0,99 a 20.000,00 per pagamento, i valori predefiniti di PayPlug. Con un'altra valuta o al di fuori di questi limiti il metodo di pagamento viene nascosto.

Account PayPlug: ti servono le chiavi segrete del tuo account PayPlug: la chiave di test (sk_test_...) e/o la chiave live (sk_live_...). Non servono altre chiavi e non è necessario configurare alcuna notifica in PayPlug. Il tuo sito deve essere raggiungibile da internet per ricevere le notifiche; altrimenti gli ordini vengono aggiornati quando il cliente torna da PayPlug.

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_payplug_gateway in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > PayPlug > 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 chiavi segrete dal portale PayPlug (vedi Configurazione).

6. Attiva Enable/Disable e salva. Prova un pagamento con Test Mode attivo, poi disattivalo per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > PayPlug. Sopra i campi la pagina ti avvisa quando il metodo di pagamento è attivo ma la chiave segreta della modalità corrente è vuota, e quando la valuta del negozio non è EUR. In entrambi i casi il metodo di pagamento viene nascosto al checkout. Nell'elenco dei metodi di pagamento PayPlug mostra un badge della modalità test in modalità test ed è contrassegnato come da configurare finché la modalità corrente non ha una chiave segreta.

Checkout

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

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

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely by card via PayPlug.

Chiavi API

Trova le chiavi segrete nel portale PayPlug, in Developers > API keys. La sezione mostra anche l'URL di notifica che il plugin invia con ogni pagamento. Ha questo aspetto: https://your-site/wc-api/ppg_payplug_webhook/. In PayPlug non serve alcuna configurazione delle notifiche.

Test Mode: Enable test mode usa la chiave segreta di test per i nuovi pagamenti. Non viene elaborato alcun pagamento reale. I pagamenti effettuati nell'altra modalità continuano a usare la chiave della propria modalità per i controlli di stato e i rimborsi. Predefinito: on.

Test Secret Key: la tua chiave segreta di test PayPlug. Inizia con sk_test_.

Live Secret Key: la tua chiave segreta live PayPlug. Inizia con sk_live_.

Una chiave con il prefisso sbagliato non viene salvata. La pagina mostra, per esempio, Test Secret Key deve iniziare con "sk_test_". È stato mantenuto il valore precedente.

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 debug logging registra le chiamate API e le notifiche in WooCommerce > Status > Logs, origine wcp_payplug_gateway. Gli errori vengono sempre registrati. Chiavi segrete, dati della carta e dati dei clienti non vengono mai registrati. Predefinito: off.

Delete Data on Uninstall: Remove all plugin data when uninstalling. Se selezionata, le impostazioni del plugin e i suoi log vengono eliminati quando il plugin viene cancellato. Gli ID di pagamento PayPlug memorizzati negli ordini vengono conservati. Predefinito: off.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita PayPlug) e invia l'ordine. In modalità test il checkout mostra Modalità test: non verrà effettuato alcun pagamento reale. Il plugin crea un pagamento PayPlug per il totale dell'ordine in centesimi e invia il cliente alla pagina di pagamento PayPlug. I dati di fatturazione e di spedizione dell'ordine e la lingua del tuo sito vengono passati a PayPlug. Lì il cliente paga con carta.

Dopo il pagamento, il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo quando PayPlug lo conferma: il plugin legge il pagamento dall'API di PayPlug quando arriva la notifica e quando il cliente torna indietro. Un pagamento riuscito porta il cliente alla pagina di conferma dell'ordine.

Se il cliente annulla sulla pagina di PayPlug, la pagina di pagamento viene chiusa presso PayPlug, quindi non può essere pagata per errore in seguito. Il cliente torna alla pagina Pay for order con un messaggio, per esempio Hai annullato il pagamento PayPlug. Puoi riprovare o scegliere un altro metodo di pagamento., La sessione di pagamento PayPlug è scaduta. Riprova o scegli un altro metodo di pagamento. oppure Il pagamento PayPlug non è riuscito. Riprova o scegli un altro metodo di pagamento.

Quando il cliente paga di nuovo lo stesso ordine, il plugin controlla prima il tentativo precedente. Se nel frattempo è stato pagato, l'ordine viene completato senza un nuovo pagamento. Se è ancora aperto per lo stesso importo, viene riutilizzata la stessa pagina di pagamento. Altrimenti la vecchia pagina viene chiusa presso PayPlug e ne viene creata una nuova.

Se PayPlug non riesce ad avviare il pagamento, il cliente vede un breve messaggio, per esempio PayPlug non ha potuto accettare i tuoi dati di fatturazione (CAP). Controllali e riprova. oppure Impossibile raggiungere il fornitore di pagamenti. Riprova tra un momento. Il motivo tecnico viene aggiunto alle note dell'ordine.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con High-Performance Order Storage (HPOS) di WooCommerce.

I pagamenti vengono addebitati immediatamente. Il plugin non include rate Oney, Bancontact, Apple Pay o American Express, carte salvate con un clic, modulo di pagamento integrato, abbonamenti né addebito differito.

Ordini e rimborsi

Order statuses

Pending payment: il cliente è stato inviato a PayPlug e non ha ancora pagato, oppure PayPlug non ha ancora confermato il pagamento.

Processing or Completed: il pagamento è stato confermato. Lo stato segue Order Status After Payment. La nota dell'ordine mostra il pagamento PayPlug e la sua modalità. L'ID transazione è l'ID del pagamento PayPlug (pay_...).

On hold: l'importo o la valuta pagati non corrispondono all'ordine (nota amount/currency mismatch); oppure è stato effettuato un pagamento di test mentre il negozio è in modalità live, quindi non sono arrivati soldi; oppure il pagamento è arrivato per un ordine che era stato annullato; oppure un pagamento è autorizzato ma non acquisito (acquisiscilo nel portale PayPlug; l'ordine viene segnato come pagato quando PayPlug lo comunica come pagato). La nota dell'ordine spiega cosa controllare.

Failed: l'ultimo tentativo di pagamento di un ordine in attesa è fallito o è stato annullato. Il fallimento di un tentativo precedente non cambia l'ordine. Il cliente può pagare di nuovo.

Se anche un secondo tentativo su un ordine già pagato viene pagato, l'ordine non cambia. Una nota ti chiede di rimborsare il pagamento duplicato nel portale PayPlug.

Rimborsi

Apri l'ordine, clicca su Refund, inserisci l'importo e clicca su Refund via PayPlug. Sono supportati rimborsi totali e parziali. Il rimborso va al pagamento che ha effettivamente saldato l'ordine, con la chiave segreta della modalità (test o live) in cui è stato effettuato, quindi quella chiave deve essere impostata. Se PayPlug 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 di rimborso PayPlug.

I rimborsi effettuati nel portale PayPlug arrivano tramite notifica e vengono aggiunti alle note dell'ordine. Non vengono creati automaticamente in WooCommerce. Registrali manualmente se necessario.

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 > PayPlug. 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, PayPlug 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: 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 verificato di nuovo automaticamente in background.

Risoluzione dei problemi

PayPlug non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità corrente abbia una chiave segreta (Test Secret Key in modalità test, Live Secret Key in modalità live), che la valuta del negozio sia EUR e che il totale dell'ordine sia compreso tra 0,99 e 20.000,00 EUR. Gli account con altri limiti possono modificarli con il filtro ppg_amount_limits (valori in centesimi).

Il pagamento è andato a buon fine, ma l'ordine resta in Attesa di pagamento: la notifica non è arrivata al tuo negozio e il cliente non è tornato. Verifica che il tuo sito sia raggiungibile da internet all'URL di notifica mostrato nelle impostazioni, per esempio che nessuna modalità manutenzione, firewall o protezione con password lo blocchi. Controlla WooCommerce > Status > Logs, origine wcp_payplug_gateway, per le notifiche rifiutate.

La notifica risponde Verification failed: il pagamento non è stato possibile leggerlo dall'API di PayPlug, per esempio perché PayPlug non ha risposto. L'ordine non cambia e PayPlug invia di nuovo la notifica.

La notifica risponde Busy, retry: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento, per esempio il ritorno del cliente. PayPlug invia di nuovo la notifica.

La notifica risponde Unknown payment o Payment does not belong to the order: il pagamento non è stato creato da questo negozio o non riguarda questo ordine, per esempio un pagamento di un altro negozio sullo stesso account PayPlug. Viene ignorato.

Il cliente vede Payment could not be initiated: il tentativo di pagamento precedente dell'ordine è in fase di conferma in questo momento, oppure PayPlug ha rifiutato la richiesta. Attendi un momento e riprova; le note dell'ordine mostrano l'errore di PayPlug.

L'ordine è In attesa dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta pagati non corrispondevano all'ordine, è stato effettuato un pagamento di test mentre il negozio è in live, oppure il pagamento è arrivato dopo che l'ordine era stato annullato. Elabora l'ordine o rimborsa il pagamento.

Il rimborso fallisce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità test o live, e la chiave segreta di quella modalità non è configurata. 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 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 log 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 di pagamento PayPlug.

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