VibeFox EveryPay for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo.

PHP: 8.0 o successivo.

Account EveryPay: ti servono il nome utente API, il segreto API e il nome dell'account di elaborazione del tuo negozio online. Si trovano nell'EveryPay Merchant Portal, nelle impostazioni del negozio: il portale demo (mwt-demo.every-pay.com) per la modalità test e il portale live (portal.every-pay.eu) per i pagamenti reali. Gli ambienti test e live hanno credenziali separate. Devi inoltre impostare l'URL di callback del tuo negozio in entrambi i portali (vedi Configurazione).

Valuta del negozio: l'account di elaborazione definisce la valuta addebitata, per esempio EUR3D1 addebita in EUR. Il metodo di pagamento viene offerto solo per gli ordini in quella valuta.

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_everypay_payment in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > EveryPay > 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 il nome utente API di test, il segreto API di test e il nome dell'account di elaborazione dal Merchant Portal demo. Lascia attivo Test Mode.

6. Copia l'URL di callback mostrato nella pagina delle impostazioni in Callback notification URL del tuo negozio nel Merchant Portal.

7. Attiva Enable/Disable ed effettua un ordine di prova. Quando tutto funziona, inserisci le credenziali live, imposta l'URL di callback anche nel portale live e disattiva Test Mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > EveryPay. Sopra i campi la pagina mostra Test mode is on: payments go to the EveryPay demo environment, no real money is charged. finché la modalità test è attiva. Ti avvisa quando il gateway è attivo ma mancano nome utente API, segreto API o account di elaborazione della modalità corrente (il metodo di pagamento viene quindi nascosto al checkout), e quando l'account di elaborazione addebita una valuta diversa da quella del negozio. Nell'elenco dei metodi di pagamento EveryPay risulta da configurare finché non è configurata la modalità corrente. Gli spazi e le interruzioni di riga incollati insieme alle credenziali vengono rimossi al salvataggio.

Generale

Enable/Disable: Enable EveryPay 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: EveryPay.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely by card or bank link on the EveryPay payment page.

Account EveryPay

Il nome utente API, il segreto API e il nome dell'account di elaborazione sono mostrati nell'EveryPay Merchant Portal (impostazioni del negozio): il portale demo per la modalità test, il portale live per i pagamenti reali.

Test Mode: Enable test mode invia i pagamenti all'ambiente demo di EveryPay con le credenziali di test. Non viene addebitato denaro reale. Predefinito: attivo.

Test API Username: il nome utente API dell'ambiente demo.

Test API Secret: il segreto API dell'ambiente demo.

Live API Username: il nome utente API dell'ambiente live.

Live API Secret: il segreto API dell'ambiente live.

Processing Account Name: l'account di elaborazione EveryPay, per esempio EUR3D1. L'account definisce la valuta addebitata: il gateway viene offerto solo per gli ordini in quella valuta. Lo stesso nome account viene usato in entrambe le modalità.

Notifiche di pagamento (callback)

Il callback comunica al tuo negozio che un pagamento è stato completato, così gli ordini vengono aggiornati anche se il cliente chiude il browser. Copia l'URL mostrato in questa sezione in Callback notification URL del tuo negozio nell'EveryPay Merchant Portal, sia demo sia live. L'URL ha questa forma: https://your-site/wc-api/wc_evp_payment/. La richiesta di pagamento non contiene un URL di callback, quindi va impostato nel portale.

Il callback contiene solo riferimenti di pagamento. Quando arriva, il plugin chiede all'API EveryPay lo stato del pagamento nell'ambiente in cui il pagamento è stato creato e verifica che la risposta appartenga a questo ordine. I callback relativi a un pagamento che l'ordine non ha creato vengono rifiutati. Senza il callback, un ordine viene confermato quando il cliente torna sul negozio dopo aver pagato, oppure quando esegui Check EveryPay payment status sull'ordine.

Avanzate

Debug log: Log payment events scrive gli eventi di pagamento in WooCommerce > Status > Logs, origine wcp_everypay_payment. Gli errori vengono sempre registrati. Segreti API e dati della carta non vengono mai registrati. Predefinito: disattivato.

Uninstall: Delete the gateway settings and logs when the plugin is deleted. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita EveryPay) e completa l'ordine. In modalità test il checkout mostra TEST MODE: EveryPay demo environment, no real money is charged. Il plugin crea un pagamento EveryPay una tantum per il totale dell'ordine, con l'e-mail e i dati di fatturazione del cliente, e invia il cliente alla pagina di pagamento EveryPay. La lingua della pagina segue la lingua del sito (inglese, estone, russo, lettone, lituano, finlandese o tedesco; altrimenti inglese). Lì il cliente paga con uno dei metodi attivati per il tuo account EveryPay.

Dopo il pagamento il cliente torna sul tuo negozio. L'ordine viene segnato come pagato solo quando EveryPay lo conferma: il plugin chiede all'API EveryPay lo stato del pagamento al ritorno del cliente e sul callback. Un ordine pagato, un ordine in verifica o un pagamento ancora in elaborazione porta alla pagina «Ordine ricevuto».

Se il pagamento non va a buon fine, il cliente torna al checkout (o alla pagina Pay for order) con il messaggio Your EveryPay payment was not successful. Please try again or choose another payment method. Se il cliente ha lasciato la pagina di pagamento senza pagare, il messaggio è The EveryPay payment was not completed. You can try again or choose another payment method. Ogni nuovo tentativo crea un nuovo pagamento EveryPay; i tentativi precedenti vengono ricordati, quindi un pagamento effettuato con un vecchio link viene comunque riconosciuto.

Se EveryPay non riesce ad avviare il pagamento, il cliente vede un breve messaggio, per esempio EveryPay is temporarily unavailable. Please try again in a moment or choose another payment method. I dettagli sono nel registro.

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). I testi visibili ai clienti sono tradotti in estone.

Il plugin accetta solo pagamenti una tantum. Non prevede rimborsi o acquisizioni da WooCommerce, carte salvate o pagamenti con un clic, abbonamenti o pagamenti ricorrenti, campi carta incorporati né più valute.

Ordini

Stati dell'ordine

Pending payment: il cliente è stato inviato a EveryPay e non ha ancora pagato, oppure il pagamento è ancora in elaborazione.

Processing: EveryPay ha comunicato che il pagamento è regolato o autorizzato (gli ordini con soli prodotti virtuali scaricabili passano a Completato, il valore predefinito di WooCommerce). La nota dell'ordine mostra importo, valuta e riferimento del pagamento. L'ID transazione dell'ordine è il riferimento del pagamento EveryPay. Per un pagamento autorizzato la nota indica che i fondi sono riservati: se il tuo account non acquisisce automaticamente, acquisisci il pagamento nell'EveryPay Merchant Portal. Quando viene regolato in seguito, una nota lo segnala.

On hold after payment: il pagamento richiede una verifica manuale. L'importo o la valuta pagati non corrispondono all'ordine, l'ordine era stato annullato prima dell'arrivo del pagamento, oppure ora l'ordine usa un altro metodo di pagamento. La nota lo spiega e indica che l'ordine non è stato segnato come pagato. Controlla il pagamento nel Merchant Portal e completalo o rimborsalo manualmente. I callback successivi per questo pagamento non completano l'ordine automaticamente.

Failed: l'ultimo tentativo di pagamento di un ordine non pagato non è riuscito, è stato abbandonato o annullato. La nota mostra il motivo indicato da EveryPay. Il cliente può riprovare.

Se per un ordine già pagato viene completato un secondo pagamento, l'ordine non cambia. Una nota ti chiede di rimborsare il pagamento duplicato nell'EveryPay Merchant Portal.

Check EveryPay payment status

Nella schermata dell'ordine scegli l'azione Check EveryPay payment status. Il plugin verifica con l'API ogni pagamento EveryPay dell'ordine, applica il risultato come descritto sopra e aggiunge una nota con lo stato di ciascun pagamento. Usala per gli ordini il cui callback non è mai arrivato.

Rimborsi

I rimborsi da WooCommerce non sono supportati. Rimborsa nell'EveryPay Merchant Portal, poi imposta lo stato dell'ordine in WooCommerce. Quando EveryPay segnala un pagamento come rimborsato o contestato (chargeback), il plugin aggiunge solo una nota all'ordine; lo stato dell'ordine non cambia.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > EveryPay. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino a cui 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 solo dominio. Rimuovere la chiave da un sito non libera il suo posto per il dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, EveryPay 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 da (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Nella pagina Plugin e nelle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e il controllo dello stato funziona.

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

EveryPay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che nome utente API, segreto API e Processing Account Name della modalità corrente siano impostati, e che la valuta del negozio (nella pagina Pay for order, la valuta dell'ordine) sia quella dell'account di elaborazione. La pagina delle impostazioni mostra un avviso in questi casi.

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: il callback non funziona. Controlla che l'URL di callback indicato nelle impostazioni sia impostato come Callback notification URL nel Merchant Portal della modalità che usi (demo o live). Puoi anche aprire l'ordine ed eseguire Check EveryPay payment status. Attiva Debug log e consulta WooCommerce > Status > Logs, origine wcp_everypay_payment.

Il callback risponde Unknown payment reference oppure Payment does not belong to this order: il pagamento non è stato creato da questo ordine, oppure la risposta di EveryPay non corrisponde. L'ordine non viene modificato.

Il callback risponde Not configured: mancano le credenziali dell'ambiente in cui è stato creato il pagamento, per esempio un pagamento di test dopo la rimozione delle credenziali di test. Inseriscile di nuovo; EveryPay ripete il callback.

Il callback risponde Payment status unavailable oppure Busy, please retry: l'API EveryPay non era raggiungibile, oppure l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. EveryPay ripete il callback.

Il cliente vede EveryPay is temporarily unavailable: EveryPay ha rifiutato le credenziali o non era raggiungibile. Controlla nome utente API e segreto API della modalità corrente.

Il cliente vede This payment method does not support the order currency: la valuta dell'ordine è diversa da quella dell'account di elaborazione.

L'ordine è On hold after payment: leggi la nota dell'ordine. Importo o valuta erano diversi, oppure l'ordine era stato annullato prima dell'arrivo del pagamento. Controlla il pagamento nel Merchant Portal e completalo o rimborsalo manualmente.

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.

Per gli sviluppatori, la documentazione del plugin elenca i filtri wc_evp_icon, wc_evp_locale, wc_evp_currency_decimals e wc_evp_oneoff_request.

Disinstallazione

Disattivando il plugin, tutti i dati vengono mantenuti. 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 e i log vengono rimossi solo se Uninstall (Delete the gateway settings and logs when the plugin is deleted) era attivo. Altrimenti restano disponibili per una successiva reinstallazione. I riferimenti dei pagamenti EveryPay salvati sugli ordini vengono sempre conservati. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.

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