VibeFox PayU for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo rifiuta l'installazione su versioni di PHP precedenti.

Valuta: una tra PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH. La valuta deve essere abilitata anche per il tuo punto vendita in PayU. Per le altre valute, l'opzione di pagamento non viene mostrata al checkout.

Accesso a Internet al tuo negozio: PayU invia le notifiche di pagamento al tuo negozio, quindi deve essere raggiungibile da Internet (non protetto da autenticazione HTTP o firewall). Senza notifiche, i pagamenti vengono comunque verificati quando il cliente torna da PayU.

Account PayU: servono quattro chiavi del tuo punto vendita (POS): POS ID, Second key (MD5), OAuth client_id e OAuth client_secret. Si trovano nel pannello commerciante PayU in Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Le chiavi sandbox provengono da un account sandbox PayU separato.

Chiave di licenza VibeFox: acquistata 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 cerca più tardi VibeFox PayU Payment nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in cima alla pagina Configure e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci le quattro chiavi Sandbox e le quattro chiavi Live (vedi Configurazione). In PayU non serve configurare alcun URL di notifica.

5. Attiva Enable/Disable e fai clic su Save. Lascia attivo Test Mode finché non hai effettuato un pagamento di prova, poi disattivalo per accettare pagamenti reali con le chiavi Live.

All'installazione il modulo crea due stati dell'ordine: Awaiting PayU payment confirmation e PayU 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 PayU Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa quando la modalità sandbox è attiva (La modalità sandbox (test) è attiva: i pagamenti vanno alla sandbox PayU e non viene addebitato denaro reale. Non spedire ordini pagati in modalità test.), quando manca una delle quattro chiavi della modalità corrente e quando PayU non accetta la valuta predefinita del negozio. Negli ultimi due casi PayU non viene mostrato al checkout.

Al salvataggio, spazi e interruzioni di riga vengono rimossi da tutte le chiavi, perché copiandole dal pannello PayU spesso ne vengono aggiunti. Un Title vuoto non viene salvato: la pagina mostra Inserisci un titolo per il metodo di pagamento.

PayU

Enable/Disable: Enable PayU payment gateway attiva o disattiva l'opzione di pagamento. Predefinito: disattivato.

Title: il titolo del metodo di pagamento mostrato al cliente. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: PayU. Obbligatorio.

Description: la descrizione del metodo di pagamento mostrata al cliente al checkout. Predefinito: Pay securely via PayU.

Credenziali API

Trova le chiavi nel pannello commerciante PayU: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Le chiavi sandbox provengono da un account sandbox PayU separato. Tutte e quattro le chiavi di una modalità devono essere compilate.

Test Mode: usa la sandbox PayU e le chiavi Sandbox qui sotto. Non viene addebitato denaro reale. Mentre è attivo, i clienti vedono Modalità sandbox: nessun pagamento reale viene effettuato. sotto l'opzione di pagamento. Disattivalo per accettare pagamenti reali con le chiavi Live. Predefinito: attivo.

Live POS ID: il POS ID (merchantPosId) del tuo punto vendita di produzione.

Live Second Key (MD5): serve a verificare la firma delle notifiche PayU.

Live OAuth Client ID: l'OAuth client_id del punto vendita.

Live OAuth Client Secret: l'OAuth client_secret del punto vendita.

Sandbox POS ID: il POS ID del tuo punto vendita sandbox PayU.

Sandbox Second Key (MD5): serve a verificare la firma delle notifiche della sandbox PayU.

Sandbox OAuth Client ID: l'OAuth client_id del punto vendita sandbox.

Sandbox OAuth Client Secret: l'OAuth client_secret del punto vendita sandbox.

Le Second Key e i client secret salvati non vengono mai più mostrati. Il campo resta vuoto e mostra Salvato — lascia vuoto per mantenerlo. Inserisci un nuovo valore solo se vuoi cambiarlo. POS ID e client ID vengono mostrati come salvati.

Clear saved secrets: seleziona un segreto e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Ogni pagamento ricorda il proprio ambiente. Notifiche, controlli di stato e rimborsi di un pagamento usano sempre le chiavi di quell'ambiente, quindi i pagamenti precedenti continuano a funzionare dopo il cambio di modalità. Una notifica firmata con la chiave sandbox non viene mai accettata per un pagamento live, e viceversa.

Notifiche di pagamento

Notification URL: mostra l'indirizzo a cui PayU invia le notifiche. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_payu_payment/webhook, eventualmente con un codice lingua. Il modulo lo invia a PayU con ogni pagamento, quindi non c'è nulla da configurare nel pannello PayU. Assicurati che sia raggiungibile da Internet (non bloccato da firewall o autenticazione HTTP). Le notifiche funzionano anche quando il negozio è in manutenzione e non sono bloccate dalla restrizione per paese del tuo negozio.

Avanzate

Receive payments automatically: riceve automaticamente i pagamenti in attesa di conferma. Conta solo se la ricezione automatica è disattivata per il tuo punto vendita nel pannello PayU: in tal caso i pagamenti attendono la conferma (WAITING_FOR_CONFIRMATION). Con questa opzione attiva, il modulo riceve subito questi pagamenti e l'ordine viene creato quando PayU segnala il pagamento come completato. Quando è disattiva, oppure se la ricezione fallisce, l'ordine viene creato in Awaiting PayU payment confirmation e tu ricevi o annulli il pagamento con i pulsanti nel blocco PayU dell'ordine. Predefinito: attivo.

Logging: registra eventi tecnici (numeri di carrello e di ordine, ID ordini PayU, stati, errori, senza chiavi né dati personali) nel file logs/wc_pu_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati; gli altri eventi solo quando questa opzione è attiva. Predefinito: disattivato.

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

Delete data on uninstall: elimina le impostazioni e i registri del modulo alla disinstallazione. Ordini e relativi dati di pagamento (transazioni PayU, rimborsi, stati dell'ordine) non vengono mai eliminati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie l'opzione di pagamento (per impostazione predefinita PayU) e vede la descrizione e la nota Verrai reindirizzato a PayU per completare il pagamento (BLIK, bonifico bancario, carta e altri metodi). Dopo la conferma, il modulo crea un ordine PayU per il totale del carrello nella valuta del carrello, con la descrizione Cart #, il numero del carrello e il nome del tuo negozio, e con prodotti, spedizione e confezione regalo da visualizzare sulla pagina PayU. Email, nome e telefono del cliente vengono trasmessi a PayU. La lingua della pagina PayU segue quella del negozio quando PayU la supporta, altrimenti è l'inglese. Il cliente viene indirizzato alla pagina PayU, sceglie lì un metodo e paga. A questo punto non esiste ancora alcun ordine.

Ogni tentativo di pagamento riceve un proprio ordine PayU. Quando il cliente riprova, il precedente pagamento PayU non completato del carrello viene annullato presso PayU, così un vecchio link di pagamento non può essere pagato due volte. Se il pagamento precedente risulta già pagato, viene creato l'ordine invece di un nuovo pagamento.

Il solo ritorno al tuo negozio non paga mai un ordine. L'ordine viene contrassegnato come pagato solo dopo la conferma di PayU: tramite una notifica firmata con la Second Key dell'ambiente del pagamento, oppure tramite un controllo lato server dello stato dell'ordine PayU al ritorno del cliente (al massimo una volta ogni 10 secondi per carrello). L'ordine PayU deve essere stato creato per questo carrello, e importo e valuta devono corrispondere. Il modulo gestisce questi stati PayU:

Dopo un pagamento confermato il cliente vede la consueta pagina di conferma dell'ordine. Per un ordine in attesa di conferma o in sospeso, la pagina aggiunge Il tuo pagamento è in fase di verifica. Ti invieremo un'email non appena sarà confermato. Se il pagamento di tale ordine viene annullato in seguito, la pagina mostra Il tuo pagamento PayU non è stato completato. Contattaci per questo ordine.

Se PayU non ha ancora confermato il pagamento quando il cliente torna, una pagina Payment confirmation mostra Non abbiamo ancora ricevuto la conferma del pagamento da PayU. Se il pagamento è stato interrotto, puoi riprovare: (oppure, quando PayU ha segnalato un errore, Il pagamento non è stato completato. Puoi riprovare:) con i pulsanti Pay again e Check again. La notifica crea l'ordine non appena arriva. Se il pagamento è stato annullato, il cliente torna al checkout con Il pagamento non è stato completato. Puoi riprovare o scegliere un altro metodo di pagamento. Il carrello viene conservato.

Se PayU non riesce ad avviare il pagamento, il cliente resta al checkout con Errore di pagamento. Riprova o scegli un altro metodo di pagamento. Il motivo tecnico viene scritto nel registro. Se mancano le chiavi della modalità corrente, il messaggio è Il gateway di pagamento non è configurato correttamente. Contatta l'amministratore.

Se un buono sconto nel carrello smette di essere valido tra il pagamento e la sua conferma, viene rimosso dall'ordine. L'ordine passa quindi a PayU payment on hold con una nota che indica il buono, perché il cliente ha pagato il prezzo scontato.

Il cliente sceglie il metodo di pagamento sulla pagina PayU, non nel tuo checkout. Il modulo non ha un modulo carta nel tuo negozio, né carte salvate o pagamenti con un clic, né abbonamenti, né widget di rate o credito PayU. Usa un solo punto vendita per ambiente.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a PayU e non ha pagato, oppure PayU non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted: il pagamento è stato confermato. Viene registrato con l'ID dell'ordine PayU come ID transazione, e una nota mostra l'ID dell'ordine PayU, l'importo e l'ambiente (sandbox o live).

Awaiting PayU payment confirmation: il pagamento è autorizzato e attende la tua decisione (ricezione automatica disattivata o fallita). Nessun pagamento è ancora registrato.

PayU payment on hold: l'importo o la valuta pagati non corrispondevano al carrello (l'ordine non è contrassegnato come pagato), un buono sconto è stato rimosso, un pagamento in attesa di conferma aveva un importo diverso, oppure è stato completato un pagamento per un ordine annullato (il pagamento viene registrato). La nota indica quale caso si è verificato. Controlla l'ordine ed evadilo oppure rimborsa il pagamento.

Payment error: il pagamento di un ordine in attesa di conferma è stato annullato o rifiutato.

Refunded: il pagamento è stato rimborsato interamente tramite il modulo.

Ogni notifica viene elaborata una sola volta: le notifiche ripetute non aggiungono note né modificano di nuovo l'ordine. Se per un ordine già pagato o rimborsato viene completato un altro pagamento, una nota ti chiede di rimborsarlo nel pannello PayU. Un pagamento in attesa di conferma su un ordine già pagato o chiuso viene annullato automaticamente, così il denaro non viene addebitato due volte.

Blocco pagamento PayU

La pagina dell'ordine mostra un blocco PayU payment con l'ID ordine PayU, l'extOrderId, lo stato PayU, l'importo pagato e rimborsato, un badge Sandbox per i pagamenti sandbox, la cronologia dei rimborsi e le PayU notes dell'ordine. Le azioni del blocco richiedono il permesso di modificare gli ordini; non serve l'accesso alle pagine Moduli.

Pagamenti in attesa di conferma

Per un ordine con un pagamento in attesa di conferma, il blocco mostra Receive PayU payment (waiting for confirmation) e Cancel PayU payment (release the funds). Dopo aver confermato la domanda, l'azione viene inviata a PayU con le chiavi dell'ambiente del pagamento, aggiunta alle note con il tuo nome, e il nuovo stato PayU viene applicato subito: un pagamento ricevuto imposta l'ordine su Payment accepted, uno annullato su Payment error.

Rimborsi

Nel blocco PayU payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via PayU. Conferma la domanda Rimborsare questo importo tramite PayU? Non è possibile annullare l'operazione. Sono supportati rimborsi completi e parziali. Il rimborso viene inviato per l'ordine PayU effettivamente pagato, con le chiavi dell'ambiente del pagamento, quindi quelle chiavi devono essere impostate. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da PayU: dopo una discrepanza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il motivo viene inviato come descrizione del rimborso. Se PayU rifiuta il rimborso, il blocco mostra l'errore di PayU e nessun rimborso viene registrato. Un rimborso completo imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.

I rimborsi sono asincroni presso PayU. Il modulo aggiunge subito una nota con l'ID e lo stato del rimborso PayU; lo stato finale arriva in seguito come notifica PayU e viene aggiunto alle note e alla cronologia dei rimborsi. Se PayU annulla un rimborso, la nota indica che il denaro non è stato restituito al cliente, e l'importo può essere rimborsato di nuovo.

Il modulo non crea note di credito. I pulsanti standard di rimborso di PrestaShop nella pagina dell'ordine non rimandano denaro tramite PayU.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza License — VibeFox PayU Payment è il primo blocco della pagina Modules > Module Manager > VibeFox PayU Payment > 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 si trovano la riga Product: presta-payment-payu 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, PayU non viene mostrato ai clienti al checkout. Se un pagamento viene comunque avviato, il cliente vede This payment method is not available. Please choose another one. Lo storefront di PrestaShop 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 puoi provarlo 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 dalle notifiche, e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il 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 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

PayU non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che tutte e quattro le chiavi della modalità corrente siano compilate: le chiavi Sandbox in modalità sandbox, le chiavi Live in modalità live. Verifica che la valuta del carrello sia tra quelle supportate. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente. La pagina delle impostazioni mostra un avviso quando mancano chiavi o la valuta del negozio non è supportata.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: PayU non ha ancora inviato la notifica, e il controllo di stato sulla pagina di ritorno non ha rilevato un pagamento completato. Verifica che la Notification URL mostrata nelle impostazioni sia raggiungibile da Internet. Attiva Logging per vedere cosa arriva. Il cliente può anche fare clic su Check again nella pagina Payment confirmation.

La notifica risponde Invalid signature: la notifica non è stata firmata con la Second Key di nessuno dei due ambienti. Controlla Live Second Key (MD5) e Sandbox Second Key (MD5). La risposta Invalid signature for this payment significa che la notifica è stata firmata con la chiave dell'altro ambiente rispetto a quello del pagamento.

La notifica risponde Ignored: unknown PayU order: l'ordine PayU non è stato creato da questo negozio, per esempio un altro negozio sullo stesso POS. PayU smette di riprovare.

La notifica risponde Busy, retry later: il carrello era in fase di conferma da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). PayU ripete la notifica. Attiva Logging per vedere il motivo.

L'URL di notifica mostra POST expected nel browser: è normale. L'URL accetta solo notifiche da PayU.

Il cliente vede Payment error scegliendo PayU: attiva Logging e controlla il campo Log nella pagina del modulo. Il registro mostra il codice HTTP e lo stato PayU. Impossibile autenticarsi con PayU (verifica OAuth client ID / secret). indica chiavi OAuth errate per la modalità corrente.

L'ordine è in PayU payment on hold: leggi le note nel blocco PayU payment (vedi Stati dell'ordine), poi evadi l'ordine oppure rimborsa il pagamento.

L'ordine è in Awaiting PayU payment confirmation: la ricezione automatica è disattivata per il tuo punto vendita e il pagamento attende te. Usa Receive PayU payment oppure Cancel PayU payment nel blocco PayU.

Il rimborso non riesce: Questo ordine non ha un pagamento PayU completato. Impossibile elaborare il rimborso. significa che PayU non ha ancora completato un pagamento per l'ordine. Un messaggio che indica la mancanza delle chiavi Sandbox o Live significa che il pagamento è stato effettuato in quell'ambiente e le sue chiavi non sono impostate. Inseriscile e riprova.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox PayU Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. I token di accesso PayU in cache vengono sempre rimossi. Se Delete data on uninstall è attivo, vengono rimosse le impostazioni del modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le transazioni e i rimborsi PayU e gli stati dell'ordine Awaiting PayU payment confirmation e PayU payment on hold vengono sempre conservati, 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.

PayU è un marchio registrato del rispettivo titolare. Questo modulo non è affiliato né approvato da PayU.