VibeFox ECPay 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.

Valuta: nuovo dollaro taiwanese (TWD). ECPay addebita solo in TWD, quindi il metodo di pagamento viene mostrato solo quando il carrello del cliente è in TWD. Aggiungi TWD in International > Localization > Currencies se il tuo negozio non ce l'ha. Gli importi vengono inviati in TWD interi, perché ECPay non accetta decimali: i totali del carrello vengono arrotondati al dollaro più vicino. Usa 0 decimali per i prezzi in TWD per evitare arrotondamenti.

Account ECPay: per i pagamenti live ti servono MerchantID, HashKey e HashIV del tuo account commerciante ECPay, dal back office commerciante di ECPay (vendor.ecpay.com.tw). Per le prove non serve un account ECPay.

Accesso al sito: il tuo negozio deve essere raggiungibile da internet tramite HTTP/HTTPS sulla porta 80/443, così ECPay può inviare le notifiche di pagamento. Un firewall o l'autenticazione di base davanti al sito le bloccano.

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 ECPay Payment 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. Attiva Enable/Disable, scegli i metodi di pagamento e lascia Test Mode attivo per le prime prove. Fai clic su Save.

5. Per i pagamenti live inserisci Merchant ID, Hash Key e Hash IV (vedi Configurazione), disattiva Test Mode e fai clic su Save.

All'installazione il modulo crea due stati dell'ordine, Awaiting ECPay payment e ECPay 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; TWD deve restare consentita per il modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure. Ogni sezione ha il suo pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra un errore se il tuo negozio non ha la valuta TWD (in tal caso ECPay non compare al checkout) oppure un avviso se la valuta predefinita non è TWD (in tal caso ECPay viene mostrato solo ai clienti che pagano in TWD). Mostra un errore se la modalità live non ha MerchantID, HashKey e HashIV. Finché la modalità di test è attiva, avvisa che i pagamenti vanno al sandbox ECPay con il commerciante di test pubblico 3002607, che non viene incassato denaro e che chiunque conosca le chiavi sandbox pubbliche potrebbe confermare ordini di prova, quindi la modalità di test deve essere disattivata prima di accettare ordini reali.

ECPay (綠界)

Enable/Disable: Enable ECPay Payment attiva o disattiva il metodo di pagamento. Predefinito: disattivo.

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: ECPay (綠界). Obbligatorio: la pagina non si salva con il titolo vuoto.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).

Account ECPay

Trova il tuo MerchantID, HashKey e HashIV nel back office commerciante di ECPay (vendor.ecpay.com.tw), in System development management > System integration settings (系統開發管理 > 系統介接設定).

Test Mode: invia i pagamenti al sandbox ECPay (payment-stage.ecpay.com.tw) con il commerciante di test pubblico ECPay 3002607. Nessun denaro reale. Le credenziali qui sotto vengono usate solo quando la modalità di test è disattivata. Predefinito: attivo. Finché è attiva, i clienti vedono TEST MODE — ECPay sandbox, no real money is charged. sotto il metodo di pagamento.

Merchant ID: il tuo Merchant ID ECPay (produzione). Ignorato in modalità di test.

Hash Key: il tuo Hash Key ECPay (produzione). Ignorato in modalità di test.

Hash IV: il tuo Hash IV ECPay (produzione). Ignorato in modalità di test.

Spazi e interruzioni di riga nelle credenziali incollate rompono ogni firma, quindi vengono rimossi al salvataggio, e la pagina te lo segnala. Un Hash Key e un Hash IV salvati non vengono più mostrati: il campo resta vuoto e riporta Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved secrets: spunta Hash Key o Hash IV e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Opzioni di pagamento

Enabled Payment Methods: i metodi offerti ai clienti. Con più di uno, il cliente sceglie al checkout. Gli ordini ATM, CVS e codice a barre restano in Awaiting ECPay payment finché il cliente non paga. Deve essere selezionato almeno un metodo; se non ne è selezionato nessuno, viene attivato Credit Card e la pagina te lo segnala. Predefinito: Credit Card.

Default Payment Method: il metodo preselezionato. Deve essere uno dei metodi attivati; altrimenti viene usato il primo metodo attivato. Predefinito: Credit Card.

Order Prefix: il prefisso del numero di transazione ECPay (MerchantTradeNo), fino a 5 lettere o cifre. Gli altri caratteri vengono rimossi al salvataggio, con un messaggio. Utile quando più negozi condividono un account ECPay: assegna a ciascuno un prefisso proprio. Predefinito: EC.

Notifiche di pagamento

ECPay invia i risultati dei pagamenti al tuo negozio. Questa sezione mostra la Notification URL. Con gli URL search-friendly ha questo aspetto: https://your-shop/module/wcp_ecpay_payment_gateway/notify, eventualmente con un codice lingua come /en/. L'URL viene inviato con ogni pagamento, quindi in ECPay non c'è nulla da configurare, ma deve essere raggiungibile da internet sulla porta 80/443, senza firewall o autenticazione di base davanti. La modalità manutenzione e la restrizione per paese del tuo negozio non la bloccano.

Ogni notifica viene verificata tramite la firma CheckMacValue con le chiavi dell'ambiente (test o live) in cui è stato avviato il pagamento, e tramite il MerchantID di quel pagamento. Le notifiche senza firma valida vengono rifiutate, e ECPay le invia di nuovo. Senza la notifica non viene creato alcun ordine; verifica il pagamento nel back office di ECPay.

Avanzate

Enable Logging: scrive ID ordine, numeri di transazione, importi e codici di risposta ECPay in logs/ecpay_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Nessuna chiave o dato del cliente viene registrato. Gli errori vengono sempre registrati, anche quando questo interruttore è disattivato. Predefinito: disattivo.

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 sue impostazioni e il registro. I record dei pagamenti ECPay e gli stati dell'ordine vengono sempre conservati, così gli ordini esistenti continuano a funzionare dopo una reinstallazione. Predefinito: disattivo.

Checkout

Al passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita ECPay (綠界)). Con più metodi attivati, il cliente sceglie anche Credit Card, ATM (Virtual Account), CVS (Convenience Store) o Barcode sotto Payment Method.

Dopo la conferma, il cliente vede Redirecting to ECPay for payment. Please wait... ed è inviato alla pagina di pagamento ECPay, con un pulsante Proceed to ECPay nel caso il reindirizzamento non parta. Il totale del carrello viene inviato in TWD interi con i nomi e le quantità dei prodotti. La pagina ECPay si apre in cinese tradizionale per le lingue taiwanese e di Hong Kong, in cinese semplificato, coreano o giapponese per quelle lingue, e in inglese per tutte le altre, seguendo la lingua del negozio del cliente. A questo punto non esiste ancora alcun ordine.

L'ordine viene creato solo dopo che ECPay lo conferma con una notifica firmata dal server. Quando il cliente fa clic sul link di ritorno al negozio nella pagina ECPay e l'ordine esiste già, si apre la pagina standard di conferma dell'ordine. Mostra Your ECPay payment has been received. per un ordine pagato, Your ECPay payment was received and is being reviewed by the store. per un ordine in sospeso e le istruzioni di pagamento per un ordine ATM, CVS o con codice a barre in attesa. Se la notifica non è ancora arrivata, una pagina Payment confirmation mostra We have not received a payment confirmation from ECPay for this order yet. Your order will be created as soon as ECPay confirms the payment. con i pulsanti Check again e Back to checkout. Se ECPay ha segnalato che il pagamento non è riuscito, il cliente torna al checkout con The payment was not completed. You can try again or choose another payment method. Il carrello viene conservato.

Per ATM, CVS e codice a barre il cliente riceve prima i dati di pagamento. L'ordine viene creato in Awaiting ECPay payment, e il codice banca e il conto virtuale, il codice di pagamento del negozio di convenienza o i codici a barre, l'importo e la data Pay before vengono mostrati sotto ECPay payment instructions nella pagina di conferma dell'ordine e nei dettagli dell'ordine del cliente. Quando il cliente paga, ECPay invia un'altra notifica e l'ordine viene segnato come pagato. Le istruzioni di pagamento non vengono aggiunte alle e-mail di PrestaShop.

Ogni tentativo crea un nuovo numero di transazione ECPay, perché ECPay rifiuta i numeri riutilizzati. Quindi i nuovi tentativi dopo un pagamento non riuscito funzionano, e se il cliente torna indietro nel browser alla pagina di reindirizzamento, viene avviato un nuovo tentativo. Un carrello può avere fino a 30 tentativi di pagamento. Una volta che il carrello ha un ordine, non può più essere pagato tramite il checkout; un ordine ATM o CVS in attesa si paga con i dati già emessi.

Se il pagamento non può essere avviato, il cliente resta al checkout con un breve messaggio, per esempio The order total is too small for ECPay. quando il totale è inferiore a 1 TWD dopo l'arrotondamento. I limiti di importo propri di ECPay per ciascun metodo vengono verificati nella pagina ECPay, non al checkout.

Il modulo accetta pagamenti singoli solo nella pagina ECPay. Non prevede rimborsi da PrestaShop, carte salvate, abbonamenti o pagamenti periodici (定期定額), pagamenti a rate, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, fatture elettroniche o logistica, e non effettua interrogazioni lato server dello stato: se il tuo negozio non riesce a ricevere la notifica, verifica il pagamento nel back office di ECPay.

Ordini

Stati dell'ordine

No order yet: il cliente è stato inviato a ECPay e non ha pagato, oppure la notifica non è ancora arrivata. Esiste solo il carrello.

Awaiting ECPay payment: il cliente ha scelto ATM, CVS o codice a barre e ha ricevuto i dati di pagamento. La nota mostra il codice banca e il conto virtuale, il codice di pagamento o i codici a barre e la scadenza.

Payment accepted: il pagamento è stato confermato. Il pagamento viene registrato con il TradeNo ECPay come ID transazione, e una nota mostra il TradeNo, il tipo di pagamento, l'importo e il numero di transazione (con un contrassegno di modalità di test per i pagamenti sandbox).

ECPay payment on hold: ECPay ha segnalato un importo o una valuta diversi dal carrello (per esempio, il carrello è stato modificato in un'altra scheda dopo l'avvio del pagamento), un pagamento sandbox è arrivato dopo il passaggio alla modalità live (non è stato incassato denaro reale), oppure il pagamento è arrivato dopo che l'ordine era stato annullato (in tal caso il pagamento viene registrato). La nota lo spiega. Confronta con il back office di ECPay, poi evadi l'ordine o rimborsa il pagamento lì.

Payment error: ECPay ha segnalato che l'ultimo pagamento ATM, CVS o con codice a barre di un ordine in attesa non è riuscito. La nota mostra il codice di risposta e il messaggio di ECPay.

Le notifiche ripetute vengono ignorate. Un ordine pagato, rimborsato o annullato non viene mai riaperto da un fallimento tardivo. Un secondo pagamento per un ordine già pagato, per esempio da due schede del browser, viene annotato una sola volta, così puoi rimborsarlo nel back office di ECPay. I pagamenti simulati avviati dal back office di ECPay vengono solo annotati e non segnano mai un ordine come pagato, perché ECPay non incassa denaro per essi.

Blocco di pagamento ECPay

La pagina dell'ordine mostra un blocco ECPay payment con ogni tentativo di pagamento dell'ordine: il MerchantTradeNo con un badge Test mode per i tentativi sandbox, il metodo, l'importo in TWD, lo stato, il TradeNo ECPay, il tipo di pagamento e la data, e il codice di risposta ECPay. Sotto ci sono le ECPay notes dell'ordine. Per un ordine in ECPay payment on hold, il blocco ti ricorda di confrontarlo con il back office di ECPay.

Rimborsi

I rimborsi da PrestaShop non sono disponibili. Rimborsa il pagamento nel back office di ECPay, poi aggiorna manualmente l'ordine in PrestaShop. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite ECPay.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox ECPay Payment Gateway è il primo blocco di Modules > Module Manager > VibeFox ECPay 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 ci sono la riga Product: presta-payment-ecpay 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 un cambio dell'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 dominio: il dominio 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, ECPay non viene mostrato ai clienti al checkout. Se comunque viene avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. La vetrina di PrestaShop 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.

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 alla 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

ECPay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che il carrello del cliente sia in TWD e che, in modalità live, Merchant ID, Hash Key e Hash IV siano impostati. La pagina delle impostazioni mostra un messaggio in ciascuno di questi casi. In Payment > Preferences verifica che il modulo sia consentito per TWD, per il paese del cliente e per il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: la notifica ECPay non è arrivata al tuo negozio (sito non raggiungibile, firewall, autenticazione di base). ECPay riprova più volte. Puoi anche verificare la transazione nel back office di ECPay. Attiva Enable Logging per vedere le notifiche ricevute dal modulo; le notifiche rifiutate vengono comunque registrate come errori.

La notifica risponde 0|CheckMacValue verification failed: Hash Key o Hash IV non corrispondono al tuo account ECPay, oppure il pagamento è stato avviato nell'altro ambiente. Copiali di nuovo dal back office di ECPay.

La notifica risponde 0|MerchantID mismatch: la notifica appartiene a un commerciante ECPay diverso da quello con cui è stato avviato il pagamento.

La notifica risponde 0|Order not found: il numero di transazione non è stato emesso da questo negozio, per esempio quando più negozi condividono un account ECPay. Assegna a ciascun negozio un proprio Order Prefix.

La notifica risponde 0|Retry: il carrello era in elaborazione da parte di un'altra notifica nello stesso momento, oppure l'ordine non ha potuto essere creato (per esempio perché il modulo è disattivato). ECPay invia di nuovo la notifica. Attiva Enable Logging per vedere il motivo.

L'URL di notifica mostra 0|Method not allowed in the browser: è normale. L'URL accetta solo richieste da ECPay.

Il cliente vede «The order total is too small for ECPay.»: il totale del carrello è inferiore a 1 TWD dopo l'arrotondamento e non può essere pagato con ECPay.

Il cliente vede «Too many payment attempts for this order»: il carrello ha raggiunto 30 tentativi di pagamento. Chiedi al cliente di iniziare un nuovo carrello.

L'ordine è in ECPay payment on hold: leggi le note nel blocco ECPay payment (vedi Stati dell'ordine), confrontale con il back office di ECPay, poi evadi l'ordine o rimborsa il pagamento lì.

Sviluppatori: l'hook actionEcpayPRequestParams permette a un altro modulo di modificare i parametri inviati a ECPay; commerciante, numero di transazione e importo non possono essere modificati tramite esso.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox ECPay Payment Gateway e scegli Uninstall. La chiave di licenza e lo stato di 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 reinstallazione successiva. I record dei pagamenti ECPay e gli stati dell'ordine Awaiting ECPay payment e ECPay payment on hold vengono sempre conservati, così le notifiche tardive di pagamenti vecchi continuano a essere verificate dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID di transazione.

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