VibeFox Autopay 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 successiva.

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 e testportal.autopay.eu per i 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 dell'ordine deve essere PLN, EUR, GBP, USD o CZK ed essere 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 o firewall che blocchi le richieste POST. La modalità manutenzione non blocca le notifiche, perché OpenCart lascia passare le richieste delle estensioni di pagamento.

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_autopay_payment-oc3-(versione).ocmod.zip e il pacchetto per OpenCart 4 wcp_autopay_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. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_autopay_payment-oc3-(versione).ocmod.zip. L'estensione non ha modifiche OCMOD, quindi Extensions > Modifications non deve essere aggiornato. Invece dell'installer puoi anche copiare il contenuto della cartella upload dell'archivio nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo Payments. Trova VibeFox Autopay 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 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.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_autopay_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 Autopay Payment, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passaggi da 3 a 6 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni. Cambiano solo gli indirizzi ITN e di ritorno (vedi Indirizzi ITN e di ritorno).

Una nuova installazione parte con il metodo di pagamento disattivato, la modalità test attiva e il PLN come unica valuta.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit. Le sezioni sono elencate a sinistra; il pulsante Save sotto l'elenco salva l'intera pagina. Sopra le impostazioni, la pagina ti avvisa quando il Service ID o la Shared key dell'ambiente selezionato sono vuoti (in quel caso il metodo di pagamento viene nascosto al checkout) e quando la valuta predefinita del negozio non è selezionata in Currencies (in quel caso il metodo di pagamento viene nascosto in quella valuta). Mentre la modalità test è attiva, mostra Test mode is on: payments go to the Autopay test environment (testpay.autopay.eu), no real money is taken. 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, Sort Order deve essere un numero intero, Total deve essere un numero pari o superiore a 0, e un Service ID può contenere solo lettere, cifre, trattini e trattini bassi. Se un campo contiene un errore, non viene salvato nulla e la pagina indica il campo.

Autopay

Enable/Disable: Enable Autopay payment gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Autopay. Obbligatorio, fino a 128 caratteri.

Description: il testo mostrato al cliente nel passaggio Confirm Order, sopra il pulsante di conferma. Predefinito: Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.

Sort Order: la posizione di Autopay tra i metodi di pagamento del checkout. Lascialo vuoto o inserisci un numero intero.

Geo Zone: mostra Autopay solo per gli indirizzi di pagamento della 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 Autopay venga proposto. Lascialo vuoto per proporre Autopay per qualsiasi importo.

Servizio Autopay

Il Service ID e la 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 indicate sotto. Predefinito: attivo. Disattivalo per accettare pagamenti reali su pay.autopay.eu con le credenziali di produzione. Mentre è attiva, i clienti vedono Test mode: no real payment is taken. nel passaggio Confirm Order.

Service ID (production): l'identificativo numerico del servizio su portal.autopay.eu.

Shared key (production): la chiave hash del servizio di produzione. Tienila riservata.

Service ID (test): l'identificativo numerico del servizio su testportal.autopay.eu.

Shared key (test): la chiave hash del servizio di test.

Le Shared key salvate non vengono più mostrate. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarlo. Per rimuovere una chiave salvata, seleziona Clear the saved key on save sotto il campo e clicca su Save.

Currencies: le valute che il tuo servizio Autopay accetta: PLN, EUR, GBP, USD, CZK. Autopay di solito apre un servizio separato per ogni valuta. Il metodo di pagamento viene proposto solo quando la valuta del checkout è selezionata qui. Predefinito: PLN.

Indirizzi ITN e 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 e sono costruiti a partire dall'indirizzo della vetrina della tua installazione di OpenCart:

Questi sono gli indirizzi per OpenCart 3. Su OpenCart 4 sono:

Copia gli indirizzi esattamente come li mostrano le impostazioni. Senza l'URL ITN gli ordini non vengono mai confermati: OpenCart mantiene l'ordine senza stato finché Autopay non conferma il pagamento. Ogni ITN viene verificato con l'hash SHA-256 calcolato con la Shared key del servizio indicato nella notifica. Le notifiche senza un hash valido o con un Service ID sconosciuto vengono rifiutate. Una notifica viene applicata a un ordine 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 dei pagamenti avviati prima di cambiare Test mode vengono comunque verificate con la chiave corretta, purché entrambe le credenziali restino salvate.

L'estensione gestisce questi stati di pagamento nell'ITN:

Orders

OpenCart crea l'ordine nel passaggio Confirm Order senza stato (un ordine mancante). L'ordine riceve uno stato solo quando Autopay conferma il pagamento (ITN SUCCESS). Un pagamento non riuscito o abbandonato lo lascia senza stato. Su OpenCart 4 un ordine non pagato del checkout può ricevere lo stato Voided, che OpenCart 4 imposta quando il cliente torna al passaggio Confirm Order; l'estensione tratta un ordine di questo tipo come un ordine senza stato, e un successivo ITN SUCCESS lo segna comunque come pagato. Ogni campo qui sotto elenca i tuoi stati ordine di OpenCart.

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

On Hold Status: l'importo o la valuta pagati non corrispondono all'ordine, oppure il pagamento è arrivato dopo che lo stato dell'ordine era stato modificato (per esempio 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.

Advanced

Logging: scrive gli eventi di pagamento in wc_ap_debug.log.php, nella cartella dei log di OpenCart (storage/logs). Il file non può essere aperto dal web e, al raggiungimento di 5 MB, viene spostato in wc_ap_debug.old.log.php. Chiavi e dati dei clienti non vengono mai registrati. Predefinito: disattivato. Finché è disattivato non viene scritto nulla, errori compresi.

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

Import / Export

Export: Download JSON salva le impostazioni in un file JSON. Le Shared key non vengono esportate.

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

Checkout

Nel passaggio Payment Method il cliente sceglie il metodo di pagamento (per impostazione predefinita, Autopay). Nel passaggio Confirm Order il cliente vede la tua descrizione e la nota You will be redirected to the secure Autopay payment page to complete the payment. OpenCart crea l'ordine in questo passaggio, ancora senza stato. Quando il cliente clicca su Confirm Order, il browser invia ad Autopay un modulo di pagamento firmato con il totale dell'ordine nella valuta dell'ordine, il numero d'ordine di OpenCart come OrderID, la descrizione Order seguita dal numero, e l'indirizzo 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 l'importo e la valuta corrispondono all'ordine. L'ordine riceve quindi il suo stato nel modo standard di OpenCart, con le consuete e-mail d'ordine e l'aggiornamento del magazzino. Dopo il pagamento il cliente torna nel tuo negozio. L'indirizzo di ritorno è firmato, ma non modifica mai un ordine. Se l'ordine ha già uno stato, il cliente vede la pagina di successo dell'ordine di OpenCart. Se l'ITN non è ancora arrivato, una pagina Payment confirmation mostra Thank you. Your payment is being confirmed by Autopay — your order is confirmed as soon as Autopay reports the payment, and you will receive an e-mail. con i pulsanti Check again e Back to checkout.

Se Autopay ha segnalato un pagamento non riuscito, il cliente torna al checkout con il messaggio The payment was not completed. You can try again or choose another payment method. Il carrello viene conservato. Ogni nuovo tentativo crea un nuovo ordine di OpenCart (su OpenCart 4 il cliente paga di nuovo lo stesso ordine, con un nuovo tentativo sotto lo stesso OrderID). Se un altro ordine dello stesso carrello (gli stessi prodotti nella stessa visita) è già stato pagato, il cliente va alla pagina di successo invece di pagare di nuovo. Un nuovo acquisto dopo uno completato è un nuovo carrello e viene pagato normalmente. Se non è possibile avviare il pagamento, il cliente resta nel passaggio Confirm Order con un breve messaggio sopra il pulsante, per 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.

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. Il messaggio sul pagamento non completato viene mostrato sopra la pagina del checkout. OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna. Se nel frattempo il negozio ha chiuso quell'ordine (per esempio perché lo hai annullato), il cliente torna al checkout con The payment was not completed. You can try again or choose another payment method., oppure, se l'ordine era stato pagato tramite Autopay, con Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order. Se l'ordine del checkout è già pagato per un carrello diverso, il messaggio è Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. Il successivo Confirm Order paga un nuovo ordine. Una modifica del carrello, inclusa una nuova quantità, conta come un nuovo carrello che richiede un proprio pagamento. L'ITN funziona anche mentre il negozio è in modalità manutenzione: su OpenCart 4 l'estensione aggiunge a questo scopo un'azione di avvio.

L'estensione non prevede rimborsi da OpenCart, abbonamenti o pagamenti ricorrenti, carte salvate, codice BLIK o modulo della carta nella pagina di checkout, scelta della banca o del canale di pagamento nella pagina di checkout, e usa un Service ID per ambiente.

Ordini

Order statuses

No status (missing order): il cliente è stato inviato ad Autopay e non ha pagato, il pagamento non è riuscito, oppure Autopay non ha ancora confermato il pagamento. In Sales > Orders questi ordini vengono mostrati solo con il filtro Order Status impostato su Missing Orders.

Order Status After Payment (default Processing): Autopay ha confermato il pagamento e importo e valuta corrispondono. Una nota mostra l'importo, l'ID della transazione Autopay (remoteID) e la data del pagamento.

On Hold Status (default Pending): Autopay ha segnalato un importo o una valuta diversi dal totale dell'ordine. 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 il cui stato nel frattempo è stato modificato, per esempio annullato: una nota ti chiede di controllare il magazzino 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 già pagato, oppure se viene pagato un secondo ordine dello stesso carrello, una nota avvisa 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 voci della History dell'ordine che il cliente non vede.

VibeFox Autopay Payment tab

In Sales > Orders apri un ordine pagato con Autopay. In fondo alla pagina dell'ordine, accanto a History e Additional, la scheda VibeFox Autopay Payment mostra l'OrderID at Autopay, il Service ID e l'ambiente con l'etichetta Test mode per i pagamenti di test, l'Amount, lo stato del Payment attempt, l'Autopay transaction ID e le Autopay notes dell'ordine. La scheda è di sola lettura e viene mostrata agli utenti che hanno accesso all'estensione.

Refunds

I rimborsi tramite Autopay non sono supportati. Rimborsa il pagamento nel portale Autopay, poi aggiorna manualmente l'ordine in OpenCart.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco di licenza License — VibeFox Autopay Payment è il primo blocco di Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad esempio la data fino a cui 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 compaiono la riga Product: opencart-payment-autopay 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, ad esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo una modifica dell'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 della 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, 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. 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 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 sono interessati: i pagamenti già avviati vengono comunque confermati.

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

Risoluzione dei problemi

Autopay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che l'ambiente selezionato abbia un Service ID e una Shared key, e che la valuta del checkout sia selezionata in Currencies. La pagina delle impostazioni mostra un avviso quando manca uno di questi elementi. 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: 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 dell'estensione corrisponda al servizio. Verifica che il negozio sia raggiungibile da internet. Attiva Logging e controlla il campo Log nella pagina dell'estensione.

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 nell'estensione, oppure la cui Shared key è vuota.

Il log mostra could not lock the order, Autopay will retry: l'ordine era in elaborazione da un'altra notifica nello stesso momento. Il negozio risponde in modo che Autopay invii di nuovo la notifica.

L'URL ITN mostra METHOD_NOT_ALLOWED nel browser: è normale. L'URL accetta solo richieste POST da Autopay.

L'ordine è nello stato di attesa con una nota di discrepanza: Autopay ha segnalato un importo o una valuta diversi dal totale dell'ordine. Controlla la transazione nel portale Autopay e completa o rimborsa l'ordine manualmente.

Una nota dice che la notifica NON è stata applicata: il pagamento di questo ordine non è stato avviato con questo servizio Autopay, per esempio una notifica di test per un ordine di produzione. Controlla la transazione nel portale Autopay.

Dopo il pagamento il cliente arriva alla home page: l'indirizzo di ritorno non è stato verificato, per esempio perché il Service ID non è inserito nell'estensione. L'ordine non è interessato; segue l'ITN.

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 o ha perso le sue credenziali nel frattempo. Il cliente ricarica il checkout.

Per gli sviluppatori: prima che il modulo di pagamento venga firmato, l'estensione attiva l'evento OpenCart wc_ap_payment_params con i parametri del modulo e l'ordine; servizio, numero d'ordine, importo e valuta non possono essere modificati da esso.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Payments e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Autopay Payment. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart rimuove le proprie impostazioni dell'estensione: Enable/Disable, Sort Order, Geo Zone, Total e gli stati dell'ordine della sezione Orders. L'estensione rimuove sempre anche le altre impostazioni del gateway, compresi i Service ID e le Shared key, e il log. Non esiste un'opzione per conservare le impostazioni. Su OpenCart 4 vengono rimossi anche gli eventi dell'estensione e la sua azione di avvio, che fa passare l'ITN in modalità manutenzione. I registri dei pagamenti Autopay vengono sempre conservati. Gli ordini esistenti conservano le loro note di pagamento.

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

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