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

Progetto Paysera: ti servono l'ID progetto e la password di progetto (sign key) del tuo progetto Paysera. I metodi di pagamento che il cliente vede sono quelli attivati in questo progetto. Non occorre configurare nulla in Paysera per il callback: il suo URL viene inviato con ogni richiesta di pagamento.

Negozio raggiungibile: gli ordini vengono creati dal callback di Paysera, quindi il tuo negozio deve essere raggiungibile da internet, non dietro un login, un'autenticazione di base o un firewall. Il callback funziona anche quando il negozio è in modalità manutenzione.

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 Paysera Payment nell'elenco dei moduli e fai clic su Configure.

3. Incolla 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 Project ID e la Project password dal tuo account Paysera (vedi Configurazione).

5. Facoltativo: attiva Allow test payments nel progetto Paysera e Test payments nel modulo per provare il flusso senza addebitare denaro. Disattivali prima di iniziare a vendere.

6. Attiva Enable/Disable e fai clic su Save.

All'installazione il modulo crea due stati dell'ordine: Awaiting Paysera payment e Paysera payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Paysera Payment > Configure. Ogni sezione ha un proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Paysera is hidden at checkout until the project ID and the project password are entered. finché manca uno dei due, e Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders. mentre sono attivi i pagamenti di prova o la sandbox.

Paysera

Enable/Disable: Enable Paysera Payment attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Paysera. Obbligatorio.

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

Progetto Paysera

Trova l'ID progetto e la password di progetto nel tuo account Paysera, in Projects and activities, poi il tuo progetto e General project settings.

Callback URL: l'indirizzo che Paysera usa per confermare ogni pagamento. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_paysera_payment/callback, eventualmente con un codice lingua. Viene inviato automaticamente con ogni pagamento, quindi non va configurato nulla in Paysera, ma deve essere raggiungibile da internet. Gli ordini vengono creati solo da questi callback firmati.

Project ID: l'ID numerico del tuo progetto Paysera. Sono accettate solo cifre: qualsiasi altro valore mostra l'errore Project ID must be a number: the numeric ID of your Paysera project. e non viene salvato nulla.

Project password: la password di progetto (sign key). Firma le richieste di pagamento e verifica i callback di Paysera. La password salvata non viene più mostrata. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

Clear saved password: spunta Project password e fai clic su Save per rimuovere la password salvata. Un campo vuoto mantiene il valore salvato.

Test

Test payments: invia i pagamenti in modalità di prova, quindi non viene addebitato denaro. Paysera restituisce un pagamento di prova riuscito senza addebitare il cliente. Attiva prima Allow test payments nelle impostazioni del progetto Paysera. Finché questa opzione è attiva, i pagamenti di prova contrassegnano gli ordini come pagati; quando è disattivata, un pagamento di prova mette l'ordine in sospeso. Predefinito: off. Mentre è attiva, i clienti vedono TEST MODE — no money will be charged. sotto il metodo di pagamento.

Environment: dove viene inviato il cliente. Mantieni Production per un normale progetto Paysera, anche per i pagamenti di prova. Predefinito: Production.

Avanzate

Debug log: scrive gli eventi di pagamento in logs/wc_psr_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre scritti; gli altri passaggi solo finché questa opzione è attiva. Password e dati dei clienti non vengono mai scritti. Predefinito: off.

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

Delete data: se attiva, la disinstallazione del modulo rimuove le impostazioni del modulo e il log. I dati degli ordini (ordini, registrazioni dei pagamenti Paysera, stati dell'ordine) vengono sempre conservati. Predefinito: off.

Checkout

Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Paysera) e conferma l'ordine. Il modulo crea una richiesta di pagamento firmata con il totale del carrello nell'unità minima della valuta del carrello, il nome, l'e-mail e l'indirizzo di fatturazione del cliente, e la lingua della pagina del negozio (lituano, lettone, estone, russo, tedesco, polacco, altrimenti inglese). Il cliente viene inviato alla finestra di pagamento di Paysera e lì sceglie una banca, una carta o un altro metodo. A questo punto l'ordine non esiste ancora.

Paysera conferma il pagamento con un callback server-to-server. L'ordine viene contrassegnato come pagato solo dopo la conferma di Paysera con un callback firmato; il ritorno del cliente nel negozio non crea né paga mai un ordine. Quando il cliente torna dopo il callback, viene mostrata la normale pagina di conferma dell'ordine. Se la banca ha accettato l'ordine di pagamento ma non lo ha ancora eseguito, l'ordine viene creato in Awaiting Paysera payment e la pagina mostra Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Per un ordine in sospeso la pagina mostra Your payment is being reviewed. We will contact you if anything else is needed.

Se il cliente torna prima del callback, una pagina Payment confirmation spiega che l'ordine verrà creato non appena Paysera confermerà il pagamento e offre Check again e Back to checkout.

Se il cliente annulla nella finestra di Paysera, torna al checkout con The Paysera payment was cancelled. You can try again or choose another payment method. Se Paysera segnala che il pagamento non è stato eseguito, il messaggio è The payment was not completed. You can try again or choose another payment method. Il carrello viene conservato in entrambi i casi. Se il carrello ha già un ordine, un nuovo tentativo porta direttamente alla conferma dell'ordine invece che a un secondo pagamento.

Se il pagamento non può essere avviato, il cliente resta al checkout con Paysera payments are temporarily unavailable. Please choose another payment method. oppure, per un totale d'ordine non valido, con This order cannot be paid via Paysera. Il motivo viene scritto nel log.

Il callback funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo non offre rimborsi dal back office, né scelta di banca o metodo di pagamento sulla pagina di checkout, né abbonamenti, carte salvate o servizi di consegna o corriere Paysera.

Ordini

Stati dell'ordine

No order yet: il cliente è stato inviato a Paysera e il callback non è ancora arrivato, oppure il cliente ha annullato. Esiste solo il carrello.

Payment accepted: Paysera ha confermato il pagamento con importo e valuta corrispondenti. Il pagamento viene registrato con l'ID richiesta Paysera come ID transazione, e una nota mostra la richiesta e il metodo di pagamento, contrassegnata da (TEST — no money charged) per i pagamenti di prova.

Awaiting Paysera payment: Paysera ha accettato l'ordine di pagamento, ma la banca non lo ha ancora eseguito. L'ordine passa a Payment accepted quando Paysera conferma il pagamento.

Paysera payment on hold: il pagamento richiede una verifica manuale. L'importo o la valuta pagati differiscono dal carrello o dal totale dell'ordine, è arrivato un pagamento TEST mentre Test payments era disattivato (non è stato addebitato denaro), oppure il pagamento è stato confermato dopo che il cliente lo aveva annullato. Il pagamento non viene registrato. La nota lo spiega e il blocco Paysera ti chiede di verificare il pagamento nel tuo account Paysera, poi di impostare l'ordine su Payment accepted oppure annullarlo e rimborsare il pagamento in Paysera.

Cancelled: un pagamento confermato in seguito per un ordine annullato non modifica il suo stato. Una nota chiede di ripristinare l'ordine (impostandolo su Payment accepted) o di rimborsare il pagamento in Paysera. Un successivo pagamento TEST o una discrepanza di importo per un ordine annullato aggiunge anch'esso solo una nota.

Se arriva un altro pagamento riuscito per un ordine già pagato, l'ordine non viene modificato e una nota ti chiede di rimborsare il duplicato nel tuo account Paysera. Altri stati Paysera (pagamento non eseguito, informazioni aggiuntive) aggiungono solo una nota.

Blocco pagamento Paysera

La pagina dell'ordine mostra un blocco Paysera payment con l'ID ordine Paysera (il numero del carrello e il tentativo), l'ID richiesta Paysera, l'ambiente e un contrassegno TEST payment, lo stato del pagamento, gli importi richiesto e pagato, il metodo di pagamento e le note del modulo.

Rimborsi

I rimborsi dal back office non sono supportati: il protocollo della finestra di pagamento Paysera non ha un'API per i rimborsi. Effettua i rimborsi nel tuo account Paysera. Quando Paysera segnala un rimborso, all'ordine viene aggiunta una nota con l'importo rimborsato, e lo stato dell'ordine non cambia. Registra il rimborso in PrestaShop manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Paysera Payment è il primo blocco di Modules > Module Manager > VibeFox Paysera Payment > Configure, sopra le impostazioni. Incolla la chiave in License key e fai clic su Activate. Dopodiché 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 verificare 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-paysera 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 un cambio dell'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, Paysera 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 per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo al checkout. Un promemoria appare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati dal callback.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato 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 alla 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

Paysera non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che siano inseriti Project ID e Project password. La pagina delle impostazioni mostra un avviso finché uno dei due manca. 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 nessun ordine è stato creato: l'ordine viene creato dal callback di Paysera, non dal ritorno del cliente. Verifica che il tuo negozio sia raggiungibile da internet all'indirizzo Callback URL mostrato nelle impostazioni (non dietro un login, un'autenticazione di base o un firewall), e controlla il campo Log nella pagina del modulo.

Il callback risponde Invalid signature: la Project password non corrisponde al progetto, oppure il callback non proviene da Paysera. Copia di nuovo la password di progetto. Se hai cambiato progetto o password, i pagamenti avviati prima della modifica non possono più essere verificati.

Il callback risponde Project ID mismatch: il Project ID nelle impostazioni è diverso dal progetto che ha effettuato il pagamento.

Il callback risponde Order not found: il carrello nel callback non ha un pagamento Paysera in questo negozio, per esempio perché il pagamento è stato avviato in un altro negozio con lo stesso progetto.

Il callback risponde Gateway not configured, Busy o Temporary error: l'ID o la password del progetto sono vuoti, un altro callback per lo stesso carrello è ancora in esecuzione, oppure l'ordine non è stato creato (per esempio perché il modulo è disattivato). Paysera ripete il callback. Attiva Debug log per vedere il motivo.

Paysera rifiuta la finestra di pagamento o dice che il progetto non esiste: controlla Environment. Un normale progetto Paysera funziona solo con Production; Sandbox richiede un progetto creato nell'ambiente sandbox di Paysera.

Il pagamento di prova non paga l'ordine: un pagamento TEST paga un ordine solo se Test payments è attivo. Altrimenti l'ordine viene messo in sospeso con una nota che indica che non è stato addebitato denaro. Attiva anche Allow test payments nel progetto Paysera.

Un ordine è Paysera payment on hold con una nota su una discrepanza di importo o valuta: Paysera ha confermato un pagamento il cui importo o la cui valuta differisce dal totale del carrello, per esempio perché il carrello è stato modificato in un'altra scheda dopo che il cliente aveva avviato il pagamento. Confronta il pagamento nel tuo account Paysera e accetta l'ordine oppure rimborsa il pagamento manualmente. Un successivo pagamento corretto per lo stesso ordine lo contrassegna come pagato.

Il cliente vede Paysera payments are temporarily unavailable: controlla il campo Log. L'ID o la password del progetto potrebbero essere vuoti, oppure uno degli indirizzi del negozio inviati a Paysera supera i 255 caratteri.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Paysera Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data è attivo, vengono rimosse le impostazioni del modulo e il log. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I registri dei pagamenti Paysera e gli stati dell'ordine Awaiting Paysera payment e Paysera payment on hold vengono sempre conservati. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.

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