VibeFox Authorize.Net for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo. Senza WooCommerce il plugin mostra un avviso nell'area di amministrazione e il metodo di pagamento non viene caricato.
PHP: 8.0 o successivo.
HTTPS: il checkout deve usare HTTPS. Accept.js non funziona su HTTP semplice.
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 quelli 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 negozio deve essere USD, CAD, CHF, DKK, EUR, GBP, NOK, PLN, SEK, AUD o NZD, e il tuo account Authorize.Net deve regolare i pagamenti in quella valuta. Per le altre valute il metodo di pagamento viene nascosto al checkout.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo dominio.
Installazione
1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella wcp_authorizenet_gateway in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Authorize.Net > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Inserisci le credenziali degli account sandbox e di produzione (vedi Configurazione). Facoltativamente, configura il webhook.
6. Attiva Enable/Disable, scegli il Transaction type e salva. Prova un pagamento in modalità sandbox con la carta 4111 1111 1111 1111, una data di scadenza futura e un CVV qualsiasi, poi deseleziona Sandbox mode.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Authorize.Net. Sopra i campi la pagina ti avvisa quando il sito non usa HTTPS (Accept.js funziona solo su pagine HTTPS) e quando la valuta del negozio non è supportata (in quel caso il metodo di pagamento viene nascosto al checkout). La pagina mostra solo i campi delle credenziali della modalità selezionata.
Generali
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. Predefinito: Credit Card.
Description: il testo mostrato sopra il modulo carta 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.
Sandbox mode: Use the Authorize.Net sandbox (test transactions, no real charges). Cambia l'endpoint API, Accept.js e l'insieme di credenziali indicato sotto. Predefinito: attivato. Deselezionalo per accettare pagamenti reali.
Live API Login ID e Sandbox API Login ID: l'API Login ID dell'account di produzione o sandbox.
Live Transaction Key e Sandbox Transaction Key: la Transaction Key di quell'account.
Live Public Client Key e Sandbox Public Client Key: la chiave pubblica usata da Accept.js nel browser.
Live Signature Key e Sandbox Signature Key: necessarie solo per i webhook. Verificano l'intestazione X-ANET-Signature di ogni notifica.
Pagamento
Transaction type: come viene addebitata la carta. Un'autorizzazione scade dopo 30 giorni.
Webhook (consigliati)
Senza webhook, gli ordini trattenuti dalla Fraud Detection Suite o acquisiti o annullati nel pannello di Authorize.Net vanno aggiornati a mano. Nel Merchant Interface vai su Account > Settings > Business Settings > Webhooks e fai clic su Add Endpoint. Usa l'URL mostrato in questa sezione delle impostazioni. Ha una forma come https://your-site/wc-api/wc_authorizenet/. Seleziona questi eventi:
Inserisci la Signature Key dell'account in Live Signature Key o Sandbox Signature Key. I webhook senza una firma valida vengono rifiutati. Per ogni notifica il plugin chiede anche 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: Log API requests and responses scrive in WooCommerce > Status > Logs, origine wcp_authorizenet_gateway. Chiavi, token di carta e dati personali vengono mascherati. Predefinito: disattivato.
Delete data on uninstall: Remove the settings and the Authorize.Net order meta when the plugin is deleted. Predefinito: disattivato.
Checkout
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) nella pagina di checkout. In modalità sandbox il modulo mostra un suggerimento con la carta di prova 4111 1111 1111 1111. Quando l'ordine viene effettuato, Accept.js scambia i dati della carta con un token monouso nel browser. I campi carta non hanno nomi di campo, quindi numero della carta e CVV non vengono mai inviati al tuo server.
Il plugin addebita il token tramite l'API di Authorize.Net per il totale dell'ordine nella valuta dell'ordine. Indirizzo di fatturazione, e-mail e indirizzo IP vengono inviati con la transazione per la verifica dell'indirizzo e i filtri antifrode. Se il pagamento viene approvato, il cliente va alla pagina Ordine ricevuto e il carrello viene svuotato.
Se la carta viene rifiutata, il cliente resta sul checkout e vede Payment failed: seguito dal motivo, per esempio carta rifiutata, codice di sicurezza errato o carta scaduta. Gli errori di configurazione e dell'API non vengono mostrati ai clienti: vedono un messaggio generico, mentre i dettagli vanno nella nota dell'ordine e 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.
Invii ripetuti e pagamenti ripetuti dello stesso ordine non lo addebitano mai una seconda volta. Il metodo di pagamento funziona con il checkout classico, con il blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin non gestisce carte salvate o profili cliente, WooCommerce Subscriptions o Pre-Orders, eCheck/ACH, Apple Pay, Google Pay, PayPal o 3-D Secure, né acquisizioni parziali di un'autorizzazione o conversioni automatiche di valuta.
Ordini e rimborsi
Stati dell'ordine
Processing or Completed: la carta è stata addebitata (Authorize and capture), oppure un'autorizzazione è stata acquisita. WooCommerce imposta Processing, oppure Completed per gli ordini con solo prodotti virtuali scaricabili. La nota dell'ordine mostra importo, ID transazione, codice di autorizzazione, tipo di carta e le ultime quattro cifre. L'ID transazione è il Trans ID di Authorize.Net.
On hold: i fondi sono solo autorizzati (Authorize only), oppure la Fraud Detection Suite ha trattenuto la transazione per verifica. Approva o rifiuta una transazione trattenuta nel pannello di Authorize.Net; con i webhook l'ordine si aggiorna automaticamente. Un ordine viene messo in sospeso anche quando un'acquisizione segnalata dal webhook non corrisponde all'importo dell'ordine.
Cancelled: un webhook ha segnalato che la transazione è stata rifiutata, annullata o è scaduta prima che l'ordine fosse pagato. Se questo accade a un ordine pagato, il suo stato non cambia e viene aggiunta una nota di avviso.
Acquisizione
Per un ordine con un'autorizzazione, apri l'ordine, scegli Capture payment (Authorize.Net) tra le azioni dell'ordine e fai clic sul pulsante Aggiorna. Viene acquisito l'intero importo dell'ordine meno i rimborsi, e l'ordine viene segnato come pagato. Se l'acquisizione non riesce, l'errore viene mostrato e aggiunto alle note dell'ordine. Puoi anche acquisire nel pannello di Authorize.Net; con i webhook l'ordine si aggiorna automaticamente.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Credit Card (il pulsante usa il titolo del tuo metodo di pagamento). Un rimborso dell'intero importo dell'ordine 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'intero importo per annullare la transazione, oppure riprova dopo la regolazione. Se Authorize.Net non accetta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso o un annullamento riuscito viene aggiunto alle note dell'ordine.
I rimborsi, le acquisizioni e le verifiche webhook di un ordine usano le credenziali della modalità in cui l'ordine è stato pagato, quindi gli ordini dell'altra modalità possono essere ancora acquisiti e rimborsati dopo aver cambiato Sandbox mode. Mantieni le credenziali di quella modalità nei rispettivi campi finché questi ordini non sono conclusi.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Authorize.Net. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva e il tuo dominio. Usa Check now per verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.
Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera il posto del dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, il metodo di pagamento 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. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i webhook continuano a essere elaborati e acquisizioni e rimborsi funzionano.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente in background.
Risoluzione dei problemi
Authorize.Net non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia API Login ID, Transaction Key e Public Client Key. Verifica che la valuta del negozio sia supportata; la pagina delle impostazioni mostra un avviso quando non lo è.
Il pagamento è andato a buon fine, ma l'ordine resta On hold: il tipo di transazione è Authorize only (acquisiscilo con l'azione d'ordine), oppure Authorize.Net ha trattenuto la transazione per verifica. Approvala o rifiutala nel pannello di Authorize.Net. Per aggiornare automaticamente questi ordini, configura il webhook: verifica che l'URL dell'endpoint sia esattamente quello mostrato nelle impostazioni, che i quattro eventi siano selezionati e che sia inserita la Signature Key della modalità corrente.
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 o a un'altra modalità. Crea di nuovo o copia la Signature Key e incollala nel campo della sua modalità.
Webhook answers verification failed, retry later: il negozio non è riuscito a leggere la transazione dall'API di Authorize.Net. Authorize.Net ripete la consegna.
Il modulo carta non si carica o 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à corrente devono essere corretti.
Payment error: the card could not be tokenized: Accept.js non ha restituito un token. Il cliente deve inserire di nuovo i dati della carta e riprovare.
Il cliente vede un errore generico: apri le note dell'ordine oppure attiva il Debug log e controlla WooCommerce > Status > Logs, origine wcp_authorizenet_gateway. Una valuta che l'account non supporta viene rifiutata da Authorize.Net.
Un rimborso parziale non riesce perché la transazione non è ancora regolata: rimborsa l'intero importo dell'ordine per annullare la transazione, oppure riprova dopo la regolazione, di solito entro 24 ore.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.
Disinstallazione
Disattivare il plugin mantiene tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, i dati Authorize.Net salvati negli ordini e i registri vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.
Authorize.Net è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da Authorize.Net.