VibeFox Eupago for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo.
PHP: 8.0 o successivo.
Valuta del negozio: euro (EUR). Eupago addebita solo in euro, quindi per le altre valute il metodo di pagamento viene nascosto al checkout.
Account Eupago: ti serve la chiave API del tuo canale Eupago e la chiave di un Webhook 2.0 che crei nel back office Eupago (vedi Configurazione). Il back office live è clientes.eupago.pt, quello sandbox è sandbox.eupago.pt. Sandbox e live sono account separati con chiavi separate.
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_eupago_gateway in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Eupago > 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 API del tuo canale Eupago, crea un Webhook 2.0 nel back office Eupago e incolla la sua chiave (vedi Configurazione).
6. Scegli il Payment Method, attiva Enable/Disable, effettua un ordine di prova in modalità sandbox, poi deseleziona Sandbox Mode.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Eupago. Quando il gateway è attivo, la pagina ti avvisa se la chiave API della modalità corrente è vuota (in tal caso il gateway viene nascosto al checkout), oppure mostra Sandbox mode: no real payments are taken. finché la modalità sandbox è attiva. Nell'elenco dei metodi di pagamento Eupago è segnalato come bisognoso di intervento finché non viene impostata la chiave API della modalità corrente, e in modalità sandbox mostra un badge di modalità di test.
Generali
Enable/Disable: Enable Eupago Gateway attiva o disattiva il metodo di pagamento. Predefinito: off.
Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Eupago.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via Eupago.
Payment Method: l'unico metodo Eupago offerto al checkout.
Order Status After Payment: lo stato dell'ordine impostato quando il pagamento viene confermato: Processing (predefinito) o Completed. Lo stato viene impostato subito, con un unico cambio di stato e una sola e-mail.
Account Eupago
Ottieni la chiave API del tuo canale e la chiave del Webhook 2.0 nel back office Eupago: clientes.eupago.pt (live) o sandbox.eupago.pt (sandbox).
Sandbox Mode: Enable sandbox/test mode usa sandbox.eupago.pt e le chiavi sandbox. Non viene incassato alcun pagamento reale. Predefinito: on. Deselezionalo per accettare pagamenti reali con le chiavi live.
Live API Key: la chiave API del tuo canale Eupago live (clientes.eupago.pt).
Live Webhook Key: la chiave di cifratura del tuo Webhook 2.0 live. Obbligatoria: le notifiche senza firma valida vengono rifiutate.
Sandbox API Key: la chiave API del tuo canale sandbox (sandbox.eupago.pt).
Sandbox Webhook Key: la chiave di cifratura del tuo Webhook 2.0 sandbox.
URL del webhook
Il webhook comunica al negozio che un pagamento è stato effettuato. Nel back office Eupago crea un Webhook 2.0 con l'URL mostrato in questa sezione delle impostazioni, metodo POST e cifratura attiva. L'URL ha questo aspetto: https://your-site/wc-api/eupago_payment_callback/. Crea un webhook nel back office sandbox e un altro in quello live.
Copia la chiave di ciascun webhook in Sandbox Webhook Key o Live Webhook Key. I webhook senza firma valida vengono rifiutati. Un webhook non cifrato viene accettato solo se Eupago lo firma, quindi mantieni la cifratura attiva. Il plugin reagisce a questi stati di notifica:
Gli altri stati non richiedono alcuna azione. Anche il callback GET legacy di Eupago verso lo stesso URL viene accettato; è autenticato dalla chiave API e segnala sempre un pagamento. Senza notifiche gli ordini non vengono mai segnati come pagati: il plugin non interroga Eupago e il ritorno del cliente non paga un ordine.
Avanzate
Debug Log: Enable logging scrive le chiamate API e le notifiche in WooCommerce > Status > Logs, origine wcp_eupago_gateway. Chiavi, e-mail e numeri di telefono completi non vengono registrati. Gli errori vengono sempre registrati. Predefinito: off.
Delete Data on Uninstall: Delete all plugin data when uninstalling. Se selezionato, le impostazioni del gateway e i log vengono rimossi quando il plugin viene eliminato. Ordini e relativi dati di pagamento vengono conservati. Predefinito: off.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Eupago) e invia l'ordine. In modalità sandbox il checkout mostra SANDBOX / TEST MODE. Ciò che accade dopo dipende da Payment Method.
Multibanco: al checkout il cliente vede You will receive Multibanco payment details after placing the order. Il plugin crea un riferimento Multibanco per l'importo totale dell'ordine. L'ordine viene messo In attesa, le scorte vengono ridotte e il carrello viene svuotato. La pagina di ricezione dell'ordine mostra Multibanco Payment Details con entità, riferimento e importo. Gli stessi dati vengono aggiunti all'e-mail d'ordine del cliente finché l'ordine attende il pagamento. Il cliente paga a uno sportello ATM o nell'home banking.
MB WAY: al checkout il cliente inserisce MB WAY Phone Number, precompilato con il telefono di fatturazione. I numeri portoghesi possono essere inseriti senza +351. Un numero errato mostra Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). Il plugin invia la richiesta di pagamento all'app MB WAY. L'ordine viene messo In attesa, le scorte vengono ridotte e il carrello viene svuotato. La pagina di ricezione dell'ordine chiede al cliente di aprire l'app MB WAY e approvare la richiesta entro 5 minuti.
Credit Card: al checkout il cliente vede You will be redirected to a secure payment page to enter your card details. Il cliente viene inviato alla pagina carte di Eupago, in portoghese, spagnolo o inglese in base alla lingua del sito. L'ordine resta In attesa di pagamento e il carrello viene conservato. Dopo il pagamento il cliente torna alla pagina di ricezione dell'ordine, che mostra Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. finché non arriva la notifica. Se il pagamento con carta non riesce o viene abbandonato, il cliente finisce sulla pagina Pay for order con The card payment was not completed. You can try again or choose another payment method. oppure The card payment was cancelled. You can try again or choose another payment method.
Per ogni metodo, l'ordine viene segnato come pagato solo dopo che Eupago lo conferma con una notifica verificata. Un cliente può pagare di nuovo un ordine non pagato dalla pagina Pay for order; ogni riferimento di pagamento creato per l'ordine resta valido per la verifica.
Se Eupago non riesce ad avviare il pagamento, il cliente vede un breve messaggio, per esempio The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. L'ordine non cambia e i dettagli sono nel log.
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 al cliente sono tradotti in portoghese.
Il plugin offre un solo metodo Eupago per installazione. Non prevede rimborsi da WooCommerce, carte salvate, abbonamenti o pre-autorizzazioni, PayShop, Cofidis Pay, Bizum o altri metodi Eupago, promemoria SMS, data di scadenza di Multibanco né verifica dello stato.
Ordini
Stati dell'ordine
Pending payment: è stato avviato un pagamento con carta e Eupago non l'ha ancora confermato.
On hold, awaiting payment: è stato creato un riferimento Multibanco o una richiesta MB WAY. La nota dell'ordine mostra l'entità e il riferimento oppure il numero di telefono mascherato.
Processing or Completed: il pagamento è stato confermato. Lo stato segue Order Status After Payment. La nota dell'ordine mostra il metodo, l'ID transazione Eupago e il riferimento. L'ID transazione dell'ordine è l'ID transazione Eupago.
On hold, manual review: Eupago ha segnalato un pagamento con importo o valuta diversi, con un riferimento non creato per questo ordine, oppure per un ordine nel frattempo annullato o non riuscito (per esempio un riferimento Multibanco pagato in ritardo). La nota lo spiega. Controlla il pagamento e le scorte, poi completa l'ordine manualmente o rimborsa il cliente. Le notifiche successive per questo pagamento non completano l'ordine senza che tu lo sappia.
Cancelled: Eupago ha segnalato il pagamento come annullato o scaduto, per il tentativo di pagamento in corso di un ordine non pagato.
Failed: Eupago ha segnalato un errore per il tentativo di pagamento in corso di un ordine non pagato.
Se Eupago segnala un altro pagamento per un ordine già pagato (per esempio è stato pagato anche un riferimento Multibanco precedente), l'ordine non cambia. Una nota ti chiede di verificare un pagamento duplicato e di rimborsarlo nel back office Eupago. Una notifica di pagamento non riapre mai un ordine che era stato pagato e poi annullato o rimborsato.
Rimborsi: i rimborsi da WooCommerce non sono supportati. Rimborsa il cliente nel back office Eupago e registra il rimborso in WooCommerce con Refund manually.
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 > Eupago. 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 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 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, Eupago 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. Gli amministratori del negozio connessi vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati.
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
Eupago non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la chiave API della modalità corrente sia impostata (Sandbox API Key in modalità sandbox, Live API Key in modalità live) e che la valuta del negozio sia EUR. Con Multibanco l'importo dell'ordine deve essere compreso tra 1 € e 999 999,99 €.
Il pagamento è andato a buon fine, ma l'ordine resta Pending payment o On hold: la notifica Eupago non arriva o viene rifiutata. Nel back office Eupago della modalità che usi, verifica che il Webhook 2.0 esista, che il suo URL sia esattamente quello mostrato nelle impostazioni, che il metodo sia POST e che la cifratura sia attiva. Controlla che la sua chiave sia nel campo corrispondente (Sandbox Webhook Key o Live Webhook Key). Attiva Debug Log e consulta WooCommerce > Status > Logs, origine wcp_eupago_gateway. Se una notifica non arriva mai, controlla il pagamento nel back office Eupago.
Il webhook risponde Invalid signature o Missing signature: la chiave del webhook nel plugin non corrisponde alla chiave del webhook, oppure il webhook non è cifrato né firmato. Copia di nuovo la chiave e mantieni la cifratura attiva.
Il webhook risponde Webhook key not configured: nessuna delle due chiavi webhook è impostata. Eupago ripete la notifica dopo che incolli la chiave.
Il webhook risponde Decryption failed: la firma è valida, ma il corpo non può essere decifrato. Controlla le impostazioni del Webhook 2.0 nel back office Eupago.
Il webhook risponde Environment mismatch: la notifica è firmata con la chiave dell'altra modalità rispetto a quella in cui è stato effettuato l'ordine. Una notifica sandbox non paga mai un ordine live e viceversa.
Il callback legacy risponde Invalid API key: la chiave API inviata da Eupago non corrisponde a Live API Key o a Sandbox API Key.
Il cliente vede The MB WAY payment could not be started: verifica che il numero di telefono sia associato a MB WAY e riprova.
L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. Importo o valuta erano diversi, il riferimento era sconosciuto oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Verifica il pagamento nel back office Eupago, poi completa l'ordine o rimborsa il cliente.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per 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, la documentazione del plugin elenca i filtri eupago_p_icon (icona del checkout) e eupago_p_card_language (lingua della pagina carte di Eupago: PT, EN o ES).
Disinstallazione
Disattivare il plugin mantiene 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 del gateway e i log vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Ordini e relativi riferimenti Eupago vengono sempre conservati. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.
Eupago è un marchio del rispettivo titolare. Questo plugin non è affiliato a Eupago né approvato da Eupago.