VibeFox Eupago 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: euro (EUR). Eupago addebita solo in euro, quindi per i carrelli in altre valute il metodo di pagamento viene nascosto al checkout.

Account Eupago: ti servono 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, il back office 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 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 VibeFox Eupago Gateway più tardi 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 clicca su Activate (vedi Chiave di licenza).

4. Inserisci la chiave API del tuo canale Eupago, crea un Webhook 2.0 nel back office Eupago e incolla la sua chiave (vedi Configurazione).

5. Scegli il Payment Method, attiva Enable/Disable e clicca su Save. Effettua un ordine di prova in modalità sandbox, poi disattiva Sandbox Mode.

All'installazione il modulo crea due stati dell'ordine, Awaiting Eupago payment e Eupago 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; l'euro deve restare consentito per il modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Eupago Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Quando il metodo di pagamento è attivo, la pagina ti avvisa sopra i campi se la chiave API della modalità corrente è vuota (il metodo di pagamento viene allora nascosto al checkout), oppure mostra Sandbox mode: no real payments are taken. finché la modalità sandbox è attiva.

Eupago

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Eupago. Obbligatorio: un titolo vuoto mostra Enter a title for the payment method.

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.

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 e live sono account separati con chiavi separate.

Sandbox Mode: usa sandbox.eupago.pt e le chiavi sandbox. Non viene addebitato alcun pagamento reale. Predefinito: attivo. Disattivalo per accettare pagamenti reali con le chiavi live. Finché è attivo, i clienti vedono SANDBOX / TEST MODE sotto il metodo di pagamento.

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.

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

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

URL del webhook

Il webhook comunica al tuo negozio che un pagamento è stato effettuato. Nel back office Eupago crea un Webhook 2.0 con l'URL mostrato in questa sezione, metodo POST e cifratura attiva. Con gli URL parlanti l'URL ha questo aspetto: https://your-shop/module/wcp_eupago_gateway/webhook, eventualmente con un codice lingua come /pt/. Copia l'URL esattamente come lo mostrano le impostazioni. Crea un webhook nel back office sandbox e un altro nel back office 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 tieni attiva la cifratura. Una notifica deve essere firmata con la chiave della modalità in cui il pagamento è stato avviato, quindi una notifica sandbox non paga mai un pagamento live. Il modulo reagisce a questi stati di notifica:

Gli altri stati non richiedono alcuna azione. Viene accettato anche il callback GET legacy di Eupago verso lo stesso URL; è autenticato dalla chiave API e segnala sempre un pagamento. Senza notifiche, gli ordini non vengono mai segnati come pagati: il modulo non interroga Eupago e il ritorno del cliente non paga un ordine. Il webhook funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Avanzate

Debug Log: scrive le chiamate API e le notifiche in logs/eupago_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi, e-mail e numeri di telefono completi non vengono registrati. Gli errori vengono sempre registrati. Predefinito: disattivato.

Log: mostra la dimensione e gli ultimi inserimenti del registro. Clicca su Clear log per svuotarlo.

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway, i record dei pagamenti Eupago di questo modulo e il registro. Ordini e dati di pagamento vengono conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Eupago) nel passaggio di pagamento e conferma l'ordine. 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 modulo crea un riferimento Multibanco per il totale del carrello. L'ordine viene creato subito in Awaiting Eupago payment, come qualsiasi ordine PrestaShop, e il carrello viene svuotato. La pagina di conferma dell'ordine mostra Multibanco Payment Details con entità, riferimento e importo. Gli stessi dati vengono aggiunti alla riga di pagamento dell'e-mail di conferma dell'ordine. Il cliente paga a uno sportello ATM o nell'home banking.

MB WAY: al checkout il cliente inserisce il MB WAY Phone Number, precompilato con il telefono dell'indirizzo 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 modulo invia la richiesta di pagamento all'app MB WAY e crea l'ordine in Awaiting Eupago payment. La pagina di conferma dell'ordine chiede al cliente di aprire l'app MB WAY sul numero mascherato 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 delle carte di Eupago, in portoghese, spagnolo o inglese in base alla lingua del carrello. Non esiste ancora alcun ordine e il carrello viene conservato. L'ordine viene creato solo quando Eupago conferma il pagamento. Se la notifica è arrivata quando il cliente torna, vede la normale pagina di conferma dell'ordine. Altrimenti una pagina Payment confirmation mostra Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. con un pulsante Check again. Se il pagamento con carta fallisce o viene abbandonato, il cliente torna al checkout 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. I dettagli di pagamento vengono mostrati solo mentre l'ordine è in Awaiting Eupago payment. Se Eupago segnala in seguito che il pagamento è stato annullato, è scaduto o è fallito e l'ordine non era pagato, la pagina di conferma dell'ordine mostra Your Eupago payment was not completed. Please contact us about this order.

Se Eupago non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, ad esempio The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. Nessun ordine viene creato e i dettagli sono nel registro. Un carrello in un'altra valuta mostra Eupago only supports payments in EUR.

Il modulo offre un solo metodo Eupago per installazione. Non prevede rimborsi da PrestaShop, carte salvate, abbonamenti o pre-autorizzazioni, né PayShop, Cofidis Pay, Bizum o altri metodi Eupago, né promemoria SMS, data di scadenza di Multibanco o verifica dello stato.

Ordini

Stati dell'ordine

No order yet: è stato avviato un pagamento con carta e Eupago non lo ha ancora confermato. Esiste solo il carrello.

Awaiting Eupago payment: è stato creato un riferimento Multibanco o una richiesta MB WAY. La nota mostra l'entità e il riferimento oppure il numero di telefono mascherato.

Payment accepted or Delivered: il pagamento è stato confermato. Lo stato segue Order Status After Payment. Il pagamento viene registrato con l'ID transazione Eupago come ID transazione, e una nota mostra metodo, ID transazione e riferimento.

Eupago payment on hold: Eupago ha segnalato un pagamento con importo o valuta diversi, con un riferimento non creato per questo carrello, oppure per un ordine nel frattempo annullato o fallito (ad esempio un riferimento Multibanco pagato in ritardo). La nota lo spiega. Controlla il pagamento e le scorte, poi completa manualmente l'ordine o rimborsa il cliente. Le notifiche successive per questo pagamento non completano l'ordine alle tue spalle.

Canceled: Eupago ha segnalato il pagamento come annullato o scaduto, per il tentativo di pagamento corrente di un ordine in attesa.

Payment error: Eupago ha segnalato un errore per il tentativo di pagamento corrente di un ordine in attesa.

Se Eupago segnala un altro pagamento per un ordine già pagato (ad esempio è stato pagato anche un riferimento Multibanco precedente), l'ordine non cambia. Una nota ti chiede di verificare un eventuale 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.

Blocco pagamenti Eupago

La pagina dell'ordine mostra un blocco Eupago payment con ogni tentativo di pagamento del carrello: data, metodo, un badge Sandbox per i pagamenti sandbox, importo, entità e riferimento Multibanco o telefono mascherato MB WAY, ID transazione Eupago e stato. Mentre l'ordine è in Eupago payment on hold, il blocco mostra un avviso Manual review. Più sotto, Eupago notes elenca le note del modulo sull'ordine, dalla più recente.

Rimborsi

I rimborsi da PrestaShop non sono supportati. Rimborsa il cliente nel back office Eupago e aggiorna manualmente l'ordine in PrestaShop. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Eupago.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox Eupago Gateway è il primo blocco di Modules > Module Manager > VibeFox Eupago Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, 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 di essi ci sono la riga Product: presta-payment-eupago 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 modificare 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 che l'indirizzo del negozio è cambiato, o dopo aver liberato un posto dominio nel tuo account, clicca 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: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto 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. Il negozio 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 vengono influenzati: 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

Eupago non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la chiave API della modalità corrente sia impostata (Sandbox API Key in modalità sandbox, Live API Key in modalità live). La valuta del carrello deve essere EUR, e in Payment > Preferences il modulo deve essere consentito per l'euro, per il paese del cliente e per il gruppo del cliente. Con Multibanco, il totale dell'ordine deve essere compreso tra 1 € e 999.999,99 €.

Il pagamento è andato a buon fine, ma l'ordine resta in Awaiting Eupago payment oppure non è stato creato alcun ordine: la notifica di Eupago non arriva o viene rifiutata. Nel back office Eupago della modalità che stai usando, verifica che il Webhook 2.0 esista, che il suo URL sia esattamente quello mostrato in Webhook URL, che il metodo sia POST e che la cifratura sia attiva. Verifica che la sua chiave sia nel campo corrispondente (Sandbox Webhook Key o Live Webhook Key). Attiva Debug Log e controlla il campo Log nella pagina del modulo. Se una notifica non arriva mai, verifica il pagamento nel back office Eupago.

Il webhook risponde Invalid signature o Missing signature: la chiave del webhook nel modulo non corrisponde a quella del webhook, oppure il webhook non è cifrato né firmato. Copia di nuovo la chiave e tieni attiva la cifratura.

Il webhook risponde Webhook key not configured: nessuna chiave del webhook è impostata. Eupago ritenta 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 il pagamento è stato avviato. Una notifica sandbox non paga mai un pagamento live, e viceversa. Verifica che le chiavi sandbox e live non siano invertite.

Il webhook risponde Order not found: la notifica riguarda un carrello senza un pagamento Eupago di questo negozio, per esempio un pagamento effettuato da un altro negozio con lo stesso canale Eupago.

Il webhook risponde Busy or Retry: il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (ad esempio perché il modulo è disattivato). Eupago ritenta la notifica. Il motivo è nel registro.

Il callback legacy risponde Invalid API key: la chiave API inviata da Eupago non corrisponde a Live API Key né a Sandbox API Key. La stessa risposta compare se apri l'URL del webhook in un browser; è normale.

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 è in Eupago payment on hold dopo il pagamento: leggi le Eupago notes nel blocco Eupago payment. L'importo o la 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.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Eupago Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete Data on Uninstall è attivo, vengono rimosse le impostazioni del gateway, i record dei pagamenti Eupago di questo modulo e il registro. Se è disattivo, tutte le impostazioni e i record vengono conservati per una successiva reinstallazione. Gli stati d'ordine Awaiting Eupago payment e Eupago payment on hold vengono sempre conservati. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.

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