VibeFox Authorize.Net 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.

HTTPS: il checkout deve usare HTTPS. Accept.js non viene eseguito su pagine HTTP semplici.

Account Authorize.Net: ti servono API Login ID, Transaction Key e Public Client Key del tuo account Authorize.Net, e una Signature Key se usi i webhook. Gli account di produzione (account.authorize.net) e sandbox (sandbox.authorize.net) hanno credenziali diverse. Gli account Authorize.Net sono disponibili per i commercianti di Stati Uniti, Canada, Regno Unito, Europa, Australia e Nuova Zelanda.

Valuta: la valuta del carrello deve essere USD, CAD, CHF, DKK, EUR, GBP, NOK, PLN, SEK, AUD o NZD, e il tuo account Authorize.Net deve regolare in quella valuta. Per le altre valute il metodo di pagamento viene nascosto al checkout.

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 cerca più tardi VibeFox Authorize.Net Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci 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 le credenziali degli account sandbox e di produzione (vedi Configurazione). Facoltativamente, configura il webhook.

5. Attiva Enable/Disable, scegli il Transaction type e fai clic su Save. Prova un pagamento in modalità sandbox con la carta 4111 1111 1111 1111, una data di scadenza futura qualsiasi e un CVV qualsiasi, poi disattiva Sandbox mode.

All'installazione il modulo crea due stati dell'ordine: Authorize.Net payment authorized e Authorize.Net payment on hold. PrestaShop attiva il nuovo modulo di pagamento per tutte le valute, tutti i paesi e tutti i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Authorize.Net Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa se SSL non è attivo per il negozio (Accept.js funziona solo su pagine HTTPS), se la valuta predefinita del negozio non è supportata da Authorize.Net, se la modalità attuale non ha API Login ID, Transaction Key o Public Client Key (in tal caso il metodo di pagamento viene nascosto al checkout) e se la modalità attuale non ha una Signature Key (in tal caso i webhook sono disattivati). Mentre la modalità sandbox è attiva, mostra Sandbox mode is on: test transactions, no real charges.

Authorize.Net

Enable/Disable: Enable Authorize.Net 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: Credit Card. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with your credit card via Authorize.Net.

Credenziali API

Nel Merchant Interface di Authorize.Net apri Account > Settings > Security Settings. In API Credentials & Keys copia l'API Login ID e crea una Transaction Key e una Signature Key. In Manage Public Client Key copia la Public Client Key. Sandbox e produzione usano credenziali diverse. La pagina mostra i campi di entrambe le modalità, quindi puoi conservare entrambi i set.

Sandbox mode: usa la sandbox di Authorize.Net (transazioni di prova, nessun addebito reale). Cambia l'endpoint API, Accept.js e l'insieme di credenziali usato per i nuovi pagamenti. Predefinito: attivo. Disattivalo per accettare pagamenti reali. Finché è attivo, i clienti vedono un suggerimento con la carta di prova 4111 1111 1111 1111 sotto il metodo di pagamento.

Sandbox API Login ID e Live API Login ID: l'API Login ID dell'account sandbox o di produzione.

Sandbox Transaction Key e Live Transaction Key: la Transaction Key di quell'account.

Sandbox Public Client Key e Live Public Client Key: la chiave pubblica che Accept.js usa nel browser.

Sandbox Signature Key e Live Signature Key: necessarie solo per i webhook. Verifica l'header X-ANET-Signature di ogni notifica.

Le Transaction Key e le Signature Key salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un valore nuovo solo per cambiarlo.

Clear saved secrets: spunta una chiave e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Pagamento

Transaction type: come viene addebitata la carta. Un'autorizzazione scade dopo 30 giorni.

Webhook (consigliati)

Senza webhook, gli ordini trattenuti da Fraud Detection Suite, oppure acquisiti o annullati nel pannello di Authorize.Net, devono essere aggiornati a mano. Nel Merchant Interface vai su Account > Settings > Business Settings > Webhooks e fai clic su Add Endpoint, sia nell'account sandbox sia in quello di produzione. Usa l'URL mostrato in Endpoint URL in questa sezione. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_authorizenet_gateway/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni. Seleziona questi eventi (sono elencati anche in questa sezione):

Inserisci la Signature Key di ciascun account in Sandbox Signature Key o Live Signature Key. I webhook senza una firma valida vengono rifiutati. Una notifica deve essere firmata con la chiave della modalità in cui è stato effettuato il pagamento; una notifica dell'altra modalità non cambia nulla. Per ogni notifica il modulo chiede inoltre ad Authorize.Net lo stato e l'importo attuali della transazione prima di modificare l'ordine, quindi le notifiche ripetute non cambiano nulla.

Avanzate

Debug log: scrive richieste e risposte API in logs/wc_ang_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi, token delle carte e dati personali sono mascherati. Predefinito: disattivato. Gli errori, come pagamenti rifiutati o non riusciti, errori API e rimborsi non riusciti, vengono sempre registrati, anche quando questa opzione è disattivata.

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

Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni e il registro. Le transazioni e i rimborsi di Authorize.Net e gli stati dell'ordine del modulo restano sempre, quindi gli ordini pagati in precedenza possono ancora essere acquisiti e rimborsati dopo una reinstallazione. Predefinito: disattivato.

Checkout

Al passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit Card) e inserisce numero della carta, data di scadenza (MM/YY) e codice di sicurezza (CVV) nel modulo sottostante. Accept.js viene caricato solo sulla pagina di checkout. Quando il cliente conferma l'ordine, Accept.js scambia i dati della carta con un token monouso nel browser. I campi della carta non hanno nomi di modulo, quindi il numero della carta e il CVV non vengono mai inviati al tuo server.

Il modulo addebita il token tramite l'API di Authorize.Net per il totale del carrello nella valuta del carrello. Indirizzo di fatturazione, e-mail e indirizzo IP vengono inviati con la transazione per la verifica dell'indirizzo e i filtri antifrode. Il numero del carrello viene inviato come numero di fattura, perché prima del pagamento non esiste ancora alcun ordine. L'ordine viene segnato come pagato solo dopo la conferma di Authorize.Net: se la transazione è approvata, l'ordine viene creato subito e il cliente vede la pagina standard di conferma dell'ordine con Your card payment has been received. Con Authorize only la pagina mostra Your card payment has been authorized. The amount will be charged when your order is processed. Se Fraud Detection Suite trattiene la transazione, la pagina mostra Your payment is being reviewed. We will update your order as soon as the review is complete.

Se la carta viene rifiutata, il cliente resta al passaggio di pagamento e vede Payment failed: seguito dal motivo, ad esempio carta rifiutata, codice di sicurezza errato o carta scaduta. Non viene creato alcun ordine e il carrello viene conservato. Gli errori di configurazione e dell'API non vengono mostrati ai clienti: vedono un messaggio generico, e i dettagli finiscono nel registro. Se il negozio non riesce a raggiungere Authorize.Net, il cliente vede Payment error: unable to connect to the payment gateway. Please try again. Se i campi della carta sono vuoti, il modulo chiede Please enter the card number, expiry date and card code.

Un doppio clic, una seconda scheda o un invio ripetuto non addebitano mai due volte lo stesso carrello. Un secondo tentativo mentre il primo è ancora in corso mostra Your payment is already being processed. Please wait a moment and check your order history before trying again. Se un pagamento è stato approvato ma l'ordine non è stato creato, il cliente vede Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. L'ordine viene poi creato dal pagamento approvato al tentativo successivo o tramite il webhook, senza addebitare di nuovo la carta.

Se il carrello cambia mentre il pagamento è in corso, l'importo addebitato non corrisponde più al carrello. L'ordine passa allora a Authorize.Net payment on hold con una nota, e il pagamento viene registrato per l'importo effettivamente addebitato.

Il webhook funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo non gestisce carte salvate o profili cliente, abbonamenti o pagamenti ricorrenti, eCheck/ACH, Apple Pay, Google Pay, PayPal o 3-D Secure, né acquisizioni parziali di un'autorizzazione o conversione automatica di valuta.

Ordini e rimborsi

Stati dell'ordine

No order: la carta è stata rifiutata o il pagamento non è riuscito. Esiste solo il carrello.

Payment accepted: la carta è stata addebitata (Authorize and capture), oppure un'autorizzazione è stata acquisita. Il pagamento viene registrato con l'Authorize.Net Trans ID come ID transazione, e una nota mostra l'importo, il Trans ID, il codice di autorizzazione, il tipo di carta e le ultime quattro cifre.

Authorize.Net payment authorized: i fondi sono solo autorizzati (Authorize only). Acquisiscili prima dell'evasione.

Authorize.Net payment on hold: Fraud Detection Suite ha trattenuto la transazione per la verifica, l'importo addebitato non corrisponde al totale dell'ordine, oppure un'acquisizione segnalata dal webhook non corrisponde all'importo dell'ordine. La nota lo spiega. Approva o rifiuta una transazione trattenuta nel pannello di Authorize.Net; con i webhook l'ordine viene aggiornato automaticamente.

Canceled: un webhook ha segnalato che la transazione è stata rifiutata, annullata o è scaduta prima che l'ordine fosse pagato, oppure hai annullato un'autorizzazione che non era stata acquisita. Se la transazione di un ordine pagato viene annullata nel pannello di Authorize.Net, il suo stato non cambia e viene aggiunta una nota di avviso.

Refunded: il pagamento è stato rimborsato o annullato per intero tramite il modulo.

Se per un carrello che ha già un ordine viene approvata una seconda transazione, l'ordine non cambia. Una nota ti chiede di verificarla e di annullare o rimborsare il duplicato nel pannello di Authorize.Net.

Blocco pagamento Authorize.Net

La pagina dell'ordine mostra un blocco Authorize.Net payment con il Trans ID, il tipo di transazione, lo stato della transazione, la carta e il codice di autorizzazione, l'importo addebitato, il totale dell'ordine e l'importo rimborsato, un badge Sandbox per i pagamenti sandbox, lo storico dei rimborsi e le Authorize.Net notes dell'ordine. Acquisizione e rimborsi richiedono solo il permesso di modificare gli ordini, non l'accesso alle pagine dei moduli.

Acquisizione

Per un ordine in Authorize.Net payment authorized, fai clic su Capture payment nel blocco e conferma Capture the authorized amount through Authorize.Net? L'importo autorizzato viene acquisito, il pagamento viene registrato con il Trans ID e l'ordine passa a Payment accepted. Se l'acquisizione non riesce, l'errore viene mostrato e aggiunto alle note. Puoi anche acquisire nel pannello di Authorize.Net; con i webhook l'ordine viene aggiornato automaticamente.

Rimborsi

Nel blocco inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, fai clic su Refund via Authorize.Net e conferma Refund this amount through Authorize.Net? This cannot be undone. Un rimborso dell'importo totale annulla prima la transazione se non è ancora regolata, oppure un'autorizzazione non acquisita. Le transazioni regolate, di solito dopo 24 ore, possono essere rimborsate in tutto o in parte. Prima della regolazione non è possibile un rimborso parziale: rimborsa l'importo totale per annullare la transazione, oppure riprova dopo la regolazione. I rimborsi vengono effettuati nell'importo e nella valuta che Authorize.Net ha addebitato, quindi dopo una differenza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Se Authorize.Net non accetta il rimborso, il blocco mostra l'errore e nessun rimborso viene registrato. Un rimborso o un annullamento riuscito viene aggiunto allo storico dei rimborsi e alle note. Un rimborso totale imposta l'ordine su Refunded (Canceled quando è stata annullata solo un'autorizzazione). Un rimborso parziale non cambia lo stato. Finché una transazione è trattenuta per la verifica, i rimborsi non vengono proposti.

Acquisizioni, rimborsi e verifiche dei webhook di un ordine usano le credenziali della modalità in cui l'ordine è stato pagato, quindi gli ordini dell'altra modalità possono ancora essere acquisiti e rimborsati dopo aver cambiato Sandbox mode. Conserva le credenziali di quella modalità nei rispettivi campi finché questi ordini non sono completati.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Authorize.Net. I rimborsi effettuati nel pannello di Authorize.Net non vengono comunicati al negozio: aggiorna l'ordine manualmente.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox Authorize.Net Gateway è il primo blocco di Modules > Module Manager > VibeFox Authorize.Net Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo di che 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 di essi ci sono la riga Product: presta-payment-authorizenet e il collegamento 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, 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 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 multinegozio. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave di licenza attiva, il pagamento con carta Authorize.Net 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. Il negozio non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati, e acquisizioni e rimborsi funzionano.

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

Authorize.Net non compare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità attuale abbia API Login ID, Transaction Key e Public Client Key. La pagina delle impostazioni mostra un avviso se ne manca una. Controlla che la valuta del carrello sia supportata e, in Payment > Preferences, 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 l'ordine resta in Authorize.Net payment on hold o authorized: il tipo di transazione è Authorize only (acquisiscila dal blocco dell'ordine), oppure Authorize.Net ha trattenuto la transazione per la verifica. Approvala o rifiutala nel pannello di Authorize.Net. Per aggiornare automaticamente questi ordini, configura il webhook: controlla che l'endpoint esista nell'account della modalità che usi, che il suo URL sia esattamente quello mostrato in Endpoint URL, che siano selezionati i quattro eventi e che la Signature Key di quell'account sia inserita.

Webhook answers webhooks are not configured: non è inserita alcuna Signature Key per nessuna delle due modalità.

Webhook answers invalid signature: la Signature Key appartiene a un altro account, oppure una chiave è stata modificata in Authorize.Net. Crea o copia di nuovo la Signature Key e incollala nel campo della sua modalità.

Webhook answers mode mismatch: la notifica è stata firmata con la chiave di una modalità, ma il pagamento è stato effettuato nell'altra. Controlla che le Signature Key sandbox e live non siano scambiate.

Webhook answers verification failed, retry later: il negozio non è riuscito a leggere la transazione dall'API di Authorize.Net, oppure mancano le credenziali della modalità del pagamento. Authorize.Net ritenta la consegna.

Webhook answers busy, retry later: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento, oppure l'ordine non è stato possibile crearlo. Authorize.Net ritenta la consegna. Controlla il campo Log per il motivo.

L'URL del webhook mostra method not allowed nel browser: è normale. L'URL accetta solo richieste da Authorize.Net.

Il modulo carta mostra The secure card form (Accept.js) could not be loaded: il checkout deve usare HTTPS, e la Public Client Key e l'API Login ID della modalità attuale devono essere corrette.

Payment error: the card could not be tokenized: Accept.js non ha restituito alcun token. Il cliente deve inserire di nuovo i dati della carta e riprovare.

Il cliente vede un errore generico: controlla il campo Log nella pagina del modulo; gli errori vengono sempre scritti lì. Una valuta non supportata dall'account viene rifiutata da Authorize.Net.

Un rimborso parziale non riesce perché la transazione non è ancora regolata: rimborsa l'importo totale per annullare la transazione, oppure riprova dopo la regolazione, di solito entro 24 ore.

Rimborso o acquisizione non riuscito con un messaggio sulla modalità: il pagamento è stato effettuato in modalità sandbox o di produzione, e API Login ID e Transaction Key di quella modalità non sono impostati. Inseriscili e riprova.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Authorize.Net 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 e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le transazioni e i rimborsi di Authorize.Net e gli stati dell'ordine Authorize.Net payment authorized e Authorize.Net payment on hold restano sempre, quindi gli ordini pagati in precedenza possono ancora essere acquisiti e rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID delle transazioni.

Authorize.Net è un marchio registrato del suo titolare. Questo modulo non è affiliato né approvato da Authorize.Net.