VibeFox eWAY for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo.

PHP: 8.0 o successivo.

Valuta del negozio: AUD, NZD, SGD, HKD o MYR. Per le altre valute il metodo di pagamento viene nascosto al checkout. L'ordine viene addebitato nella sua valuta.

Account eWAY: ti serve un account commerciante eWAY con accesso all'API Rapid e la relativa chiave e password dell'API Rapid, da MyeWAY in Settings, API Key. Per i test ti serve un account sandbox eWAY con la sua chiave e password. Le chiavi sandbox e live sono diverse. Non c'è nulla da configurare in eWAY: l'URL di ritorno viene inviato con ogni pagamento.

Chiave di licenza VibeFox: si acquista 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_eway_payment_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > eWAY > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Inserisci la chiave e la password API sandbox, lascia attivo Sandbox Mode, attiva Enable/Disable ed effettua un ordine di prova con la carta di test eWAY 4444333322221111.

6. Inserisci la chiave e la password API live, deseleziona Sandbox Mode e salva.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > eWAY. Sopra i campi un badge indica la modalità: SANDBOX (i pagamenti vanno alla sandbox di eWAY e non viene addebitato denaro reale) oppure LIVE (i pagamenti reali vengono elaborati con la chiave API live). La pagina ti avvisa quando mancano chiave e password API della modalità corrente (in tal caso il gateway non viene mostrato al checkout) e quando la valuta del negozio non è supportata. Nell'elenco dei metodi di pagamento, eWAY risulta da configurare finché la modalità corrente non ha le credenziali, e in modalità sandbox mostra un badge di modalità test.

Generali

Enable/Disable: Enable eWAY Payment Gateway 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 (eWAY).

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

Credenziali API

La chiave e la password dell'API Rapid si trovano in MyeWAY, in Settings, API Key. eWAY offre guide per le chiavi live e sandbox, collegate in questa sezione. Sandbox e live usano chiavi diverse.

Sandbox Mode: Enable sandbox (test) mode invia i pagamenti alla sandbox di eWAY con la chiave sandbox. Non viene addebitato denaro reale. Predefinito: attivo. Deselezionala per incassare pagamenti reali con la chiave live.

Live API Key: la chiave dell'API Rapid del tuo account eWAY live.

Live API Password: la password dell'API Rapid del tuo account eWAY live.

Sandbox API Key: la chiave dell'API Rapid del tuo account sandbox (partner/developer) di eWAY.

Sandbox API Password: la password dell'API Rapid del tuo account sandbox di eWAY.

Ordini

Order Status on Success: lo stato dell'ordine una volta che eWAY conferma il pagamento.

Avanzate

Debug log: Enable logging scrive le chiamate API e i risultati dei pagamenti in WooCommerce > Status > Logs, origine wcp_eway_payment_gateway. Dati della carta e chiavi non vengono registrati. Gli errori vengono sempre registrati. Predefinito: disattivato.

Uninstall: Delete all plugin data on uninstall. Se selezionata, le impostazioni del gateway e i relativi log vengono eliminati quando il plugin viene cancellato. I riferimenti di pagamento salvati negli ordini vengono conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit Card (eWAY)) e conferma l'ordine. Il plugin chiede a eWAY una pagina di pagamento per l'importo totale dell'ordine nella valuta dell'ordine, con l'ID ordine come riferimento fattura e i dati di fatturazione del cliente, e invia il cliente alla Responsive Shared Page di eWAY. Lì il cliente paga con carta. Il pagamento viene addebitato immediatamente.

Dopo il pagamento, il cliente torna al tuo negozio. Il plugin non si fida del browser: chiede a eWAY, da server a server, il risultato della pagina di pagamento creata per questo ordine. L'ordine viene segnato come pagato solo dopo la conferma di eWAY e se importo e valuta approvati corrispondono all'ordine. Poi il cliente arriva alla pagina «Ordine ricevuto». Se in quel momento non è stato possibile interrogare eWAY, l'ordine resta «In attesa di pagamento» e la pagina mostra We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again. Il pagamento viene verificato di nuovo all'apertura della pagina «Ordine ricevuto» e prima che WooCommerce annulli automaticamente l'ordine non pagato.

Se il pagamento viene rifiutato, il cliente torna al checkout (o alla pagina Pay for order) con il motivo, ad esempio Your payment was declined: Insufficient funds. Please try again or use a different payment method. Se il cliente fa clic su Cancel nella pagina eWAY, il plugin verifica prima con eWAY che non sia stato pagato nulla. Un ordine effettuato al checkout viene poi annullato, mentre un ordine pagato dalla pagina Pay for order resta non pagato. Il cliente vede You cancelled the payment on the eWAY page. Your order has not been paid — you can try again. Se il pagamento non è stato completato, il messaggio è The payment was not completed. Please try again.

Un cliente può pagare di nuovo un ordine non pagato. Ogni pagina di pagamento dell'ordine viene tracciata, quindi anche il pagamento effettuato tramite una pagina precedente viene riconosciuto. Se eWAY non riesce a creare la pagina di pagamento, il cliente vede un breve messaggio, ad esempio Payment error: Unable to connect to eWAY. Please try again.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con l'archiviazione degli ordini ad alte prestazioni di WooCommerce (HPOS).

eWAY non invia notifiche da server a server per la Shared Page: il risultato viene rilevato al ritorno del cliente e nei controlli descritti sopra. Il plugin non prevede campi carta sul tuo sito, carte salvate o abbonamenti, né autorizzazione e cattura separate, e non valuta i punteggi antifrode di Beagle (le transazioni bloccate dalle regole antifrode di eWAY vengono rifiutate da eWAY stesso).

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a eWAY e non ha ancora pagato, oppure il risultato non è ancora stato recuperato da eWAY (lo indica la nota dell'ordine).

Processing or Completed: il pagamento è stato approvato. Lo stato segue Order Status on Success. La nota dell'ordine mostra l'ID transazione eWAY, il codice di autorizzazione e la risposta. L'ID transazione dell'ordine è l'ID transazione eWAY.

On hold after payment: eWAY ha approvato un importo o una valuta diversi da quelli dell'ordine (ad esempio Approved for partial amount, oppure l'ordine è stato modificato dopo che il cliente ha aperto la pagina di pagamento), oppure il pagamento è stato approvato dopo l'annullamento dell'ordine. La nota lo spiega. Nella pagina «Ordine ricevuto» il cliente vede Your payment was received and is being reviewed by the store. We will contact you if anything is needed. Completa l'ordine o rimborsa il pagamento.

Failed: eWAY ha rifiutato il pagamento. La nota mostra il codice eWAY e il suo significato.

Cancelled: il cliente ha annullato nella pagina eWAY dopo aver effettuato l'ordine al checkout, oppure l'ordine è stato annullato da te o dal timeout di mantenimento delle scorte di WooCommerce, dopo che eWAY ha confermato che non era pagato.

Se per un ordine già pagato viene approvato un secondo pagamento, l'ordine non cambia. Una nota ti chiede di rimborsare il duplicato in MyeWAY.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Credit Card (eWAY) (il pulsante usa il titolo del metodo di pagamento). Sono supportati rimborsi totali e parziali. Il rimborso viene inviato nell'ambiente in cui è stato effettuato il pagamento (sandbox o live), quindi chiave e password API di quell'ambiente devono essere impostate. Se eWAY rifiuta il rimborso, WooCommerce mostra il codice eWAY e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID transazione del rimborso eWAY.

I rimborsi effettuati in MyeWAY non vengono sincronizzati con WooCommerce. Se necessario, crea un rimborso manuale in WooCommerce senza usare il pulsante di rimborso eWAY.

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 > eWAY. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad 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 suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, eWAY 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 con accesso effettuato vedono ancora il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

eWAY does not appear at checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che chiave e password API della modalità corrente siano impostate (campi sandbox in modalità sandbox, campi live in modalità live) e che la valuta del negozio sia AUD, NZD, SGD, HKD o MYR. Nella pagina Pay for order viene verificata la valuta dell'ordine.

The payment went through, but the order stays Pending payment: il cliente non è tornato da eWAY, oppure in quel momento non è stato possibile interrogare eWAY. eWAY non invia notifiche per la Shared Page. Il pagamento viene verificato di nuovo all'apertura della pagina «Ordine ricevuto» e prima che WooCommerce annulli l'ordine non pagato. Controlla la transazione in MyeWAY e guarda in WooCommerce > Status > Logs, origine wcp_eway_payment_gateway.

Il cliente vede il messaggio This payment method is temporarily unavailable: chiave o password API della modalità corrente mancanti, oppure eWAY le ha rifiutate. Controlla le credenziali della modalità corrente.

Il cliente vede il messaggio eWAY could not start the payment: eWAY ha restituito codici di errore, mostrati nel messaggio. Spesso i dati di fatturazione non sono validi.

Il cliente vede il messaggio We could not match this payment to an order: il link di ritorno non appartiene ad alcun ordine di questo negozio. Se il cliente è stato addebitato, cerca il pagamento in MyeWAY.

Il cliente vede il messaggio We could not confirm your payment with eWAY: non è stato possibile verificare il risultato del pagamento. L'ordine viene aggiornato quando il risultato viene recuperato; il cliente non deve pagare di nuovo.

Order is On hold after payment: leggi la nota dell'ordine. L'importo o la valuta approvati erano diversi da quelli dell'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Completa l'ordine o rimborsa il pagamento.

Il rimborso non riesce con un messaggio sulla modalità sandbox o live: l'ordine è stato pagato in quell'ambiente, e chiave e password API di quell'ambiente non sono impostate. Inseriscile e riprova.

Il blocco licenza mostra un errore: segui il messaggio del blocco. Ad esempio, se la chiave è già usata su un altro dominio, libera uno slot 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.

Per gli sviluppatori, il readme elenca il filtro eway_p_supported_currencies, se il tuo account eWAY è abilitato a più valute.

Disinstallazione

Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i log vengono rimossi solo se l'opzione Uninstall (Delete all plugin data on uninstall) era attiva. Altrimenti restano per una futura reinstallazione. I riferimenti di pagamento salvati negli ordini vengono sempre conservati. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID transazione.

eWAY è un marchio del rispettivo proprietario. Questo plugin non è affiliato a eWAY né approvato da eWAY.