VibeFox Autopay for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.
Servizio Autopay: ti servono il Service ID e la Shared key (chiave hash) del tuo servizio Autopay. Sono mostrati nel portale merchant di Autopay: portal.autopay.eu per la produzione, testportal.autopay.eu per il test. I servizi di test hanno un proprio Service ID e una propria Shared key; chiedi ad Autopay di aprirne uno. La funzione hash del servizio deve essere SHA-256.
Valuta: la valuta del carrello deve essere PLN, EUR, GBP, USD o CZK e accettata dal tuo servizio Autopay.
Negozio raggiungibile: Autopay deve poter inviare notifiche al tuo negozio, quindi deve essere raggiungibile da internet senza autenticazione di base e senza un firewall che blocchi le richieste POST. La modalità manutenzione e la restrizione per paese del negozio non bloccano le notifiche.
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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 Autopay Payment nell'elenco dei moduli e clicca su Configure.
3. Inserisci la chiave di licenza VibeFox in License key, nel blocco licenza in alto nella pagina Configure, e fai clic su Activate (vedi Chiave di licenza).
4. Inserisci il Service ID e la Shared key (test e produzione) e scegli le valute del tuo servizio.
5. Nel portale Autopay imposta per il tuo servizio l'URL ITN, l'URL di ritorno e la funzione hash SHA-256 (vedi Configurazione).
6. Attiva Enable/Disable e clicca su Save. Effettua un ordine di prova in modalità test, poi disattiva Test mode per i pagamenti reali.
All'installazione il modulo crea lo stato dell'ordine Autopay payment on hold. PrestaShop attiva 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 Autopay Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa se il Service ID o la Shared key dell'ambiente selezionato sono vuoti, e se la valuta predefinita del negozio non è selezionata in Currencies. In entrambi i casi il metodo di pagamento viene nascosto al checkout (per la valuta non selezionata).
Autopay
Enable/Disable: Enable Autopay payment gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Autopay. Obbligatorio.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.
Servizio Autopay
Service ID e Shared key sono mostrati nel portale merchant di Autopay (portal.autopay.eu o testportal.autopay.eu, collegati in questa sezione).
Test mode: usa l'ambiente di test di Autopay (testpay.autopay.eu) e le credenziali di test qui sotto. Predefinito: attivo. Disattivalo per accettare pagamenti reali su pay.autopay.eu con le credenziali di produzione.
Service ID (production): l'identificativo numerico del servizio da portal.autopay.eu.
Shared key (production): la chiave hash del servizio di produzione. Tienila segreta.
Service ID (test): l'identificativo numerico del servizio da testportal.autopay.eu.
Shared key (test): la chiave hash del servizio di test.
Al salvataggio, un Service ID con caratteri diversi da lettere, cifre, trattini o trattini bassi viene rifiutato con un errore e non viene salvato nulla. Le Shared key salvate non vengono mai più mostrate. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.
Clear saved keys: spunta una chiave e clicca su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.
Currencies: le valute accettate dal tuo servizio Autopay: PLN, EUR, GBP, USD, CZK. Di solito Autopay apre un servizio separato per ogni valuta. Il metodo di pagamento viene offerto solo quando la valuta del carrello è selezionata qui. Predefinito: PLN.
Notifiche di pagamento (ITN) e indirizzo di ritorno
Inserisci questi indirizzi nel portale Autopay per il tuo servizio, sia per la produzione sia per il test. Gli indirizzi esatti sono mostrati nel campo Addresses di questa sezione. Con URL parlanti hanno questo aspetto, eventualmente con un codice lingua come /en/:
Copia gli indirizzi esattamente come li mostrano le impostazioni. Senza l'URL ITN gli ordini non vengono mai creati, perché PrestaShop crea l'ordine solo quando Autopay conferma il pagamento. Ogni ITN viene verificata con l'hash SHA-256 calcolato con la Shared key del servizio indicato nella notifica. Le notifiche senza hash valido o con un Service ID sconosciuto vengono rifiutate. Una notifica viene applicata a un carrello solo se il suo pagamento è stato avviato con lo stesso servizio Autopay, quindi una notifica di test non conferma mai un pagamento di produzione. Le notifiche relative a pagamenti avviati prima di cambiare Test mode vengono comunque verificate con la chiave corretta, finché entrambe le credenziali restano salvate.
Il modulo gestisce questi stati di pagamento nell'ITN:
Avanzate
Logging: registra gli eventi di pagamento in logs/wc_ap_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi e dati dei clienti non vengono mai registrati. Predefinito: disattivato. Finché è disattivato non viene scritto nulla, inclusi gli errori.
Log: mostra la dimensione e le ultime voci del registro. Clicca su Clear log per svuotarlo.
Checkout
Al passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Autopay) con la sua descrizione e conferma. La pagina successiva mostra Thank you. You are being redirected to Autopay to complete the payment. Your order is created as soon as Autopay confirms it. e invia il cliente alla pagina di pagamento di Autopay. Se il cliente torna indietro con il pulsante Indietro del browser, la pagina mostra il pulsante Pay with Autopay invece di reindirizzare di nuovo. A questo punto non esiste ancora alcun ordine.
Il modulo passa il totale del carrello nella valuta del carrello, il numero del carrello come riferimento dell'ordine, la descrizione (Cart e il numero) e l'e-mail del cliente. Sulla pagina di Autopay il cliente sceglie il metodo di pagamento e paga.
L'ordine viene segnato come pagato solo dopo che Autopay lo ha confermato con un ITN firmato e importo e valuta corrispondono al carrello. L'ordine viene quindi creato e il cliente riceve le e-mail standard di PrestaShop. Dopo il pagamento il cliente torna nel tuo negozio. L'indirizzo di ritorno è firmato, ma non crea né modifica mai un ordine. Se l'ordine esiste già, il cliente vede la normale pagina di conferma dell'ordine. Se l'ITN non è ancora arrivato, una pagina Payment confirmation mostra Thank you. Your payment is being confirmed by Autopay — your order will be created as soon as Autopay confirms it, and you will receive an e-mail. con i pulsanti Check again e Back to checkout.
Se Autopay ha segnalato un pagamento fallito, il cliente torna al checkout con The payment was not completed. You can try again or choose another payment method. Il carrello viene conservato. Se il pagamento non può essere avviato, il cliente resta al checkout con un breve messaggio, ad esempio Autopay payments are not configured. Please choose another payment method or contact the store. oppure che Autopay non può accettare pagamenti in questa valuta.
Il modulo non gestisce rimborsi da PrestaShop, abbonamenti o pagamenti ricorrenti, carte salvate, codice BLIK o modulo carta nella pagina di checkout, scelta della banca o del canale di pagamento nella pagina di checkout, e usa un solo Service ID per ambiente.
Ordini
Stati dell'ordine
No order yet: il cliente è stato inviato ad Autopay e non ha pagato, il pagamento non è riuscito, oppure Autopay non ha ancora confermato il pagamento. Esiste solo il carrello.
Payment accepted: Autopay ha confermato il pagamento e importo e valuta corrispondono. Il pagamento viene registrato con l'ID transazione Autopay (remoteID) come ID transazione, e una nota mostra importo, transazione Autopay e data del pagamento.
Autopay payment on hold: Autopay ha segnalato un importo o una valuta diversi dal totale del carrello (per esempio il carrello è stato modificato dopo l'avvio del pagamento). L'ordine non viene segnato come pagato. Controlla la transazione nel portale Autopay e completala o rimborsala manualmente. Una successiva notifica corretta per questo ordine lo segna come pagato. Lo stesso stato viene usato quando arriva un pagamento per un ordine annullato: il pagamento viene registrato e una nota ti chiede di verificare le scorte ed evadere l'ordine, oppure di rimborsare il pagamento.
Un ordine pagato non viene mai modificato da una successiva notifica di fallimento. Se Autopay segnala un altro pagamento riuscito per un ordine pagato, una nota avverte che il cliente potrebbe aver pagato due volte. Una notifica relativa a un pagamento avviato con un altro servizio Autopay non viene applicata, e una nota lo spiega. Le note sono visibili solo allo staff, nel blocco Autopay payment della pagina dell'ordine.
Blocco Autopay payment
La pagina dell'ordine mostra un blocco Autopay payment con l'OrderID Autopay, il Service ID e l'ambiente, importo e valuta, lo stato del pagamento, l'ID transazione Autopay, un badge Test mode per i pagamenti di test e le Autopay notes dell'ordine. Il blocco è di sola lettura.
Rimborsi
I rimborsi tramite Autopay non sono supportati. Rimborsa il pagamento nel portale Autopay, quindi registralo in PrestaShop con gli strumenti standard per gli ordini.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Autopay Payment è il primo blocco di Modules > Module Manager > VibeFox Autopay Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo di che il blocco mostra la chiave mascherata, lo stato (per esempio la data fino alla quale 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-autopay e il collegamento 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 cambiare 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 con 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 multinegozio. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave di licenza attiva, Autopay 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. Il negozio non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento è nascosto anche per 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.
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
Autopay non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che l'ambiente selezionato abbia Service ID e Shared key e che la valuta del carrello sia selezionata in Currencies. La pagina delle impostazioni mostra un avviso se manca uno di questi elementi. 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: Autopay non ha consegnato l'ITN, oppure il negozio lo ha rifiutato. Verifica che l'URL ITN mostrato nelle impostazioni sia impostato per il servizio nel portale Autopay (produzione o test), che la funzione hash sia SHA-256 e che la Shared key nel modulo corrisponda al servizio. Verifica che il negozio sia raggiungibile da internet. Attiva Logging e controlla il campo Log nella pagina del modulo.
Il log mostra ITN rejected: invalid hash: la Shared key non corrisponde al servizio, oppure la funzione hash del servizio non è SHA-256.
Il log mostra che il Service ID non è configurato: la notifica proviene da un servizio il cui Service ID non è inserito nel modulo, oppure la cui Shared key è vuota.
Il log mostra could not lock the cart, Autopay will retry: il carrello era in elaborazione da un'altra notifica nello stesso momento. Il negozio risponde in modo che Autopay invii di nuovo la notifica. Lo stesso accade quando non è stato possibile creare l'ordine, per esempio perché il modulo è disattivato.
L'ordine è Autopay payment on hold con una nota di discrepanza: Autopay ha segnalato un importo o una valuta diversi dal totale del carrello. Controlla la transazione nel portale Autopay e completa o rimborsa l'ordine manualmente.
Una nota dice che la notifica NON è stata applicata: il pagamento per questo ordine non è stato avviato con questo servizio Autopay, per esempio una notifica di test per un ordine reale. Controlla la transazione nel portale Autopay.
Dopo il pagamento il cliente atterra sulla home page: non è stato possibile verificare l'indirizzo di ritorno, per esempio perché il Service ID non è inserito nel modulo. L'ordine non è interessato; segue l'ITN.
Il cliente vede This payment method is not available.: il metodo di pagamento non viene offerto per questo carrello (disattivato, credenziali mancanti, valuta non selezionata o non consentito in Payment > Preferences).
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox Autopay Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Vengono rimosse le impostazioni del modulo, incluse le chiavi, e il registro. Il modulo non offre un'opzione per conservare le impostazioni. I dati dei pagamenti Autopay e lo stato dell'ordine Autopay payment on hold vengono sempre conservati. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID transazione.
Autopay è un marchio del rispettivo proprietario. Questo modulo non è affiliato né approvato da Autopay.