VibeFox GoPay for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 7.6 o successivo, installato e attivo. Il plugin non si attiva se manca.

PHP: 8.0 o successivo.

Valuta: GoPay accetta CZK, EUR, PLN, USD, GBP, HUF, RON e BGN. Con un'altra valuta, il metodo di pagamento viene nascosto nel checkout.

Account GoPay: ti servono il GoID, il Client ID e il Client Secret del tuo account commerciante GoPay. Si trovano nelle impostazioni di integrazione dell'account. L'account sandbox (di test) ha credenziali proprie. Non occorre configurare le notifiche nell'account GoPay, ma il tuo negozio deve essere raggiungibile da Internet.

Chiave di licenza VibeFox: acquistabile su vibefox.net. Una chiave funziona su un dominio.

Installazione

1. In WordPress vai a Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella wcp_gopay_gateway in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > GoPay > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel riquadro della licenza nella parte superiore della pagina e fai clic su Activate.

5. Inserisci GoID, Client ID e Client Secret della sandbox, lascia attivo Test Mode e attiva Enable/Disable.

6. Effettua un ordine di prova. Quando tutto funziona, inserisci le credenziali di produzione e deseleziona Test Mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > GoPay. Sotto la descrizione del gateway, la pagina mostra Sandbox mode — test payments only oppure Production mode — real payments. Ti avvisa se mancano il GoID, il Client ID o il Client Secret della modalità corrente o se GoPay non accetta la valuta del negozio. In entrambi i casi GoPay non viene offerto nel checkout. Nell'elenco dei metodi di pagamento il gateway è indicato come da configurare finché non sono presenti le credenziali della modalità corrente. Quando salvi, i token di accesso GoPay memorizzati nella cache vengono eliminati, così le nuove credenziali vengono usate subito.

Enable/Disable: Enable GoPay payment gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: titolo del metodo di pagamento mostrato nel checkout. Predefinito: GoPay.

Description: descrizione del metodo di pagamento mostrata nel checkout. Predefinito: Pay securely via GoPay - cards, wallets, bank transfers.

Credenziali API

GoID, Client ID e Client Secret sono mostrati nel tuo account commerciante GoPay (impostazioni di integrazione). L'account sandbox (di test) ha credenziali proprie. La documentazione API è disponibile su doc.gopay.com.

Test Mode: Enable sandbox/test mode invia i pagamenti a gw.sandbox.gopay.com con le credenziali sandbox. Non viene addebitato denaro reale. Deselezionalo per accettare pagamenti reali con le credenziali di produzione (gate.gopay.cz). Predefinito: attivato.

Sandbox GoID: il GoID del tuo account GoPay sandbox (di test).

Sandbox Client ID: il Client ID OAuth dell'account sandbox.

Sandbox Client Secret: il Client Secret OAuth dell'account sandbox.

Production GoID: il tuo ID commerciante GoPay (GoID).

Production Client ID: il Client ID OAuth di GoPay.

Production Client Secret: il Client Secret OAuth di GoPay.

Un GoID contiene solo cifre, per esempio 8123456789. Se inserisci un altro valore, la pagina mostra un errore e conserva quello precedente.

Pagamento

Payment Page Language: lingua della pagina di pagamento GoPay. Predefinito: Automatic (site language, then billing country). La modalità automatica usa la lingua del sito; se GoPay non la supporta, viene usato il paese di fatturazione e, in caso contrario, l'inglese. Puoi anche fissare una delle 19 lingue: ceco, inglese, slovacco, tedesco, polacco, ungherese, rumeno, bulgaro, croato, sloveno, estone, lettone, lituano, francese, italiano, spagnolo, portoghese, ucraino o russo.

Order Status After Payment: stato assegnato all'ordine quando il pagamento viene confermato. Viene impostato subito, con una sola modifica di stato e una sola e-mail al cliente.

Notifiche di pagamento

La notifica informa il tuo negozio che è stato effettuato un pagamento. L'URL di notifica viene inviato a GoPay con ogni pagamento, quindi non occorre configurare nulla nell'account GoPay. L'URL è mostrato nelle impostazioni. È simile a https://your-site/?gopay-api=gopay_payment_notification. Deve essere raggiungibile da Internet, senza protezione con password, modalità manutenzione o firewall che lo blocchino.

Le notifiche GoPay contengono solo l'ID del pagamento e non hanno una firma. Ogni notifica viene verificata chiedendo all'API GoPay lo stato del pagamento; inoltre, il pagamento deve essere stato creato dal plugin per un ordine del tuo negozio. Se non è possibile leggere lo stato da GoPay, il negozio risponde con un errore e GoPay ripete la notifica. Senza notifiche, un ordine viene confermato solo quando il cliente torna al negozio dopo aver pagato.

Avanzate

Logging: Enable logging scrive gli eventi GoPay in WooCommerce > Status > Logs, origine wcp_gopay_gateway. Gli errori vengono sempre registrati. Credenziali, token, dati delle carte, e-mail, telefono e indirizzo del cliente non vengono mai registrati. Predefinito: disattivato.

Delete Data on Uninstall: Delete plugin settings, cached access tokens and log files when uninstalled. Se attiva, l'eliminazione del plugin rimuove le impostazioni del gateway, i token di accesso GoPay memorizzati nella cache e i registri. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita GoPay) ed effettua l'ordine. Il plugin crea un pagamento GoPay per il totale dell'ordine nella valuta dell'ordine, includendo articoli, spedizione e commissioni, e invia il cliente alla pagina di pagamento GoPay. Qui GoPay mostra i metodi abilitati nel tuo account, come carte di pagamento, Apple Pay, Google Pay e bonifici bancari. A GoPay vengono trasmessi il nome di fatturazione, l'e-mail, il telefono e l'indirizzo del cliente; i campi vuoti non vengono inviati. In GoPay il pagamento appare come Order seguito dal numero dell'ordine.

Dopo il pagamento, il cliente torna al tuo negozio. L'ordine viene contrassegnato come pagato solo dopo la conferma di GoPay: tramite la notifica o una richiesta all'API GoPay quando il cliente torna. Se una notifica e il ritorno arrivano nello stesso momento, vengono gestiti uno dopo l'altro, quindi l'ordine non viene mai completato due volte. Dopo la conferma del pagamento, il cliente arriva alla pagina di conferma dell'ordine.

Se il pagamento non è stato completato, è stato annullato o è scaduto, il cliente viene portato alla pagina Pay for order con il messaggio The GoPay payment was not completed. You can try again or choose another payment method. oppure The GoPay payment was cancelled or has expired. You can try again or choose another payment method. Da quella pagina il cliente può pagare di nuovo un ordine non pagato. Per un ordine già pagato non viene creato un secondo pagamento GoPay.

Se GoPay non riesce ad avviare il pagamento, il cliente visualizza un breve messaggio, per esempio GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. oppure GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. Il motivo tecnico viene aggiunto alle note dell'ordine.

Il metodo di pagamento funziona nel checkout classico, nei blocchi Cart e Checkout e nella pagina Pay for order. In modalità sandbox il blocco Checkout mostra Sandbox mode: no real payment will be made. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il cliente sceglie il metodo di pagamento sulla pagina GoPay; non può sceglierlo in WooCommerce. Il plugin non supporta abbonamenti o pagamenti ricorrenti, carte salvate, moduli di pagamento integrati né l'acquisizione o l'annullamento delle preautorizzazioni da WooCommerce.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a GoPay e non ha ancora pagato, oppure GoPay 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 l'ID del pagamento GoPay e lo strumento di pagamento. L'ID della transazione è l'ID del pagamento GoPay.

On hold: GoPay ha confermato il pagamento, ma l'importo o la valuta non corrispondono all'ordine; oppure il pagamento è arrivato dopo l'annullamento dell'ordine; oppure il pagamento è solo preautorizzato e il denaro non è ancora stato acquisito. La nota dell'ordine ne spiega il motivo. Un pagamento preautorizzato deve essere acquisito in GoPay, poi devi completare l'ordine manualmente.

Failed: l'ultimo pagamento GoPay di un ordine non pagato è stato annullato o è scaduto.

Refunded: il pagamento GoPay dell'ordine è stato rimborsato interamente, per esempio dall'account GoPay.

Se viene pagato anche un altro tentativo di pagamento di un ordine già pagato, l'ordine non cambia. Una nota ti chiede di rimborsare il duplicato dall'account GoPay. Una nota simile viene aggiunta quando viene pagato con GoPay un ordine già contrassegnato come pagato senza GoPay, per esempio manualmente. Una notifica successiva non riapre mai un ordine pagato che hai annullato o rimborsato.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via GoPay. Sono supportati rimborsi totali e parziali. GoPay accetta rimborsi parziali solo 24 ore dopo il pagamento. Il rimborso viene inviato nella modalità in cui è stato effettuato il pagamento (sandbox o produzione), quindi devono essere configurate le credenziali di quella modalità. Se GoPay rifiuta il rimborso, WooCommerce mostra il messaggio di GoPay e non registra alcun rimborso. Un rimborso riuscito viene aggiunto alle note dell'ordine. Anche un rimborso accettato da GoPay per l'elaborazione successiva viene indicato come accettato.

I rimborsi effettuati nell'account GoPay arrivano tramite notifica. Un rimborso totale porta l'ordine allo stato «Rimborsato»; uno parziale aggiunge una nota. Non vengono registrati automaticamente come rimborsi WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il riquadro della licenza si trova in cima a WooCommerce > Settings > Payments > GoPay. Incolla la chiave in License key e fai clic su Activate. Il riquadro mostra lo stato, per esempio la data di scadenza della licenza 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 il relativo slot di dominio. Libera lo slot dal tuo account vibefox.net.

Senza una chiave attiva, GoPay non viene mostrato ai clienti nel checkout. Se un pagamento viene comunque avviato, il cliente vede This payment method is not available. Please choose another one. I responsabili del negozio connessi vedono comunque il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria appare nella pagina Plugins e nelle pagine WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando la licenza scade, il plugin continua a funzionare, ma per ricevere aggiornamenti e assistenza occorre rinnovarla. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

GoPay non compare nel checkout: controlla che la licenza sia attiva, Enable/Disable sia attivo, la modalità corrente abbia GoID, Client ID e Client Secret e la valuta sia CZK, EUR, PLN, USD, GBP, HUF, RON o BGN. Nella pagina Pay for order conta la valuta dell'ordine. La pagina delle impostazioni mostra un avviso se le credenziali o la valuta non sono corrette.

Il pagamento è stato eseguito, ma l'ordine resta Pending payment: GoPay non ha potuto raggiungere l'URL di notifica mostrato nelle impostazioni e il cliente non è tornato al negozio. Rimuovi la protezione con password, la modalità manutenzione o le regole del firewall che bloccano l'URL. Controlla che siano impostate le credenziali della modalità usata per il pagamento, perché ogni notifica viene verificata con quelle credenziali. Consulta WooCommerce > Status > Logs, origine wcp_gopay_gateway. GoPay ripete le notifiche che non hanno ricevuto una risposta corretta.

La notifica risponde «Order not found»: il pagamento non è stato creato da questo negozio oppure il relativo ordine è stato eliminato.

La notifica risponde «Payment state could not be verified»: non è stato possibile raggiungere l'API GoPay oppure le credenziali di quella modalità sono errate. GoPay ripete la notifica.

Il cliente vede un errore quando effettua l'ordine: apri le note dell'ordine o attiva Logging. La nota mostra l'errore GoPay. Di solito la causa è l'uso di credenziali errate o di quelle dell'altra modalità. Un messaggio sui dati di fatturazione indica che GoPay non ha accettato l'e-mail, il telefono o l'indirizzo.

I pagamenti di prova non confermano un ordine reale: sandbox e produzione sono separati. Ogni pagamento viene verificato nella modalità in cui è stato creato. Imposta Test Mode sulla modalità desiderata e usa le relative credenziali.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta pagati erano diversi da quelli dell'ordine, il pagamento è arrivato dopo l'annullamento dell'ordine oppure è solo preautorizzato.

Il rimborso non riesce: leggi il messaggio di GoPay. Un rimborso parziale è possibile solo 24 ore dopo il pagamento. Un messaggio relativo alla modalità indica che il pagamento è stato effettuato in sandbox o in produzione e che le credenziali di quella modalità non sono configurate.

Il riquadro della licenza mostra un errore: segui le indicazioni nel riquadro. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic 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.

Per gli sviluppatori: il filtro gopay_p_payment_payload modifica la richiesta di pagamento e gopay_p_icon modifica l'icona del metodo di pagamento.

Disinstallazione

La disattivazione del plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, i token di accesso memorizzati nella cache e i registri vengono rimossi solo se era attivo Delete Data on Uninstall. In caso contrario restano disponibili per una reinstallazione successiva. Gli ID dei pagamenti GoPay salvati negli ordini vengono sempre conservati. Gli ordini esistenti mantengono le note sui pagamenti e gli ID delle transazioni.

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