VibeFox GoPay for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non può essere installato con versioni precedenti di PHP.

Valuta: GoPay accetta CZK, EUR, PLN, USD, GBP, HUF, RON e BGN. Con un'altra valuta del carrello, il metodo di pagamento non viene mostrato al 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. Per le notifiche non c'è nulla da configurare nell'account GoPay, ma il tuo negozio deve essere raggiungibile da internet.

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 GoPay 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. Inserisci il GoID, il Client ID e il Client Secret del sandbox, lascia attivo Test Mode, attiva Enable/Disable e fai clic su Save.

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

Al momento dell'installazione il modulo crea lo stato d'ordine GoPay payment on hold. PrestaShop rende disponibile 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 GoPay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Sandbox mode — test payments only oppure Production mode — real payments. Avvisa quando mancano il GoID, il Client ID o il Client Secret della modalità corrente, e quando GoPay non accetta la valuta predefinita del negozio. In entrambi i casi GoPay non viene offerto al checkout. Al salvataggio, i token di accesso GoPay in cache vengono cancellati, quindi le nuove credenziali vengono usate subito.

GoPay

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

Title: il titolo del metodo di pagamento mostrato al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: GoPay. Obbligatorio: un titolo vuoto non viene salvato.

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

Credenziali API

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

Test Mode: invia i pagamenti a gw.sandbox.gopay.com con le credenziali sandbox. Non viene addebitato denaro reale. Disattivalo per accettare pagamenti reali con le credenziali di produzione. Predefinito: attivo.

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 fornito da GoPay.

Production Client Secret: il Client Secret OAuth fornito da GoPay.

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

I Client Secret salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Digita un nuovo valore solo per modificarlo.

Clear saved client secrets: seleziona la casella e fai clic su Save per rimuovere entrambi i Client Secret salvati. Un campo vuoto mantiene il valore salvato.

Pagamento

Payment Page Language: la lingua della pagina di pagamento GoPay. Predefinito: Automatic (site language, then billing country). L'opzione automatica usa la lingua del carrello del cliente; se GoPay non la supporta, decide il paese di fatturazione, altrimenti si usa l'inglese. Puoi anche fissare una delle 19 lingue: Czech, English, Slovak, German, Polish, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, French, Italian, Spanish, Portuguese, Ukrainian o Russian.

Order Status After Payment: lo stato d'ordine impostato quando il pagamento viene confermato.

I pagamenti che non corrispondono all'ordine, i pagamenti successivi a un annullamento e i pagamenti preautorizzati finiscono sempre in GoPay payment on hold.

Notifiche di pagamento

La notifica informa il tuo negozio che un pagamento è stato effettuato. L'Notification URL è mostrato in questa sezione e viene inviato a GoPay con ogni pagamento, quindi nell'account GoPay non va configurato nulla. Con URL SEO-friendly ha questo aspetto: https://your-shop/module/wcp_gopay_gateway/webhook, eventualmente con un codice lingua come /en/. Deve essere raggiungibile da internet: nessuna protezione con password né firewall davanti. Funziona anche mentre il negozio è in manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Le notifiche GoPay contengono solo l'ID del pagamento e nessuna firma. Ogni notifica viene verificata chiedendo all'API GoPay lo stato del pagamento, con le credenziali della modalità in cui il pagamento è stato effettuato, e il pagamento deve essere stato creato dal modulo per un carrello del tuo negozio. Quando lo stato non può essere letto da GoPay, il negozio risponde con un errore e GoPay ripete la notifica. Senza notifiche, un ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato.

Avanzate

Logging: scrive gli eventi GoPay in logs/gopay_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati. Credenziali, token, dati delle carte, indirizzo e-mail e nome del cliente non vengono mai registrati. Predefinito: disattivato.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del modulo, i token di accesso GoPay in cache e il registro. Gli ordini, i loro dati di pagamento GoPay e lo stato d'ordine GoPay payment on hold restano sempre. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita GoPay) e conferma. Il modulo crea un pagamento GoPay per il totale del carrello nella valuta del carrello, con prodotti, spedizione e confezione regalo, e invia il cliente alla pagina di pagamento GoPay. Lì GoPay offre i metodi di pagamento attivati nel tuo account GoPay, come carte di pagamento, bonifici bancari e portafogli digitali. Nome di fatturazione, e-mail, telefono e indirizzo del cliente vengono trasmessi a GoPay; i campi vuoti non vengono inviati. Su GoPay il pagamento compare come Order PS- 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 GoPay: tramite la notifica oppure tramite una richiesta all'API GoPay quando il cliente torna. Una notifica e un ritorno arrivati nello stesso momento vengono gestiti uno dopo l'altro, quindi viene creato un solo ordine. Il cliente vede poi la normale pagina di conferma dell'ordine. Se l'ordine è passato in GoPay payment on hold, la pagina aggiunge Your payment is being reviewed. We will contact you if anything else is needed.

Se GoPay non ha ancora confermato il pagamento quando il cliente torna (per esempio perché un bonifico bancario è in viaggio o GoPay non è raggiungibile), una pagina Payment confirmation mostra GoPay has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. con un pulsante Check again.

Se il pagamento non è stato completato, è stato annullato o è scaduto, il cliente torna al checkout con 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. Il carrello viene conservato e un nuovo tentativo crea un nuovo pagamento GoPay. Un carrello che ha già un ordine non viene mai addebitato di nuovo.

Se GoPay non riesce ad avviare il pagamento, il cliente resta al checkout con 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 scritto nel registro.

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

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a GoPay e non ha ancora pagato, oppure GoPay non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted or Delivered: il pagamento è stato confermato. Lo stato segue Order Status After Payment. Il pagamento viene registrato con l'ID del pagamento GoPay come ID transazione, e una nota mostra l'ID del pagamento e lo strumento di pagamento.

GoPay payment on hold: GoPay ha confermato il pagamento, ma importo, valuta o numero d'ordine differiscono dal carrello (per esempio il carrello è stato modificato dopo l'avvio del pagamento); oppure il pagamento è arrivato dopo l'annullamento dell'ordine; oppure il pagamento è solo preautorizzato e il denaro non è ancora stato acquisito. La nota lo spiega. Un pagamento preautorizzato va acquisito in GoPay; l'ordine passa poi allo stato pagato quando GoPay segnala il pagamento come effettuato.

Refunded: il pagamento GoPay dell'ordine è stato rimborsato interamente, tramite il modulo o nell'account GoPay.

Se un altro tentativo di pagamento di un ordine già pagato viene pagato a sua volta, l'ordine non cambia. Una nota chiede di rimborsare il duplicato nell'account GoPay. Una nota simile viene aggiunta quando un pagamento GoPay viene effettuato per un ordine già segnato come pagato senza GoPay, per esempio manualmente. Un ordine annullato o rimborsato non viene mai riaperto da una notifica successiva.

Blocco pagamento GoPay

La pagina dell'ordine mostra un blocco GoPay payment con l'ID del pagamento GoPay, lo stato GoPay e lo strumento di pagamento, l'importo del pagamento, gli importi pagato e rimborsato, un badge Sandbox per i pagamenti sandbox, il motivo di una verifica manuale, lo storico dei rimborsi e le GoPay notes dell'ordine.

Rimborsi

Nel blocco GoPay payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via GoPay. Conferma la domanda Refund this amount through GoPay? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine Modules. GoPay accetta rimborsi parziali solo entro 24 ore dal pagamento. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da GoPay, quindi dopo una differenza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato. Il rimborso viene inviato nella modalità in cui il pagamento è stato effettuato (sandbox o produzione), quindi le credenziali di quella modalità devono essere impostate. Se GoPay rifiuta il rimborso, il blocco mostra il messaggio di GoPay e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note; un rimborso accettato da GoPay per un'elaborazione successiva viene annotato come accettato. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.

Il modulo non crea note di credito (credit slips). I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite GoPay.

I rimborsi effettuati nell'account GoPay arrivano tramite notifica. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale aggiunge una nota. Non vengono aggiunti allo storico dei rimborsi del blocco.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox GoPay Gateway è il primo blocco della pagina Modules > Module Manager > VibeFox GoPay Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché 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 controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto di essi ci sono la riga Product: presta-payment-gopay 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 aver cambiato l'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, GoPay 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 sei connesso al back office, quindi il metodo di pagamento viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un 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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

GoPay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità corrente abbia il suo GoID, Client ID e Client Secret, e che la valuta del carrello sia una tra CZK, EUR, PLN, USD, GBP, HUF, RON o BGN. La pagina delle impostazioni mostra un avviso quando mancano le credenziali. 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: GoPay non è riuscito a raggiungere la Notification URL mostrata nelle impostazioni, e il cliente non è tornato nel negozio. Rimuovi la protezione con password o le regole del firewall che bloccano l'URL. Verifica che siano impostate le credenziali della modalità in cui il pagamento è stato effettuato, perché ogni notifica viene verificata con esse. Attiva Logging e controlla il campo Log. GoPay ripete le notifiche che non hanno ricevuto una risposta positiva.

Notification answers Order not found: il pagamento non è stato creato da questo negozio, oppure il suo carrello è stato eliminato.

Notification answers Payment state could not be verified: non è stato possibile raggiungere l'API GoPay, oppure le credenziali di quella modalità mancano o sono errate. GoPay ripete la notifica.

Notification answers Busy, retry later: il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure l'ordine non è stato creato (per esempio perché il modulo è disattivato). GoPay ripete la notifica. Attiva Logging per vedere il motivo.

Il cliente vede un errore quando sceglie GoPay: attiva Logging e controlla il campo Log. Credenziali errate, o credenziali dell'altra modalità, sono il motivo più comune. Un messaggio sui dati di fatturazione significa che GoPay non ha accettato e-mail, telefono o 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à che vuoi usare e utilizza le credenziali di quella modalità.

L'ordine è in GoPay payment on hold dopo il pagamento: leggi le note nel blocco GoPay payment. L'importo o la valuta pagati non corrispondevano al carrello, il pagamento è arrivato dopo l'annullamento dell'ordine, oppure il pagamento è solo preautorizzato.

Il rimborso non riesce: leggi il messaggio di GoPay nel blocco. Un rimborso parziale è possibile solo entro 24 ore dal pagamento. Un messaggio sulla modalità significa che il pagamento è stato effettuato in modalità sandbox o produzione e che le credenziali di quella modalità non sono impostate.

Per gli sviluppatori: l'hook actionGopayPaymentPayload modifica la richiesta di pagamento prima che venga inviata a GoPay.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox GoPay Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete Data on Uninstall è attivo, vengono rimosse le impostazioni del modulo, i token di accesso GoPay in cache e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I dati di pagamento GoPay degli ordini e lo stato d'ordine GoPay payment on hold restano sempre, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.

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