VibeFox Moneris for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione SimpleXML. Il modulo non si installa su versioni PHP precedenti o senza SimpleXML.

Valuta del negozio: CAD per un account canadese Moneris, USD per un vecchio account Moneris USA. Il metodo di pagamento viene mostrato solo quando la valuta del carrello è quella dell'account.

HTTPS e PCI DSS: i numeri di carta vengono inseriti nel tuo checkout e transitano dal tuo server. I pagamenti reali richiedono HTTPS e la conformità a PCI DSS SAQ D. Se non puoi garantirla, usa invece una soluzione con pagina di pagamento ospitata.

Account Moneris: ti servono Store ID e API Token del tuo store Moneris Gateway, che trovi in Moneris Merchant Resource Center > Admin > Store Settings. Per i test, lo store di prova pubblico di Moneris è già compilato. Le credenziali di test e le carte di test si trovano nel portale per sviluppatori di Moneris.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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 Moneris Gateway 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. Scegli il paese dell'account e inserisci il Live Store ID e il Live API Token. La modalità test è attiva per impostazione predefinita e usa lo store di prova pubblico (store5 / yesguy per il Canada, monusqa002 / qatoken per gli USA).

5. Scegli Purchase o Pre-Authorization e i loghi delle carte, poi attiva Enable / Disable e fai clic su Save.

6. Effettua un ordine di prova con una carta di test Moneris, poi disattiva Test mode.

All'installazione il modulo crea due stati dell'ordine: Moneris payment authorized e Moneris payment on hold. PrestaShop abilita di default il 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 Moneris Gateway > Configure. Ogni sezione ha il suo pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Moneris gateway is in TEST MODE. No real charges will be made. finché la modalità test è attiva. In modalità live avvisa se i campi live contengono credenziali di test Moneris (il metodo di pagamento viene allora nascosto nel checkout) e se SSL non è attivo per il negozio. Avvisa anche se la valuta predefinita del negozio non è quella dell'account Moneris; il metodo di pagamento viene allora nascosto nel checkout per le altre valute.

Moneris

Enable / Disable: Enable Moneris Gateway attiva o disattiva il metodo 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: Credit card (Moneris). In modalità test, al titolo viene aggiunto (Test Mode). Obbligatorio.

Description: il testo mostrato sopra i campi della carta nel checkout. Predefinito: Pay securely with your credit card.

Account Moneris

Store ID e API Token si trovano nel Moneris Merchant Resource Center, in Admin > Store Settings. Le credenziali di test e le carte di test si trovano nel portale per sviluppatori di Moneris. La sezione contiene i link a entrambi.

Paese dell'account Moneris: gli account canadesi addebitano in CAD, quelli statunitensi in USD. Il metodo di pagamento viene mostrato solo se la valuta del carrello corrisponde. Predefinito: Canada (CAD).

Test mode: usa il gateway QA di Moneris e le credenziali di test; non viene effettuato alcun addebito reale. Acquisizioni, annullamenti e rimborsi vengono sempre inviati all'ambiente in cui è avvenuto il pagamento. I clienti vedono TEST MODE: use a Moneris test card, no real charges are made. sopra i campi della carta. Predefinito: attivo.

Live Store ID: lo Store ID di produzione, ad esempio monca01234.

Live API Token: l'API Token di produzione.

Test Store ID: lo store di prova pubblico di Moneris: store5 (Canada) o monusqa002 (USA). Predefinito: store5.

Test API Token: il token di prova pubblico: yesguy (Canada) o qatoken (USA). Predefinito: yesguy.

I token API salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

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

Pagamento

Transaction type: come viene addebitata la carta. Predefinito: Purchase.

Card logos: i marchi di carta mostrati insieme al metodo di pagamento nel checkout: Visa, Mastercard, Discover, American Express, JCB. I marchi accettati dipendono dal tuo account Moneris. Predefinito: Visa e Mastercard.

Avanzate

Debug log: registra le richieste e le risposte API in logs/wc_mng_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Numero di carta, CVV, scadenza e API token sono mascherati. Gli errori vengono sempre registrati, anche con l'opzione disattivata. Predefinito: disattivato.

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

Delete data on uninstall: se attiva, la disinstallazione del modulo rimuove le impostazioni del gateway e il registro. I dati Moneris degli ordini (necessari per i rimborsi) e gli stati dell'ordine restano sempre. Predefinito: disattivato.

Checkout

Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit card (Moneris)) e inserisce Card number, Expiry (MM/YY) e Card code (CVC) nel modulo carta sotto l'opzione. Tutti e tre i campi sono obbligatori. Al momento dell'ordine, il tuo server invia la carta a Moneris per il totale del carrello e ottiene il risultato subito. Non ci sono reindirizzamenti né webhook. I dati della carta vengono usati solo per questa richiesta; non vengono mai salvati, e il registro mostra solo le ultime quattro cifre.

L'ordine viene creato solo da una risposta approvata di Moneris. Il cliente vede poi la consueta pagina di conferma dell'ordine. Con Pre-Authorization l'ordine resta in Moneris payment authorized finché non acquisisci i fondi. Se Moneris ha elaborato un importo diverso dal totale del carrello, o il carrello è cambiato durante il pagamento, l'ordine viene creato in Moneris payment on hold con una nota.

Se la carta viene rifiutata, il cliente resta nel checkout con Your card was declined e il motivo indicato da Moneris, e può controllare i dati della carta o usarne un'altra. Non viene creato alcun ordine. Se Moneris non ha potuto elaborare la richiesta (ad esempio con uno Store ID o un API Token errati), il cliente vede The payment could not be processed. Please try again or use another payment method. Il motivo viene scritto nel registro. I dati della carta errati danno messaggi brevi come Invalid card number. o Invalid card expiry date., e nulla viene inviato a Moneris.

Un secondo clic o una seconda scheda del browser mentre un pagamento è in elaborazione mostra A payment for this order is already being processed. Please wait a moment and check your order status before trying again. Un carrello che ha già un ordine non viene mai addebitato di nuovo; il cliente viene reindirizzato all'ordine esistente.

Se Moneris non risponde (errore di rete o timeout), il modulo invia a Moneris uno Status Check con lo stesso ID dell'ordine Moneris per verificare se la transazione è andata a buon fine. Se Moneris non ha alcuna transazione del genere, il cliente può pagare di nuovo. Se anche lo Status Check non ottiene risposta, l'ordine viene creato in Moneris payment on hold con l'ID dell'ordine Moneris, e il cliente non viene invitato a pagare una seconda volta.

Il modulo non prevede carte salvate né Moneris Vault, abbonamenti, Apple Pay, Google Pay o Interac Online, Moneris Checkout o Hosted Tokenization, 3-D Secure, AVS o Kount, né prezzi in più valute.

Ordini e rimborsi

Stati dell'ordine

No order yet: la carta è stata rifiutata o non elaborata. Esistono solo il carrello e il tentativo nel registro. Il cliente può pagare di nuovo.

Payment accepted: l'acquisto è stato approvato. Il pagamento viene registrato con il numero di transazione Moneris come ID transazione.

Moneris payment authorized: una pre-autorizzazione è stata approvata e attende l'acquisizione. Nessun pagamento è ancora registrato.

Moneris payment on hold: l'importo elaborato era diverso dal totale del carrello, il carrello è cambiato durante il pagamento, Moneris non ha confermato il risultato, oppure PrestaShop ha scritto uno stato di pagato anche se l'acquisizione era fallita. Le note lo spiegano. Per un acquisto con importo diverso, il pagamento viene registrato con l'importo elaborato da Moneris.

Canceled: per un ordine pre-autorizzato, l'annullamento rilascia i fondi riservati (void).

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

Blocco Moneris payment

La pagina dell'ordine mostra un blocco Moneris payment con l'ID dell'ordine Moneris, il paese e la modalità dell'account, un badge Test mode per i pagamenti di test, il Trans ID (e il Trans ID della pre-autorizzazione dopo un'acquisizione), il tipo di transazione e il suo stato (non acquisita, acquisita o rilasciata), la ricevuta e il tipo di carta, l'importo elaborato, il totale dell'ordine e l'importo rimborsato, la cronologia dei rimborsi e le Moneris notes dell'ordine. Per un pagamento non confermato, il blocco ti chiede di cercare l'ID dell'ordine Moneris nel Merchant Resource Center. Tutte le azioni del blocco richiedono solo il permesso di modificare gli ordini.

Acquisizione e annullamento

Per acquisire una pre-autorizzazione, fai clic su Capture payment nel blocco e conferma, oppure porta l'ordine a uno stato di pagato come Pagamento accettato, Spedito o Consegnato. Viene acquisito il totale dell'ordine meno i rimborsi; non può superare l'importo autorizzato. Dopo un'acquisizione con il pulsante, l'ordine passa a Payment accepted; il pagamento viene registrato con il Trans ID dell'acquisizione. Se Moneris rifiuta l'acquisizione, lo stato non cambia, non viene inviata alcuna e-mail di pagamento e una nota lo spiega: Status not changed: the Moneris pre-authorization could not be captured con il motivo. Le pre-autorizzazioni Moneris scadono dopo alcuni giorni, quindi acquisiscile in tempo.

Per rilasciare i fondi, fai clic su Void pre-authorization (cancel order) oppure porta l'ordine allo stato Canceled. Portare l'ordine allo stato Refunded rilascia anche una pre-autorizzazione aperta. Se il rilascio non riesce, una nota ti chiede di rilasciarla nel Merchant Resource Center.

Rimborsi

Nel blocco Moneris payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Moneris. Conferma la domanda Refund this amount through Moneris? This cannot be undone. Sono supportati rimborsi totali e parziali. I rimborsi sono limitati all'importo effettivamente addebitato da Moneris; dopo una differenza di importo puoi quindi rimborsare fino a quanto ha pagato il cliente, non fino al totale dell'ordine. Una pre-autorizzazione può essere rimborsata solo dopo essere stata acquisita; prima, annulla l'ordine per rilasciare i fondi. Il rimborso viene inviato all'ambiente e all'account in cui è avvenuto il pagamento, quindi le credenziali di quella modalità devono essere ancora compilate. Se Moneris non accetta il rimborso, il blocco mostra Refund failed con il motivo e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e alle note con il Trans ID di Moneris. Un rimborso totale porta l'ordine a Refunded; un rimborso parziale non cambia lo stato.

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

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Moneris Gateway è il primo blocco nella pagina Modules > Module Manager > VibeFox Moneris Gateway > 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 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 si trovano la riga Product: presta-payment-moneris 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 cambiare 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, ad 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Moneris non viene mostrato ai clienti nel checkout. Se comunque viene avviato un pagamento, 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 è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo nel checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: acquisizioni, annullamenti e rimborsi dei pagamenti precedenti funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente mentre lavori nel back office: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. La disinstallazione o il reset del modulo rimuovono sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Moneris non compare nel checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che la modalità corrente abbia uno Store ID e un API Token. In modalità live, i campi live devono contenere le tue credenziali di produzione, non quelle di test Moneris. Verifica che la valuta del carrello sia quella dell'account: CAD per il Canada, USD per un account USA. In Payment > Preferences verifica che il modulo sia consentito per quella valuta, per il paese del cliente e per il gruppo del cliente.

Il pagamento è andato a buon fine, ma l'ordine è in Moneris payment on hold: il modulo non ha webhook; il risultato arriva solo dalla risposta di Moneris. Leggi le Moneris notes nel blocco. Se Moneris non ha confermato il risultato, significa che Moneris non ha risposto e anche lo Status Check è fallito. Cerca l'ID dell'ordine Moneris nel Merchant Resource Center: se la transazione è lì, spedisci l'ordine (e rimborsalo lì se necessario); se non c'è, annulla l'ordine o chiedi al cliente di pagare di nuovo. Se l'importo era diverso, controlla l'ordine ed evadilo o rimborsa il pagamento.

Il cliente vede Payment gateway is misconfigured. Please contact the store administrator.: mancano le credenziali della modalità corrente, oppure la modalità live è attiva con credenziali di test Moneris nei campi live. Inserisci il tuo Store ID e API Token di produzione.

Il cliente vede This payment method does not support the order currency.: la valuta del carrello non è quella dell'account Moneris.

Il cliente vede un errore durante il pagamento: controlla il campo Log nella pagina del modulo. Gli errori vengono sempre scritti; attiva Debug log per vedere le richieste e le risposte complete.

L'acquisizione non riesce: l'ordine non ha una pre-autorizzazione in attesa di acquisizione, il totale dell'ordine è zero, oppure l'importo è superiore a quello autorizzato. Anche le pre-autorizzazioni Moneris scadono dopo alcuni giorni.

Rimborso, acquisizione o annullamento non riesce con un messaggio su modalità o account: il pagamento è stato fatto in modalità test o live e le credenziali di quella modalità non sono impostate, oppure il pagamento è stato fatto con un account Moneris dell'altro paese. Inserisci le credenziali, oppure elabora il pagamento nel Merchant Resource Center.

Attacchi di card testing: i moduli carta diretti sono un bersaglio per il card testing. Usa le regole eFraud o di velocity del tuo account Moneris e un modulo CAPTCHA o di limitazione delle richieste per il tuo negozio.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Moneris Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, vengono rimosse le impostazioni del gateway e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le transazioni e i rimborsi Moneris e gli stati dell'ordine Moneris payment authorized e Moneris payment on hold restano sempre, quindi gli ordini pagati in precedenza possono essere ancora acquisiti o rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID di transazione.

Moneris è un marchio del rispettivo titolare. Questo modulo non è affiliato a Moneris né approvato da Moneris.