VibeFox Paysera for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successive (testato su 4.1.0.3).

PHP: 8.0 o successivo.

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

Negozio raggiungibile: gli ordini ricevono lo stato dalla callback di Paysera, quindi il tuo negozio deve essere raggiungibile da internet, non protetto da login, autenticazione di base o firewall. La callback funziona anche mentre il negozio è in modalità manutenzione.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

È un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Estrailo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 wcp_paysera_payment-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 wcp_paysera_payment.ocmod.zip. Installa solo il pacchetto per la tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_paysera_payment-oc3-(version).ocmod.zip. L'estensione non ha modifiche OCMOD, quindi Extensions > Modifications non deve essere aggiornato. Invece dell'installer puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo Payments. Trova VibeFox Paysera Payment e clicca su Install (il pulsante verde +). Il tuo utente amministratore deve avere il permesso di modificare l'elenco delle estensioni di pagamento.

3. Clicca su Edit (il pulsante con la matita) per aprire la pagina delle impostazioni. Incolla la tua chiave di licenza VibeFox in License key, nel blocco della licenza in cima alla pagina, e clicca su Activate (vedi Chiave di licenza).

4. Inserisci il Project ID e la Project password del tuo account Paysera (vedi Configurazione).

5. Facoltativo: attiva Allow test payments nel progetto Paysera e Test payments nell'estensione per provare il flusso senza addebitare denaro. Disattivalo prima di vendere.

6. Attiva Enable/Disable e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_paysera_payment.ocmod.zip. Non rinominare il file: OpenCart 4 ricava il codice dell'estensione dal nome del file, e un pacchetto rinominato non funziona.

2. Il pacchetto compare nell'elenco delle estensioni installate nella stessa pagina. Clicca su Install (il pulsante verde +) accanto ad esso.

3. Vai su Extensions > Extensions e scegli il tipo Payments. Trova VibeFox Paysera Payment, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

4. Inserisci la chiave di licenza, l'ID e la password del progetto e le impostazioni di prova come nei passaggi da 3 a 6 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni. Cambia solo la Callback URL (vedi Progetto Paysera).

Una nuova installazione parte con il metodo di pagamento disattivato, i pagamenti di prova disattivati e l'ambiente Production.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Payments > VibeFox Paysera Payment > Edit. Le sezioni sono elencate a sinistra; il pulsante Save sotto l'elenco salva l'intera pagina. Sopra le impostazioni 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 i pagamenti di prova o la sandbox sono attivi. Senza il permesso di modificare l'estensione, la pagina mostra le impostazioni ma non può salvarle.

Al salvataggio, Title deve avere da 1 a 128 caratteri, Project ID deve contenere solo cifre, Sort Order deve essere un numero intero, Total deve essere un numero pari o maggiore di 0 e gli stati ordine devono esistere. Se una verifica fallisce, non viene salvato nulla e la pagina elenca gli errori.

Paysera

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

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, fino a 128 caratteri.

Description: il testo mostrato al cliente nel passaggio Confirm Order, sopra il pulsante di conferma. Predefinito: Pay securely via Paysera.

Sort Order: la posizione di Paysera tra i metodi di pagamento al checkout. Lascialo vuoto oppure inserisci un numero intero.

Geo Zone: offri Paysera solo per gli indirizzi di pagamento nella zona geografica selezionata. Predefinito: All zones. Le zone geografiche si configurano in System > Localisation > Geo Zones.

Total: il totale del checkout, nella valuta predefinita del negozio, che un ordine deve raggiungere prima che venga offerto Paysera. Lascialo vuoto per offrire Paysera per qualsiasi totale.

Progetto Paysera

Trova l'ID progetto e la password di progetto nel tuo account Paysera, alla voce Projects and activities, il tuo progetto, General project settings. La sezione contiene un link all'account Paysera.

Callback URL: l'indirizzo che Paysera usa per confermare ogni pagamento. Su OpenCart 3 ha questo aspetto: https://your-store/index.php?route=extension/payment/wcp_paysera_payment/callback, su OpenCart 4: https://your-store/index.php?route=extension/wcp_paysera_payment/payment/wcp_paysera_payment.callback. È costruito a partire dall'indirizzo della vetrina della tua installazione di OpenCart. Viene inviato automaticamente con ogni pagamento, quindi non c'è nulla da configurare in Paysera, ma deve essere raggiungibile da internet. Gli ordini ricevono lo stato solo da queste callback firmate o cifrate.

Project ID: l'ID numerico del tuo progetto Paysera. Sono accettate solo cifre: qualsiasi altro valore dà l'errore Project ID must contain digits only: the numeric ID of your Paysera project. e non viene salvato nulla.

Project password: la password di progetto (chiave di firma). Firma le richieste di pagamento e verifica le 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 cambiarlo. Per rimuovere la password salvata, seleziona Clear saved password (tick and save; an empty field keeps the saved value) sotto il campo e clicca su Save.

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 segnano gli ordini come pagati; quando è disattiva, un pagamento di prova mette l'ordine in attesa. Predefinito: disattivo. Finché è attiva, il cliente vede TEST MODE — no money will be charged. nel passaggio Confirm Order.

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

Ordini

OpenCart crea l'ordine nel passaggio Confirm Order senza stato (un ordine mancante). L'ordine riceve uno stato solo dalla callback di Paysera. Un pagamento annullato o non eseguito lascia l'ordine senza stato, e il cliente può pagare di nuovo. Ogni campo qui sotto elenca i tuoi stati ordine di OpenCart.

Order Status After Payment: lo stato impostato quando Paysera conferma il pagamento con l'importo e la valuta attesi. Predefinito: Processing.

Awaiting Payment Status: la banca ha accettato l'ordine di pagamento ma non lo ha ancora eseguito. L'ordine viene segnato come pagato quando Paysera conferma il pagamento. Predefinito: Pending.

On Hold Status: un pagamento di PROVA mentre Test payments è disattivo, un importo o una valuta diversi, oppure un pagamento dopo che il cliente lo ha annullato. L'ordine non viene segnato come pagato; una nota spiega il motivo. Predefinito: Pending, perché OpenCart non ha lo stato On hold. Puoi creare un tuo stato in System > Localisation > Order Statuses e selezionarlo qui.

Cancelled Order Status: l'estensione non imposta mai questo stato; lo legge soltanto: un pagamento che arriva per un ordine in questo stato non riapre l'ordine, aggiunge solo una nota. Predefinito: Canceled.

Avanzate

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

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

Delete data: se attivo, disinstallando l'estensione vengono eliminati le sue impostazioni e il suo log. I dati degli ordini (ordini, registri dei pagamenti Paysera) vengono sempre conservati. Predefinito: disattivo.

Importazione / Esportazione

Export: Download JSON salva le impostazioni in un file JSON. La password di progetto non viene esportata.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni. La password di progetto salvata viene mantenuta.

Checkout

Nel passaggio Payment Method il cliente sceglie il metodo di pagamento (per impostazione predefinita Paysera). Nel passaggio Confirm Order il cliente vede la tua descrizione e la nota You will be redirected to the Paysera payment window (bank links, cards and other Paysera methods) to complete the payment. OpenCart crea l'ordine in questo passaggio, ancora senza stato. Su OpenCart 4 il cliente sceglie il metodo di pagamento con il pulsante Choose del blocco del metodo di pagamento, nella finestra Payment method options, e clicca su Confirm Order in fondo alla pagina del checkout. Quando il cliente clicca su Confirm Order, l'estensione crea una richiesta di pagamento firmata con il numero d'ordine, il totale dell'ordine nell'unità minima della valuta dell'ordine, 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 vi sceglie una banca, una carta o un altro metodo.

Paysera conferma il pagamento con una callback da server a server. L'ordine viene segnato come pagato solo dopo che Paysera lo conferma con una callback firmata; il ritorno del cliente nel negozio non paga mai un ordine. L'ordine riceve poi il proprio stato nel modo standard di OpenCart, con le consuete e-mail d'ordine e l'aggiornamento del magazzino. Quando il cliente torna dopo la callback, viene mostrata la pagina di successo dell'ordine di OpenCart. Se la banca ha accettato l'ordine di pagamento ma non lo ha ancora eseguito, l'ordine riceve l'Awaiting Payment Status 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 attesa la pagina mostra Your payment is being reviewed. We will contact you if anything else is needed.

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

Se il cliente annulla nella finestra di Paysera, torna al checkout con il messaggio 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. Su OpenCart 4 questi messaggi compaiono sopra la pagina del checkout. OpenCart 3 crea un nuovo ordine ogni volta che viene mostrato il passaggio Confirm Order, mentre OpenCart 4 aggiorna l'ordine del checkout (un nuovo tentativo paga lo stesso ordine); se un altro ordine dello stesso carrello è già pagato, in attesa di pagamento o in verifica, un nuovo tentativo va direttamente alla pagina di successo invece che a un secondo pagamento. Una modifica del carrello, inclusa una nuova quantità, conta come un nuovo carrello che richiede il proprio pagamento.

OpenCart 4 mantiene l'ordine nel checkout finché non viene mostrata la pagina di successo. Se nel frattempo quell'ordine è stato chiuso (per esempio se hai annullato un ordine in attesa del bonifico bancario), il cliente torna al checkout con il messaggio Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order. Il successivo Confirm Order paga un nuovo ordine. Se quell'ordine era già stato pagato per un carrello precedente e il carrello nel frattempo è cambiato, il cliente torna al checkout, e il successivo Confirm Order paga un nuovo ordine del carrello attuale. Un ordine chiuso non viene mai mostrato come pagato.

Se il pagamento non può essere avviato, il cliente resta nel passaggio Confirm Order 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.

La callback funziona anche mentre il negozio è in modalità manutenzione, perché OpenCart lascia passare le richieste delle estensioni di pagamento (su OpenCart 4 l'estensione aggiunge a tale scopo una propria azione di avvio, che permette anche al cliente di tornare da Paysera).

L'estensione non prevede rimborsi dall'amministrazione, nessuna scelta di banca o metodo di pagamento nella pagina di checkout, nessun abbonamento, nessuna carta salvata e nessun servizio di consegna o corriere di Paysera.

Ordini

Stati ordine

Nessuno stato (ordine mancante): il cliente è stato inviato a Paysera e la callback non è ancora arrivata, oppure il cliente ha annullato, oppure il pagamento non è stato eseguito. In Sales > Orders questi ordini vengono mostrati solo con il filtro Order Status impostato su Missing Orders.

Order Status After Payment (predefinito Processing): Paysera ha confermato il pagamento con l'importo e la valuta corrispondenti. Una nota mostra la richiesta e il metodo di pagamento, contrassegnati con (TEST — no money charged) per i pagamenti di prova.

Awaiting Payment Status (predefinito Pending): Paysera ha accettato l'ordine di pagamento, ma la banca non lo ha ancora eseguito. L'ordine passa a Order Status After Payment quando Paysera conferma il pagamento.

On Hold Status (predefinito Pending): il pagamento richiede una verifica manuale. L'importo o la valuta pagati differiscono dal totale dell'ordine; un pagamento di PROVA è arrivato mentre Test payments è disattivo (non è stato addebitato denaro); oppure il pagamento è stato confermato dopo che il cliente lo aveva annullato. La nota lo spiega, e la scheda dell'ordine indica di verificare il pagamento nel tuo account Paysera e poi di impostare l'ordine allo stato pagato oppure annullarlo e rimborsare il pagamento in Paysera. Un successivo pagamento corretto per lo stesso ordine lo segna come pagato.

Cancelled Order Status (predefinito Canceled): un pagamento confermato più tardi per un ordine annullato non ne cambia lo stato. Una nota chiede di ripristinare l'ordine (impostandolo allo stato pagato) o di rimborsare il pagamento in Paysera. Se il metodo di pagamento dell'ordine non è più Paysera, un pagamento confermato aggiunge solo una nota.

Se arriva un altro pagamento riuscito per un ordine già pagato, o per un altro ordine di un carrello già pagato, l'ordine pagato non viene modificato e una nota chiede di rimborsare il duplicato nel tuo account Paysera. Gli altri stati Paysera (pagamento non eseguito, informazioni aggiuntive) aggiungono solo una nota. Le note sono voci della History dell'ordine che il cliente non vede.

Scheda VibeFox Paysera Payment

In Sales > Orders apri un ordine pagato con Paysera. In fondo alla pagina dell'ordine, accanto a History e Additional, la scheda VibeFox Paysera Payment mostra il Paysera order ID (il numero d'ordine e il tentativo), il Paysera request ID, l'Environment e un contrassegno TEST payment, lo Status del pagamento, gli importi Requested / paid, il Payment method e le Notes dell'estensione. Per un ordine in attesa mostra cosa verificare. La scheda mostra solo informazioni ed è visibile agli utenti che hanno accesso all'estensione.

Rimborsi

I rimborsi dall'amministrazione non sono supportati: il protocollo della finestra di pagamento di Paysera non ha API di rimborso. 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 OpenCart manualmente se necessario. I resi di prodotti in Sales > Returns non restituiscono denaro tramite Paysera.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Paysera Payment è il primo blocco della pagina Extensions > Extensions > Payments > VibeFox Paysera Payment > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca 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 controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto compaiono la riga Product: opencart-payment-paysera e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso Modify per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (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 un posto dominio nel tuo account, clicca su Check now. Se il server delle licenze non è raggiungibile, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto 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. Un utente amministratore connesso all'amministrazione nello stesso browser vede ancora il metodo di pagamento nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede il login dell'amministrazione, quindi senza una chiave attiva il metodo di pagamento è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati dalla callback.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare l'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Paysera non appare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo e che siano inseriti sia Project ID sia Project password. La pagina delle impostazioni mostra un avviso finché uno dei due manca. Controlla anche che l'indirizzo di pagamento sia nella Geo Zone selezionata e che l'ordine raggiunga il Total impostato nelle impostazioni.

Il pagamento è andato a buon fine, ma l'ordine resta senza stato: l'ordine riceve il suo stato dalla callback di Paysera, non dal ritorno del cliente. Controlla 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 dell'estensione.

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

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

La callback risponde Order not found: l'ordine nella callback non ha un pagamento Paysera in questo negozio, per esempio perché il pagamento è stato avviato in un altro negozio con lo stesso progetto.

La callback risponde Gateway not configured, Busy o Temporary error: l'ID o la password del progetto sono vuoti, un'altra callback per lo stesso carrello è ancora in esecuzione, oppure non è stato possibile impostare lo stato dell'ordine. Paysera ripete la 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 di PROVA paga un ordine solo mentre Test payments è attivo. Altrimenti l'ordine viene messo in attesa con una nota che indica che non è stato addebitato denaro. Attiva anche Allow test payments nel progetto Paysera.

Un ordine è in attesa con una nota su una differenza di importo o valuta: Paysera ha confermato un pagamento il cui importo o la cui valuta differisce dal totale dell'ordine. Confronta il pagamento nel tuo account Paysera e accetta l'ordine oppure rimborsa il pagamento manualmente.

Il cliente vede Paysera payments are temporarily unavailable: consulta 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.

Il cliente vede This payment method is not available. Please reload the checkout page.: la sessione di checkout non corrisponde più all'ordine, oppure il metodo di pagamento è stato disattivato nel frattempo. Il cliente ricarica il checkout.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Payments e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Paysera Payment. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart rimuove sempre le proprie impostazioni dell'estensione: Enable/Disable, Sort Order, Geo Zone, Total e gli stati ordine della sezione Orders, che tornano ai valori predefiniti alla reinstallazione. Viene rimosso anche l'evento di OpenCart dell'estensione (su OpenCart 4 anche i suoi eventi e la sua azione di avvio, che lasciano passare la callback e il ritorno del cliente in modalità manutenzione). Se Delete data è attivo, vengono eliminate le altre impostazioni (titolo, descrizione, ID e password del progetto, test, log) e il log. Se è disattivo, vengono conservate per una reinstallazione successiva. I registri dei pagamenti Paysera vengono sempre conservati. Gli ordini esistenti conservano le proprie note di pagamento.

Per rimuovere anche i file dell'estensione su OpenCart 4, dopo la disinstallazione vai su Extensions > Installer, clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Paysera Payment nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

Paysera è un marchio del rispettivo proprietario. Questa estensione non è affiliata a Paysera né approvata da Paysera.