VibeFox ECPay 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: nuovo dollaro taiwanese (TWD). ECPay accetta pagamenti solo in TWD, e il metodo di pagamento viene nascosto quando il negozio, o l'ordine da pagare, usa un'altra valuta. Gli importi vengono inviati in TWD interi, perché ECPay non accetta decimali: i totali dell'ordine vengono arrotondati al dollaro più vicino. Usa 0 decimali per i prezzi in TWD per evitare l'arrotondamento.

Account ECPay: per i pagamenti live hai bisogno di MerchantID, HashKey e HashIV del tuo account commerciante ECPay, dal back-office commerciante ECPay (vendor.ecpay.com.tw). Per i test non è necessario alcun account ECPay.

Accesso al sito: il tuo sito deve essere raggiungibile da internet via HTTP/HTTPS sulla porta 80/443, in modo che ECPay possa consegnare le notifiche di pagamento. La modalità di manutenzione, un firewall o l'autenticazione di base davanti al sito le bloccano.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un 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_ecpay_payment_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate. WooCommerce deve essere attivo.

3. Apri le impostazioni: WooCommerce > Settings > Payments > ECPay (綠界) > 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 alto nella pagina e fai clic su Activate.

5. Attiva Enable/Disable, scegli i metodi di pagamento e lascia attivo Test Mode per i primi test. Nella sandbox puoi pagare con la carta di test ECPay 4311-9522-2222-2222 (qualsiasi data di scadenza futura, CVV 222, codice 3-D Secure dalla pagina della sandbox).

6. Per i pagamenti live inserisci MerchantID, HashKey e HashIV (vedi Configurazione) e deseleziona Test Mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > ECPay (綠界). Sopra i campi, la pagina mostra un errore quando la valuta del negozio non è TWD (ECPay non viene allora mostrato al checkout) e quando la modalità live non ha MerchantID, HashKey e HashIV. Mentre la modalità di test è attiva, avverte che i pagamenti vanno alla sandbox di ECPay con il commerciante di test pubblico 3002607, che non viene incassato denaro reale, e che chiunque conosca le chiavi pubbliche della sandbox potrebbe confermare ordini di test, quindi la modalità di test deve essere disattivata prima di accettare ordini reali.

Generale

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: ECPay (綠界).

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

Account ECPay

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

Test Mode: Enable sandbox/test mode invia i pagamenti alla sandbox di ECPay (payment-stage.ecpay.com.tw) con il commerciante di test pubblico ECPay 3002607. Nessun denaro reale. Le credenziali sotto vengono usate solo quando la modalità di test è disattivata. Predefinito: attivato.

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

Hash Key: la tua Hash Key ECPay (produzione). Ignorata in modalità di test.

Hash IV: la tua Hash IV ECPay (produzione). Ignorata 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.

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 Barcode restano In sospeso finché il cliente non paga. Deve essere selezionato almeno un metodo; se non lo è, viene attivato Credit Card. 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. Utile quando più negozi condividono un account ECPay: assegna a ciascun negozio il proprio prefisso. Predefinito: EC.

Notifiche di pagamento

ECPay invia i risultati di pagamento al tuo negozio. Questa sezione mostra l'URL di notifica. Ha questo aspetto: https://your-site/wc-api/ecpay_p_callback/. L'URL viene inviato con ogni pagamento, quindi non c'è nulla da configurare in ECPay, ma deve essere raggiungibile da internet sulla porta 80/443 senza modalità di manutenzione, firewall o autenticazione di base davanti.

Ogni notifica viene verificata tramite la sua firma CheckMacValue con le chiavi dell'ambiente (test o live) in cui è stato avviato il pagamento. Le notifiche senza una firma valida vengono rifiutate, ed ECPay le invia di nuovo. Senza la notifica, nessun ordine viene segnato come pagato; controlla il pagamento nel back-office di ECPay.

Avanzate

Enable Logging: Log payment events and API calls scrive gli ID ordine, i numeri di transazione, gli importi e i codici di ritorno ECPay in WooCommerce > Status > Logs, origine wcp_ecpay_payment_gateway. Non vengono registrate chiavi o dati dei clienti. Predefinito: disattivato.

Delete Data on Uninstall: Delete all plugin data when uninstalling. Rimuove tutte le impostazioni, i registri e i metadati d'ordine di questo plugin. Predefinito: disattivato.

Checkout

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. Mentre la modalità di test è attiva, il metodo di pagamento mostra TEST MODE — ECPay sandbox, no real money is charged.

Dopo l'invio dell'ordine, il cliente vede Redirecting to ECPay for payment. Please wait... e viene inviato alla pagina di pagamento ECPay, con un pulsante Proceed to ECPay nel caso in cui il reindirizzamento non parta. Il totale dell'ordine viene inviato in TWD interi con i nomi e le quantità degli articoli. La pagina ECPay si apre in cinese tradizionale per le lingue del sito taiwanese e di Hong Kong, in cinese semplificato, coreano o giapponese per quelle lingue, e in inglese per tutte le altre.

L'ordine viene segnato come pagato solo dopo che ECPay lo conferma con una notifica di server firmata. Quando il cliente torna alla pagina dell'ordine ricevuto prima che arrivi la conferma, la pagina mostra We have not received a payment confirmation from ECPay for this order yet. If you did not complete the payment, you can try again: con un pulsante Pay.

Per ATM, CVS e Barcode il cliente riceve prima i dettagli di pagamento. L'ordine viene messo In sospeso, e il codice bancario e il conto virtuale, il codice di pagamento per negozio di convenienza o i codici a barre, l'importo e la data Pay before vengono mostrati in ECPay payment instructions nella pagina di ringraziamento, in My account > Orders e nell'e-mail dell'ordine in sospeso. Quando il cliente paga, ECPay invia un'altra notifica e l'ordine viene segnato come pagato.

Ogni visita alla pagina di pagamento crea un nuovo numero di transazione ECPay, perché ECPay rifiuta i numeri riutilizzati. Così la pagina Pay for order e i nuovi tentativi dopo un pagamento non riuscito funzionano, e le notifiche per uno di questi numeri vengono associate all'ordine. Un ordine può avere fino a 30 tentativi di pagamento.

I limiti di importo propri di ECPay per metodo, per esempio per i pagamenti nei negozi di convenienza, vengono verificati sulla pagina ECPay, non al checkout.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin accetta solo pagamenti singoli sulla pagina ECPay. Non prevede rimborsi da WooCommerce, carte salvate, abbonamenti o pagamenti periodici (定期定額), pagamenti a rate, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, fatture elettroniche o logistica, né una verifica dello stato lato server: se il tuo sito non può ricevere la notifica, controlla il pagamento nel back-office di ECPay.

Ordini

Stati dell'ordine

Pending payment: il cliente è stato inviato a ECPay e non ha ancora pagato, oppure la notifica non è ancora arrivata.

On hold, waiting for payment: il cliente ha scelto ATM, CVS o Barcode e ha ricevuto i dettagli di pagamento. La nota dell'ordine mostra il codice bancario e il conto virtuale, il codice di pagamento o i codici a barre e la scadenza.

Processing: il pagamento è stato confermato (il valore predefinito di WooCommerce; gli ordini con soli prodotti scaricabili virtuali diventano Completato). La nota dell'ordine mostra il TradeNo ECPay, il tipo di pagamento, l'importo e il numero di transazione. L'ID della transazione è il TradeNo ECPay.

On hold after payment: ECPay ha segnalato un importo o una valuta diversi dall'ordine, un pagamento sandbox è arrivato dopo il passaggio alla modalità live (nessun denaro reale è stato incassato), oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota dell'ordine lo spiega. Confronta con il back-office di ECPay e completa o rimborsa l'ordine manualmente.

Failed: ECPay ha segnalato che l'ultimo tentativo di pagamento non è riuscito. La nota mostra il codice e il messaggio di ritorno ECPay. Il cliente può riprovare.

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

Rimborsi

I rimborsi da WooCommerce non sono disponibili. Rimborsa il pagamento nel back-office di ECPay, poi registra il rimborso manualmente in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in alto in WooCommerce > Settings > Payments > ECPay (綠界). 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 controllare 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 dominio. Rimuovere la chiave da un sito non libera il posto del suo dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, ECPay non viene mostrato ai clienti al checkout. Se un pagamento viene comunque avviato, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio con sessione attiva vedono comunque il metodo di pagamento, contrassegnato (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria appare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati.

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

Risoluzione dei problemi

ECPay non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivato, che la valuta del negozio sia TWD e che, in modalità live, siano impostati Merchant ID, Hash Key e Hash IV. La pagina delle impostazioni mostra un errore in ciascuno di questi casi.

Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: la notifica di ECPay non ha raggiunto il tuo sito (sito non raggiungibile, firewall, modalità di manutenzione, autenticazione di base). ECPay riprova più volte. Puoi anche controllare la transazione nel back-office di ECPay e completare l'ordine manualmente. Attiva Enable Logging per vedere le notifiche ricevute dal plugin.

La notifica risponde 0|CheckMacValue verification failed: la Hash Key o la Hash IV non corrisponde al tuo account ECPay. Copiale 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 il proprio Order Prefix.

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

L'ordine è In sospeso con una nota di discordanza dell'importo: l'importo segnalato da ECPay è diverso dal totale dell'ordine, per esempio perché l'ordine è stato modificato dopo che il cliente ha iniziato a pagare. Confronta con il back-office di ECPay e completa o rimborsa l'ordine manualmente.

L'ordine è In sospeso dopo un pagamento sandbox: il pagamento è stato effettuato in modalità di test, ma il negozio è ora in modalità live. Nessun denaro reale è stato incassato. Controlla l'ordine manualmente.

Il cliente vede Too many payment attempts for this order: l'ordine ha raggiunto 30 tentativi di pagamento. Chiedi al cliente di effettuare un nuovo ordine.

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 di licenza non è raggiungibile, il plugin continua a funzionare con l'ultimo stato conosciuto.

Disinstallazione

Disattivare il plugin conserva 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, i dati ECPay memorizzati negli ordini e i registri vengono rimossi solo se Delete Data on Uninstall era attivato. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le loro note di pagamento e gli ID di transazione.

ECPay è un marchio del suo rispettivo proprietario. Questo plugin non è affiliato con ECPay né approvato da ECPay.