VibeFox eWAY for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP precedenti.

Valuta del negozio: AUD, NZD, SGD, HKD o MYR. Per le altre valute del carrello il metodo di pagamento non viene mostrato al checkout. Il pagamento viene addebitato nella valuta del carrello.

Account eWAY: ti serve un account commerciante eWAY con accesso all'API Rapid e la relativa chiave e password Rapid API, che trovi in MyeWAY alla voce Settings, API Key. Per i test ti serve un account sandbox eWAY con una propria chiave e password. Le chiavi sandbox e live sono diverse. Non è necessario configurare nulla 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. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure trova più tardi VibeFox eWAY Payment Gateway nell'elenco dei moduli e clicca 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 la chiave e la password API sandbox, lascia attivo Sandbox Mode, attiva Enable/Disable, clicca su Save ed effettua un ordine di prova.

5. Inserisci la chiave e la password API live, disattiva Sandbox Mode e clicca su Save.

6. Facoltativamente, aggiungi l'URL cron mostrato nella pagina Configure alle cron job del tuo server (vedi Configurazione).

All'installazione il modulo crea lo stato ordine eWAY payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi un badge indica la modalità: SANDBOX — payments go to the eWAY sandbox, no real money is charged. oppure LIVE — real payments are taken with the live API key. La pagina ti avvisa quando mancano la chiave e la password API della modalità attuale (in tal caso il metodo di pagamento non viene mostrato al checkout) e quando la valuta predefinita del negozio non è supportata da eWAY.

eWAY

Enable/Disable: Enable eWAY Payment Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Credit Card (eWAY). Obbligatorio.

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 Rapid API si trovano in MyeWAY alla voce Settings, API Key. eWAY offre guide per le chiavi live e sandbox, collegate in questa sezione. Sandbox e live usano chiavi diverse.

Sandbox Mode: i pagamenti vanno alla sandbox di eWAY con la chiave e la password sandbox. Non viene addebitato denaro reale. Predefinito: attivo. Disattivalo per accettare pagamenti reali con la chiave live. Finché è attivo, i clienti vedono Test mode: no real payment is taken. sotto il metodo di pagamento.

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

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

Sandbox API Key: la chiave Rapid API del tuo account sandbox eWAY (account partner/sviluppatore).

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

Le chiavi e le password salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved credentials: spunta una chiave o una password e clicca su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Return URL / re-checks: in eWAY non va configurato alcun webhook né alcun URL di ritorno, perché l'URL di ritorno viene inviato con ogni pagamento. Questo campo mostra un URL cron facoltativo. Richiamalo da una cron job del server, ad esempio ogni 15 minuti. Se un cliente paga e chiude il browser prima di tornare al negozio, il pagamento viene verificato con eWAY circa un'ora dopo e l'ordine viene creato. Se eWAY non è raggiungibile, la verifica viene ripetuta fino a tre volte. Tieni segreto questo URL: contiene un token, e una chiamata con un token errato riceve la risposta Forbidden.

Ordini

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

Un importo o una valuta approvati che non corrispondono all'ordine vanno sempre su eWAY payment on hold.

Avanzate

Debug log: scrive le chiamate API e i risultati dei pagamenti in logs/eway_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Dati della carta, chiavi, password, e-mail dei clienti e codici di accesso non vengono registrati. Gli errori vengono sempre registrati. Predefinito: disattivato.

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

Delete all plugin data on uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il registro. I dati di pagamento eWAY degli ordini e lo stato eWAY payment on hold restano sempre. Predefinito: disattivato.

Checkout

Al passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit Card (eWAY)) e conferma. Il modulo chiede a eWAY una pagina di pagamento per l'importo totale del carrello nella valuta del carrello, con PS- e il numero del carrello come riferimento fattura, insieme all'indirizzo di fatturazione e all'e-mail del cliente, e invia il cliente alla eWAY Responsive Shared Page. Lì il cliente paga con carta. L'addebito è immediato. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna al tuo negozio. Il modulo non si fida del browser: chiede a eWAY, da server a server, il risultato della pagina di pagamento creata per questo carrello. L'ordine viene segnato come pagato solo dopo che eWAY lo conferma e l'importo e la valuta approvati corrispondono al carrello. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your payment with eWAY has been received. Per un ordine in attesa, la pagina mostra Your payment was received and is being reviewed by the store. We will contact you if anything is needed.

Se in quel momento non è possibile interrogare eWAY, una pagina Payment confirmation 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. con un pulsante Check again e un pulsante Back to checkout. L'ordine viene creato quando il cliente ricontrolla o quando viene eseguito l'URL cron.

Se il pagamento viene rifiutato, il cliente torna al checkout con il motivo, ad esempio Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. Se il cliente clicca su Cancel nella pagina eWAY, il modulo verifica prima con eWAY che non sia stato pagato nulla (ad esempio in un'altra scheda). Il cliente vede poi 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. Il carrello viene conservato in ogni caso.

Il cliente può riprovare. Prima di creare una nuova pagina di pagamento, la pagina precedente del carrello viene verificata con eWAY. Se risulta già pagata, viene creato l'ordine invece di un secondo pagamento. Se eWAY non riesce a creare la pagina di pagamento, il cliente resta al checkout con un breve messaggio, ad esempio Payment error: Unable to connect to eWAY. Please try again. oppure eWAY could not start the payment con i codici di errore di eWAY.

eWAY non invia notifiche da server a server per la Shared Page: il risultato viene rilevato al ritorno del cliente e tramite l'URL cron. Il modulo non prevede campi carta sul tuo sito, carte salvate o abbonamenti, nessuna autorizzazione senza cattura né cattura separata, e non valuta i punteggi antifrode Beagle (le transazioni bloccate dalle regole antifrode di eWAY vengono rifiutate da eWAY stesso).

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a eWAY e non ha pagato, ha annullato, il pagamento è stato rifiutato oppure il risultato non è ancora stato recuperato. Esiste solo il carrello.

Payment accepted or Delivered: il pagamento è stato approvato. Lo stato segue Order Status on Success. Il pagamento viene registrato con l'ID transazione di eWAY e una nota mostra l'ID transazione, il codice di autorizzazione, la risposta e la modalità (sandbox o live).

eWAY payment on hold: eWAY ha approvato un importo o una valuta diversi da quelli del carrello (ad esempio Approved for partial amount, oppure il carrello è stato modificato dopo che il cliente ha aperto la pagina di pagamento), il pagamento è stato approvato dopo che il cliente lo aveva annullato nella pagina eWAY, oppure è stato approvato dopo l'annullamento dell'ordine. Il pagamento viene registrato con l'importo incassato da eWAY e la nota lo spiega. Controlla l'ordine e gestiscilo oppure rimborsa il pagamento.

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

Se per un carrello già pagato viene approvato un secondo pagamento, l'ordine non cambia. Una nota ti chiede di rimborsare il duplicato in MyeWAY. Un pagamento approvato per un altro riferimento fattura non viene mai applicato all'ordine.

Blocco pagamento eWAY

La pagina dell'ordine mostra un blocco eWAY payment con ID transazione, codice di autorizzazione, risposta eWAY, stato, modalità e riferimento fattura, importo pagato e rimborsato, un badge Sandbox per i pagamenti sandbox, la cronologia dei rimborsi e le eWAY notes dell'ordine.

Rimborsi

Nel blocco eWAY payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via eWAY. Conferma la domanda Refund this amount through eWAY? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non è necessario l'accesso alle pagine Moduli. I rimborsi vengono eseguiti nell'importo e nella valuta incassati da eWAY, quindi dopo un'approvazione per un importo parziale puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non il totale dell'ordine. Il rimborso viene inviato nell'ambiente in cui è stato effettuato il pagamento (sandbox o live), quindi devono essere impostate la chiave e la password API di quell'ambiente. Se eWAY rifiuta il rimborso, il blocco mostra eWAY refund failed: con i codici di eWAY e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e alle note con l'ID transazione del rimborso eWAY. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non modifica lo stato. I rimborsi sono disponibili dopo che eWAY ha approvato il pagamento.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite eWAY. I rimborsi effettuati in MyeWAY non vengono sincronizzati con PrestaShop. Aggiorna l'ordine manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox eWAY Payment Gateway è il primo blocco di Modules > Module Manager > VibeFox eWAY Payment 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-eway 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, per 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. 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 Questo metodo di pagamento non è disponibile. Scegline un altro. Lo storefront di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento viene nascosto anche a 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 continuano a essere confermati e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma gli aggiornamenti e l'assistenza richiedono il 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 alcuna cron job. La disinstallazione o il ripristino del modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

eWAY does not appear at checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la chiave e la password API della modalità attuale siano impostate (campi sandbox in modalità sandbox, campi live in modalità live) e che la valuta del carrello sia AUD, NZD, SGD, HKD o MYR. La pagina delle impostazioni mostra un avviso quando mancano le credenziali. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

The payment went through, but no order was created: il cliente non è tornato da eWAY, oppure in quel momento non è stato possibile interrogare eWAY. eWAY non invia notifiche per la Shared Page. Configura l'URL cron da Return URL / re-checks: recupererà il pagamento circa un'ora dopo. Controlla la transazione in MyeWAY e consulta il campo Log nella pagina del modulo.

The customer sees This payment method is temporarily unavailable: la chiave o la password API della modalità attuale mancano, oppure eWAY le ha rifiutate. Controlla le credenziali della modalità attuale.

The customer sees eWAY could not start the payment: eWAY ha restituito codici di errore, mostrati nel messaggio. Spesso i dati di fatturazione non sono validi.

The customer sees We could not match this payment to an order: il link di ritorno non appartiene a un carrello di questo negozio, oppure eWAY ha approvato un pagamento per un altro riferimento fattura. Se il cliente è stato addebitato, cerca il pagamento in MyeWAY.

The customer sees We could not check the status of your previous payment attempt: un'altra richiesta stava elaborando lo stesso carrello. Il cliente può riprovare tra un momento.

Order is eWAY payment on hold after payment: leggi le eWAY notes nel blocco eWAY payment (vedi Stati dell'ordine), poi gestisci l'ordine oppure rimborsa il pagamento.

Refund fails with a message about the sandbox or live mode: l'ordine è stato pagato in quell'ambiente e la sua chiave e password API non sono impostate. Inseriscile e riprova.

Refund fails with at most … can be refunded: l'importo è maggiore di quanto eWAY ha incassato meno i rimborsi già effettuati.

Per gli sviluppatori: il README del modulo elenca l'hook actionWcpEwaySupportedCurrencies, se il tuo account eWAY è abilitato per altre valute.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox eWAY Payment Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete all plugin data on uninstall è attivo, vengono rimosse le impostazioni del gateway e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. I dati di pagamento eWAY degli ordini e lo stato eWAY payment on hold restano sempre, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID transazione.

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