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

Account EveryPay: ti servono il nome utente API, il segreto API e il nome dell'account di elaborazione del tuo negozio. Si trovano nell'EveryPay Merchant Portal, nelle impostazioni del tuo negozio: il portale demo per la modalità test, il portale live per i pagamenti reali. Gli ambienti di test e live hanno credenziali separate. Inoltre devi 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 i carrelli in quella valuta.

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 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 EveryPay Payment nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la 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. Inserisci il nome utente API di test, il segreto API di test e il nome dell'account di elaborazione dell'EveryPay Merchant Portal demo. Lascia attivo Test Mode.

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

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

All'installazione, il modulo crea lo stato dell'ordine EveryPay 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.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox EveryPay Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Modalità test attiva: i pagamenti vanno all'ambiente demo di EveryPay, non viene addebitato denaro reale. finché la modalità test è attiva. Ti avvisa quando il metodo di pagamento è attivato ma mancano il nome utente API, il segreto API o l'account di elaborazione della modalità corrente (in tal caso il metodo di pagamento viene nascosto al checkout), e quando l'account di elaborazione addebita una valuta diversa dalla valuta predefinita del negozio. Gli spazi e le interruzioni di riga incollati insieme alle credenziali vengono rimossi al salvataggio.

EveryPay

Enable/Disable: Enable EveryPay payment gateway attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. 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. La sezione contiene link a entrambi i portali.

Test Mode: quando è attivo, i pagamenti vanno all'ambiente demo di EveryPay con le credenziali di test. Non viene addebitato denaro reale. Predefinito: on. Mentre è attivo, i clienti vedono MODALITÀ TEST: ambiente demo di EveryPay, non viene addebitato denaro reale. sotto il metodo di pagamento.

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.

I segreti salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Salvato — lascia vuoto per mantenerlo. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved API secrets: seleziona un segreto e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Processing Account Name: l'account di elaborazione EveryPay, per esempio EUR3D1. L'account definisce la valuta addebitata: il metodo di pagamento viene offerto solo per i carrelli 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 creati anche se il cliente chiude il browser. Copia l'URL mostrato in Callback notification URL nel campo Callback notification URL del tuo negozio nell'EveryPay Merchant Portal, sia demo sia live. Con URL SEO-friendly ha questo aspetto: https://your-shop/module/wcp_everypay_payment/callback. Copia l'URL esattamente come appare nelle impostazioni. 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 modulo chiede all'API EveryPay lo stato del pagamento con le credenziali dell'ambiente in cui il pagamento è stato creato, e verifica che la risposta appartenga a questo carrello. I callback per un pagamento che il tuo negozio non ha creato vengono rifiutati senza richieste a EveryPay. Senza il callback, l'ordine viene creato quando il cliente torna sul negozio dopo aver pagato, oppure quando EveryPay ripete il callback.

Avanzate

Debug log: registra gli eventi di pagamento in logs/wc_evp_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche quando è disattivato. Segreti API, dati della carta ed e-mail dei clienti non vengono mai registrati. Predefinito: off.

Log: mostra la dimensione e le ultime voci del registro. Fai clic su Clear log per svuotarlo.

Uninstall: elimina le impostazioni del gateway e i registri quando il modulo viene disinstallato. I dati di pagamento EveryPay degli ordini vengono sempre conservati. Predefinito: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita EveryPay) e conferma. Il modulo crea un pagamento EveryPay una tantum per il totale del carrello nella valuta del carrello, con l'e-mail e l'indirizzo di fatturazione del cliente, e invia il cliente alla pagina di pagamento EveryPay. La lingua della pagina segue la lingua del negozio (inglese, estone, russo, lettone, lituano, finlandese o tedesco; altrimenti inglese). Lì il cliente paga con uno dei metodi attivati per il tuo account EveryPay. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna sul tuo negozio. L'ordine viene segnato come pagato solo quando EveryPay lo conferma: il modulo chiede all'API EveryPay lo stato del pagamento al ritorno e nel callback. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine. Se EveryPay sta ancora elaborando il pagamento, o la sua API non è raggiungibile in quel momento, compare una pagina Payment confirmation con il messaggio Il tuo pagamento è in fase di conferma da parte di EveryPay. Riceverai un'e-mail non appena l'ordine sarà confermato. e un pulsante Check again; il callback crea l'ordine appena EveryPay conferma il pagamento.

Se il pagamento non è riuscito, il cliente torna al checkout con il messaggio Il tuo pagamento EveryPay non è andato a buon fine. Riprova o scegli un altro metodo di pagamento. Se il cliente ha lasciato la pagina di pagamento senza pagare, il messaggio è Il pagamento EveryPay non è stato completato. Puoi riprovare o scegliere un altro metodo di pagamento. Il carrello viene conservato. Ogni nuovo tentativo crea un nuovo pagamento EveryPay; i tentativi precedenti vengono ricordati, quindi un pagamento fatto con un link vecchio viene comunque riconosciuto.

Se EveryPay non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, per esempio EveryPay non è temporaneamente disponibile. Riprova tra poco o scegli un altro metodo di pagamento. I dettagli sono nel registro.

Il callback funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione geografica del tuo negozio.

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

Ordini

Stati dell'ordine

No order yet: il cliente è stato inviato a EveryPay e non ha pagato, il pagamento non è riuscito o è stato abbandonato, oppure EveryPay non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted: EveryPay ha comunicato che il pagamento è regolato o autorizzato. Il pagamento viene registrato con il riferimento di pagamento EveryPay come ID transazione, e una nota mostra importo, valuta e riferimento. 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 il pagamento viene regolato più tardi, una nota lo segnala.

EveryPay payment on hold: il pagamento richiede una verifica manuale. L'importo o la valuta pagati non corrispondono al carrello (per esempio, il carrello è stato modificato dopo l'avvio del pagamento), l'ordine era stato annullato prima dell'arrivo del pagamento, oppure l'ordine ora 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 poi evadi o rimborsa manualmente. I callback successivi per questo pagamento non completano l'ordine automaticamente.

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.

Blocco pagamento EveryPay

La pagina dell'ordine mostra un blocco EveryPay payment con ogni tentativo di pagamento EveryPay dell'ordine: data, riferimento di pagamento (con un badge Test mode per i pagamenti di test), riferimento dell'ordine, importo, stato EveryPay e risultato. Sotto si trovano le EveryPay notes dell'ordine, dalla più recente.

Check EveryPay payment status: il pulsante nel blocco verifica con l'API ogni pagamento EveryPay dell'ordine, dal più recente al più vecchio, applica il risultato come descritto sopra e aggiunge una nota con lo stato di ciascun pagamento. Il risultato viene mostrato nel blocco. Serve il permesso di modificare gli ordini; l'accesso alle pagine dei moduli non è necessario. Usalo quando un callback non è mai arrivato, per esempio per vedere un'acquisizione o un rimborso successivo.

Rimborsi

I rimborsi da PrestaShop non sono supportati. Effettua il rimborso nell'EveryPay Merchant Portal, poi aggiorna lo stato dell'ordine in PrestaShop. Quando EveryPay comunica che un pagamento è stato rimborsato o stornato, il modulo aggiunge solo una nota all'ordine; lo stato dell'ordine non cambia. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite EveryPay.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox EveryPay Payment è il primo blocco di Modules > Module Manager > VibeFox EveryPay Payment > 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 si trovano la riga Product: presta-payment-everypay 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 aver cambiato l'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 solo dominio: quello 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, EveryPay non viene mostrato ai clienti al checkout. Se un pagamento viene avviato comunque, il cliente vede Questo metodo di pagamento non è disponibile. Scegline un altro. Lo storefront di 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 sono interessati: i pagamenti già avviati vengono comunque confermati e il controllo dello stato funziona.

Quando una licenza scade, il modulo continua a funzionare, ma gli aggiornamenti e l'assistenza richiedono il 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 a settimana. Non serve alcuna cron job. La disinstallazione o il ripristino del modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

EveryPay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che il nome utente API, il segreto API e il Processing Account Name della modalità corrente siano impostati e che la valuta del carrello sia quella dell'account di elaborazione. In questi casi la pagina delle impostazioni mostra un avviso. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il Paese del cliente e il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: il callback non funziona. Verifica che l'URL di callback delle impostazioni sia impostato come Callback notification URL nel Merchant Portal della modalità che usi (demo o live). L'ordine viene creato anche quando il cliente torna sul negozio dopo il pagamento. Controlla il campo Log nella pagina del modulo: gli errori vengono sempre registrati.

Il callback risponde Unknown payment, Unknown payment reference o Payment does not belong to this order: il pagamento non è stato creato da questo negozio o da questo carrello, oppure la risposta di EveryPay non corrisponde. Non viene cambiato nulla.

Il callback risponde Not configured: mancano le credenziali dell'ambiente in cui il pagamento è stato creato, 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, Busy, please retry o Order could not be created: non è stato possibile raggiungere l'API EveryPay, un'altra richiesta stava creando l'ordine nello stesso momento, oppure l'ordine non è stato creato (per esempio perché il modulo è disattivato). EveryPay ripete il callback. Il motivo è nel registro.

Il cliente vede «EveryPay non è temporaneamente disponibile»: EveryPay ha rifiutato le credenziali oppure non è stata raggiunta. Controlla il nome utente API e il segreto API della modalità corrente.

Il cliente vede «Questo metodo di pagamento non supporta la valuta dell'ordine»: la valuta del carrello è diversa da quella dell'account di elaborazione.

Il cliente resta sulla pagina Payment confirmation: EveryPay non ha ancora completato il pagamento. L'ordine viene creato dal callback oppure quando il cliente fa clic su Check again dopo che EveryPay ha confermato il pagamento.

L'ordine è EveryPay payment on hold: leggi le EveryPay notes nel blocco dell'ordine. L'importo o la valuta erano diversi, oppure l'ordine era stato annullato prima dell'arrivo del pagamento. Controlla il pagamento nel Merchant Portal e poi evadi o rimborsa manualmente.

Per gli sviluppatori, il README del modulo elenca gli hook actionWcpEverypayOneoffRequest (modifica della richiesta di pagamento) e actionWcpEverypayLocale (modifica della lingua della pagina di pagamento).

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox EveryPay Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Uninstall (elimina le impostazioni del gateway e i registri) è attivo nelle impostazioni, vengono rimosse le impostazioni del gateway e il registro. Se è disattivato, tutte le impostazioni vengono conservate per una reinstallazione successiva. I dati di pagamento EveryPay degli ordini e lo stato dell'ordine EveryPay payment on hold vengono sempre conservati. Gli ordini esistenti mantengono le loro note di pagamento e gli ID di transazione.

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