VibeFox CorvusPay for OpenCart — Guida

Requisiti

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

PHP: 8.0 o successivo.

Valuta: AUD, BAM, BHD, CAD, CHF, CZK, DKK, EUR, GBP, HRK, HUF, ISK, MKD, NOK, PLN, RON, RSD, RUB, SEK o USD. Per qualsiasi altra valuta del checkout, il metodo di pagamento viene nascosto al checkout. Gli importi vengono inviati con 2 decimali; un totale con più decimali (ad esempio in una valuta con 3 decimali come BHD) viene rifiutato invece di essere arrotondato.

Account CorvusPay: ti serve un account merchant CorvusPay. CorvusPay emette uno Store ID e una Secret Key per ogni negozio, separatamente per il negozio di test e per quello di produzione; sono mostrati nel CorvusPay Merchant Center. La Success URL e la Cancel URL dell'estensione devono essere inserite lì (vedi Configuration).

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

Installazione

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 wcp_corvuspay_gateway-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 wcp_corvuspay_gateway.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. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_corvuspay_gateway-oc3-(version).ocmod.zip. L'estensione non ha modifiche OCMOD, quindi Extensions > Modifications non deve essere aggiornato. In alternativa all'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 CorvusPay Gateway 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 License key).

4. Inserisci lo Store ID e la Secret Key del tuo negozio di test CorvusPay (e quelli del negozio di produzione per i pagamenti reali). Copia la Success URL e la Cancel URL mostrate nella pagina delle impostazioni nel CorvusPay Merchant Center, sia per il negozio di test sia per quello di produzione.

5. Attiva Enable/Disable e clicca su Save. Effettua un ordine di prova, poi disattiva Test Mode per andare in produzione.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_corvuspay_gateway.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 a esso.

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

4. Inserisci la chiave di licenza, i dati dei negozi CorvusPay e gli URL del Merchant Center come nei passaggi 3–5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali nelle due versioni. Cambiano solo la Success URL e la Cancel URL (vedi Success e Cancel URL).

Una nuova installazione parte con il metodo di pagamento disattivato e la modalità test attiva.

Configuration

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > Edit. Le sezioni sono elencate a sinistra; il pulsante Save sotto l'elenco salva l'intera pagina. Sopra le impostazioni, la pagina mostra Test mode is on. Payments go to the CorvusPay test environment — no real money is taken. mentre la modalità test è attiva, ti avvisa quando il gateway è attivo ma lo Store ID o la Secret Key della modalità corrente sono vuoti (in quel caso il metodo viene nascosto al checkout finché non vengono compilati) e quando la valuta predefinita del tuo negozio non è supportata da CorvusPay. Senza il permesso di modificare l'estensione, la pagina mostra le impostazioni ma non può salvarle.

Al salvataggio, Title non può superare i 128 caratteri, Sort Order deve essere un numero intero, Minimum Total deve essere un numero non negativo, e la zona geografica e gli stati dell'ordine selezionati devono esistere; altrimenti non viene salvato nulla e la pagina elenca gli errori.

CorvusPay

Enable/Disable: Enable CorvusPay Gateway. attiva o disattiva il metodo di pagamento. Default: off.

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Default: Credit/Debit Card (CorvusPay). Fino a 128 caratteri; se lo lasci vuoto, viene mostrato il nome predefinito.

Description: il testo mostrato al cliente nel passaggio Confirm Order, sopra il pulsante di conferma. Default: Pay securely with your credit or debit card via CorvusPay. In modalità test viene aggiunto (Test mode — no real payment is taken.)

Sort Order: la posizione di CorvusPay tra i metodi di pagamento al checkout. Lascia il campo vuoto oppure inserisci un numero intero.

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

Minimum Total: il totale dell'ordine, nella valuta predefinita del negozio, che un ordine deve raggiungere prima che venga offerto CorvusPay. Lascia il campo vuoto se non c'è un minimo.

Credenziali del negozio

Lo Store ID e la Secret Key vengono emessi da CorvusPay per ogni negozio (test e produzione separatamente) e sono mostrati nel CorvusPay Merchant Center.

Test Mode: usa l'ambiente di test di CorvusPay (wallet.test.corvuspay.com) e lo Store ID e la Secret Key di test. Default: on. Disattivalo per accettare pagamenti reali su wallet.corvuspay.com.

Test Store ID: lo Store ID numerico del tuo negozio di test CorvusPay.

Test Secret Key: la Secret Key del tuo negozio di test CorvusPay, usata per le firme HMAC-SHA256.

Live Store ID: lo Store ID numerico del tuo negozio di produzione CorvusPay.

Live Secret Key: la Secret Key del tuo negozio di produzione CorvusPay, usata per le firme HMAC-SHA256.

Lo Store ID deve contenere solo cifre. Se inserisci qualcos'altro, la pagina mostra … must contain digits only — the previous value was kept. e gli altri campi vengono comunque salvati. Le Secret Key salvate non vengono mai mostrate di nuovo: il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarlo. Per rimuovere una chiave salvata, spunta Clear the saved value on save sotto il campo e clicca su Save. Un pagamento viene sempre verificato con la Secret Key del negozio in cui è stato avviato, quindi mantieni compilata la chiave di test finché possono arrivare pagamenti di test.

Success e Cancel URL

Copia i due indirizzi mostrati in Merchant Center URLs nel CorvusPay Merchant Center, sia per il negozio di test sia per quello di produzione. CorvusPay riporta il cliente a questi indirizzi dopo il pagamento. Sono costruiti a partire dall'indirizzo della vetrina della tua installazione di OpenCart; copiali esattamente come li mostra la pagina.

Pagamento

Transaction Type: come viene addebitata la carta.

Payment Page Language: la lingua della pagina di pagamento di CorvusPay. Site language (predefinito) usa la lingua corrente del tuo negozio quando CorvusPay la supporta, altrimenti l'inglese. Puoi anche scegliere Hrvatski, English, Deutsch, Italiano, Srpski o Slovenščina.

Order Status After Payment: lo stato dell'ordine dopo un pagamento Sale riuscito. Le opzioni puntano agli stati di OpenCart scelti nella sezione Order statuses.

Stati dell'ordine

OpenCart crea l'ordine nel passaggio Confirm Order senza stato (un ordine mancante). Questi sono gli stati di OpenCart che il gateway imposta; ogni campo elenca i tuoi stati ordine di OpenCart. OpenCart non ha uno stato On hold, quindi per Authorize only, per le differenze di importo o di valuta e per i pagamenti dopo un annullamento viene usato lo stato di revisione; una nota dell'ordine spiega il motivo.

Processing status: usato quando Order Status After Payment è Processing. Default: Processing.

Completed status: usato quando Order Status After Payment è Completed. Default: Complete.

On hold (review) status: Authorize only, differenza di importo o di valuta, pagamento dopo un annullamento, oppure Order Status After Payment impostato su On hold. Default: Pending. Puoi creare un tuo stato in System > Localisation > Order Statuses e selezionarlo qui.

Avanzate

Logging: scrive le informazioni di debug in corvuspay_p_debug.log.php, nella cartella dei log di OpenCart (storage/logs). Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche quando questa opzione è disattivata; segreti, firme e dati dei clienti non vengono mai registrati. Default: off.

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

Delete Data: se attivo, disinstallando l'estensione vengono rimosse le impostazioni del gateway e i file di log. Gli ordini e i dati delle transazioni CorvusPay vengono sempre conservati. Default: off.

Import / Export

Export: Download JSON salva le impostazioni in un file JSON. Le Secret Key non vengono esportate.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni. Le Secret Key salvate vengono mantenute.

Checkout

Nel passaggio Payment Method il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit/Debit Card (CorvusPay)). Nel passaggio Confirm Order il cliente vede la tua descrizione; OpenCart crea l'ordine in questo passaggio, ancora senza stato. Quando il cliente clicca su Confirm Order, la pagina mostra Redirecting to CorvusPay for payment. Please wait... e invia il modulo firmato alla pagina di pagamento di CorvusPay. Se il reindirizzamento non parte, il cliente clicca su Pay via CorvusPay. Vengono inviati il totale dell'ordine nella valuta dell'ordine, una breve descrizione (Order, il numero dell'ordine e il nome del negozio) e i dati di indirizzo e l'e-mail del cliente (per precompilare la pagina di pagamento). Lo stesso numero d'ordine CorvusPay viene riutilizzato finché non cambiano importo, valuta, modalità e tipo di transazione, e CorvusPay non accetta un secondo pagamento per esso. 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 di checkout. Se il negozio non chiede un indirizzo di pagamento (impostazione predefinita di OpenCart 4), i dati del titolare della carta vengono presi dal nome del cliente e dall'indirizzo di spedizione.

Dopo il pagamento, CorvusPay riporta il cliente alla Success URL. L'ordine viene segnato come pagato solo dopo la conferma di CorvusPay: il numero d'ordine CorvusPay deve essere stato emesso da questo negozio, la firma deve corrispondere alla Secret Key del negozio in cui è stato avviato il pagamento, e importo e valuta devono corrispondere all'ordine. L'ordine riceve poi il suo stato nel modo standard di OpenCart, con le consuete e-mail d'ordine e l'aggiornamento del magazzino, e il cliente vede la pagina di successo dell'ordine di OpenCart con Your CorvusPay payment has been received. Per Authorize only la pagina mostra Your CorvusPay payment has been authorized. The amount will be charged when the shop processes your order., e per un ordine nello stato di revisione Your payment was received and is being reviewed by the shop.

Se in quel momento il pagamento non può essere applicato (per esempio perché un'altra richiesta sta confermando lo stesso ordine), il cliente vede Your payment is being confirmed con un pulsante Check again, che porta alla pagina di successo non appena l'ordine ha uno stato. Se la richiesta alla Success URL non può essere verificata, il cliente vede Payment not confirmed e We could not confirm this CorvusPay payment. If your card was charged, please contact the shop — do not pay again. Non viene modificato nulla. La Success URL funziona anche mentre il negozio è in modalità manutenzione: OpenCart 3 lascia passare le richieste delle estensioni di pagamento, e su OpenCart 4 l'estensione aggiunge un'azione di avvio (startup action) per gli URL di successo e annullamento. Su OpenCart 4 il browser non invia la sessione del negozio quando CorvusPay rimanda il cliente indietro, quindi l'estensione mostra prima una breve pagina che riapre lo stesso indirizzo dal tuo negozio: il cliente conserva il carrello e l'accesso.

Se il cliente annulla nella pagina di CorvusPay, l'ordine resta senza stato e il cliente torna al checkout con il carrello intatto e il messaggio The CorvusPay payment was cancelled and the order was not paid. Your cart is still here — you can try again or choose another payment method. Su OpenCart 4 questo messaggio viene mostrato sopra la pagina di checkout. OpenCart 3 crea un nuovo ordine ogni volta che viene mostrato il passaggio Confirm Order; OpenCart 4 mantiene un solo ordine per il checkout e lo aggiorna, e un nuovo tentativo riceve un nuovo numero d'ordine CorvusPay. Se un altro ordine dello stesso carrello è già pagato, il cliente viene mandato alla pagina di successo invece di pagare di nuovo.

OpenCart 4 mantiene l'ordine nel checkout finché non viene mostrata la pagina di successo. Se nel frattempo quell'ordine è stato chiuso senza pagamento (per esempio lo hai annullato), Confirm Order o il ritorno da CorvusPay rimanda il cliente al checkout con Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Se l'ordine ha già uno stato e il carrello è cambiato da allora (altri prodotti o quantità), il messaggio è Your previous order is already placed. The cart has changed since then: please confirm the new order to pay for it. In entrambi i casi il successivo Confirm Order paga un nuovo ordine del carrello.

Se il pagamento non può iniziare, il cliente resta al passaggio Confirm Order con un breve messaggio sopra il pulsante: CorvusPay is not configured. Please choose another payment method., CorvusPay does not accept payments in … oppure This order total cannot be paid via CorvusPay (it must be greater than zero with at most 2 decimals). Please choose another payment method.

L'ordine viene confermato solo quando CorvusPay riporta il cliente alla Success URL; non ci sono notifiche da server a server. Se il cliente chiude il browser subito dopo aver pagato, l'ordine resta senza stato. L'estensione non gestisce rimborsi, acquisizioni o annullamenti da OpenCart (l'API server di CorvusPay richiede un certificato client), né carte salvate, abbonamenti, rate o un modulo carta nel negozio.

Ordini

Stati dell'ordine

Nessuno stato (ordine mancante): il cliente è stato inviato a CorvusPay e non è tornato con un pagamento confermato, oppure ha annullato il pagamento. In Sales > Orders questi ordini vengono mostrati solo con il filtro Order Status impostato su Missing Orders. Se il cliente ha pagato ma non è tornato, verifica il pagamento nel CorvusPay Merchant Center e imposta manualmente lo stato dell'ordine.

Processing, Completed o stato di revisione: il pagamento Sale è stato confermato. Lo stato segue Order Status After Payment. Una nota mostra il numero d'ordine CorvusPay, il codice di autorizzazione e il tipo di carta.

Stato di revisione, autorizzato: è selezionato Authorize only. Acquisisci il pagamento nel CorvusPay Merchant Center, poi cambia lo stato dell'ordine.

Stato di revisione, differenza di importo o di valuta: l'importo o la valuta pagati non corrispondono all'ordine. Non spedire prima di aver verificato il pagamento nel CorvusPay Merchant Center.

Stato di revisione, pagamento dopo l'annullamento: è arrivato un pagamento riuscito per un tentativo che il cliente aveva annullato. Evadi l'ordine oppure rimborsa il pagamento nel CorvusPay Merchant Center.

Se arriva un altro pagamento riuscito per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di controllare il CorvusPay Merchant Center e di rimborsare il pagamento duplicato, se necessario. Se arriva un pagamento per un altro ordine dello stesso carrello mentre un ordine è già pagato, quell'ordine resta senza stato e la nota viene aggiunta all'ordine pagato.

Le note sono voci della History dell'ordine che il cliente non vede.

Scheda VibeFox CorvusPay Gateway

In Sales > Orders apri un ordine pagato con CorvusPay. In fondo alla pagina dell'ordine, accanto a History e Additional, la scheda VibeFox CorvusPay Gateway mostra il CorvusPay order number, lo Status del tentativo di pagamento, il Transaction type, l'Amount (e l'importo ricevuto, se CorvusPay lo ha comunicato), l'Approval code, la Transaction, il tipo di Card e le CorvusPay notes. I pagamenti di test sono contrassegnati con Test. La scheda è in sola lettura ed è mostrata agli utenti che hanno accesso all'estensione.

Rimborsi: rimborsi, acquisizioni e annullamenti da OpenCart non sono supportati. Eseguili nel CorvusPay Merchant Center e registra manualmente il risultato in OpenCart. I resi di prodotti in Sales > Returns non restituiscono denaro tramite CorvusPay.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox CorvusPay Gateway è il primo blocco di Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > 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-corvuspay 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 oppure 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, 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 lo slot del dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, CorvusPay non viene mostrato ai clienti al checkout. Se comunque viene avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede ancora il metodo di pagamento nel negozio, contrassegnato da (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 l'accesso all'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 vengono toccati: i pagamenti già avviati vengono comunque confermati quando il cliente torna da CorvusPay.

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

Risoluzione dei problemi

CorvusPay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che lo Store ID e la Secret Key della modalità corrente siano compilati (Test Store ID e Test Secret Key in modalità test, Live Store ID e Live Secret Key in modalità live) e che la valuta del checkout sia supportata da CorvusPay. Verifica anche che l'indirizzo di pagamento rientri nella Geo Zone selezionata e che l'ordine raggiunga il Minimum Total.

Il pagamento è andato a buon fine, ma l'ordine resta senza stato: la Success URL probabilmente non è inserita nel CorvusPay Merchant Center, oppure la Secret Key di OpenCart non corrisponde al negozio. Cerca INVALID signature nel campo Log nella pagina dell'estensione (gli errori vengono sempre registrati). L'ordine resta senza stato anche se il cliente ha chiuso il browser prima di tornare; in quel caso verifica il pagamento nel Merchant Center e imposta manualmente lo stato dell'ordine.

Il cliente vede Payment not confirmed: la richiesta alla Success URL è stata rifiutata: mancavano campi obbligatori, il numero d'ordine CorvusPay non è stato emesso da questo negozio, la Secret Key di quel negozio è vuota oppure la firma non corrispondeva. Non viene modificato nulla. Il log mostra il motivo.

Il cliente vede a lungo Your payment is being confirmed: non è stato possibile impostare lo stato dell'ordine. Il log mostra il motivo; verifica il pagamento nel Merchant Center.

Il cliente vede This order total cannot be paid via CorvusPay: il totale è zero oppure ha più di 2 decimali.

Il cliente vede CorvusPay is not configured oppure CorvusPay does not accept payments in …: manca lo Store ID o la Secret Key della modalità corrente, oppure la valuta del checkout non è supportata.

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

L'ordine è nello stato di revisione: leggi le note nella scheda VibeFox CorvusPay Gateway. È selezionato Authorize only, l'importo o la valuta pagati non corrispondevano all'ordine, il pagamento è arrivato dopo che il cliente aveva annullato, oppure Order Status After Payment è impostato su On hold.

Per gli sviluppatori: prima che il modulo venga firmato, l'estensione attiva l'evento OpenCart corvuspay_p_form_params con i campi del modulo e l'ordine.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Payments e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox CorvusPay Gateway. 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, Minimum Total e gli stati della sezione Order statuses, che tornano ai valori predefiniti alla reinstallazione. Viene rimosso anche l'evento OpenCart dell'estensione (su OpenCart 4 i suoi eventi e la sua azione di avvio, che lascia passare le richieste di CorvusPay in modalità manutenzione). Se Delete Data è attivo, vengono rimosse le altre impostazioni del gateway (titolo, descrizione, Store ID, Secret Key, modalità test, impostazioni di pagamento, registrazione) e i file di log. Se è disattivo, vengono conservate per una successiva reinstallazione. I dati delle transazioni CorvusPay vengono sempre conservati, quindi la scheda CorvusPay degli ordini precedenti ricompare dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento.

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

CorvusPay è un marchio registrato del rispettivo titolare. Questa estensione non è affiliata a CorvusPay né approvata da CorvusPay.