VibeFox ePay.bg for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP più vecchie.

Valuta: lev bulgaro (BGN), euro (EUR) o dollaro statunitense (USD). Il carrello viene addebitato nella propria valuta con 2 decimali. Per i carrelli in altre valute il metodo di pagamento è nascosto al checkout.

Account ePay.bg: ti servono il numero cliente (MIN) e la chiave segreta del tuo profilo commerciante ePay.bg: quelli live da www.epay.bg, quelli di test da demo.epay.bg (un account di test si registra separatamente). Devi anche inserire nel profilo commerciante l'URL di notifica del tuo negozio.

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 più tardi VibeFox ePay.bg Gateway 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 il MIN e la chiave segreta di test e/o live (vedi Configurazione).

5. Copia l'URL mostrato nella sezione Payment notifications (IPN) nel campo URL for receiving notifications del profilo commerciante ePay.bg, sia in quello demo sia in quello live. Senza di esso non viene creato alcun ordine.

6. Attiva Enable/Disable e clicca su Save. Effettua un ordine di prova in modalità test, poi disattiva Test Mode.

All'installazione il modulo crea lo stato ordine ePay.bg payment on hold. PrestaShop offre il 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 ePay.bg Gateway > Configure. Ogni pulsante Save salva l'intera pagina. Sopra i campi la pagina mostra un errore se la valuta predefinita del negozio non è BGN, EUR o USD, un avviso se il gateway è attivo ma il MIN o la chiave segreta della modalità selezionata sono vuoti (in quel caso è nascosto al checkout, e al salvataggio compare lo stesso avviso), e Test mode is on: payments go to demo.epay.bg and no real money is charged. finché la modalità test è attiva.

ePay.bg

Enable/Disable: Enable ePay.bg Payment Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: ePay.bg. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via ePay.bg with a bank card or your ePay.bg account.

Account ePay.bg

Il numero cliente (MIN) e la chiave segreta sono mostrati nel tuo profilo commerciante su www.epay.bg (live) e demo.epay.bg (account di test, registrato separatamente).

Test Mode: attiva la modalità test. I clienti vengono inviati all'ambiente demo di ePay.bg e le richieste sono firmate con le credenziali di test. Predefinito: attivo.

Test Merchant ID (MIN): il numero cliente (MIN) del tuo account commerciante demo.epay.bg.

Test Secret Key: la chiave segreta del tuo account commerciante demo.epay.bg (64 caratteri).

Live Merchant ID (MIN): il numero cliente (MIN) del tuo account commerciante www.epay.bg.

Live Secret Key: la chiave segreta del tuo account commerciante www.epay.bg (64 caratteri), usata per la firma HMAC-SHA1.

Le chiavi segrete salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo. Spazi e interruzioni di riga nelle chiavi incollate vengono rimossi al salvataggio.

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

Payment notifications (IPN)

La notifica comunica al tuo negozio che una richiesta di pagamento è stata pagata, rifiutata o è scaduta. Il campo Notification URL mostra l'URL da inserire come URL for receiving notifications nel profilo commerciante ePay.bg, live e test. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_epaybg_gateway/notify, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni. Gli ordini vengono creati solo da queste notifiche firmate; il ritorno del cliente nel negozio non crea né paga un ordine.

ePay.bg comunica questi esiti per ogni fattura:

Le notifiche senza un checksum valido vengono rifiutate, e ePay.bg continua a inviarle. Il checksum viene verificato con la chiave segreta di ogni modalità che ne ha una, quindi i pagamenti avviati prima del passaggio tra test e live vengono comunque confermati. Un pagamento deve arrivare nella modalità in cui è stata fatta la richiesta; altrimenti l'ordine passa a ePay.bg payment on hold. Senza l'URL di notifica nel profilo commerciante, non viene creato alcun ordine.

Payment request

Invoice Prefix: solo cifre (fino a 10), anteposte all'ID del carrello per formare il numero di fattura ePay.bg, per esempio 00001 + 123 = 00001123. Usa prefissi diversi per negozi diversi su un unico account ePay.bg. Gli altri caratteri vengono rimossi al salvataggio, con un avviso. Cambiare il prefisso in seguito non causa problemi: le richieste di pagamento aperte vengono ritrovate tramite la fattura salvata per ciascuna. Predefinito: 00001.

Expiration Time: il tempo dopo il quale una richiesta di pagamento non pagata scade; ePay.bg la segnala come scaduta e non viene creato alcun ordine. Scegli 1, 3, 6, 12, 24, 48 o 72 ore. L'orario viene inviato nell'ora bulgara, qualunque sia il fuso orario del tuo negozio. Predefinito: 24 ore.

Language: la lingua della pagina di pagamento ePay.bg, inglese o bulgaro. Predefinito: inglese.

Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento riuscito.

Advanced

Logging: scrive le richieste di pagamento e le notifiche in logs/epay_bp_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi segrete e dati della carta non vengono registrati. Predefinito: disattivato. Gli errori vengono sempre registrati, anche quando è disattivato.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il registro. I record dei pagamenti ePay.bg, lo stato ordine ePay.bg payment on hold e gli ordini restano sempre. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita ePay.bg) e conferma. Il cliente vede Redirecting to ePay.bg for payment... ed è indirizzato a ePay.bg con una richiesta di pagamento firmata per il totale del carrello nella valuta del carrello, con il numero di fattura e il tempo di scadenza. Su ePay.bg il pagamento compare come Cart e con il numero del carrello. La pagina include anche un pulsante Pay via ePay.bg nel caso il reindirizzamento non parta, e un pulsante Cancel. Su ePay.bg il cliente paga con una carta bancaria o con un account ePay.bg. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene creato solo quando arriva la notifica firmata di ePay.bg. Se è già arrivata, il cliente vede la pagina standard di conferma dell'ordine. Se no, una pagina Payment confirmation mostra Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. con i pulsanti Check again e Back to checkout.

Se il cliente annulla su ePay.bg, torna al checkout con il messaggio The ePay.bg payment was cancelled. You can try again or choose another payment method. Se ePay.bg ha segnalato la richiesta come rifiutata o scaduta, il messaggio è The payment was not completed. You can try again or choose another payment method. Il carrello viene conservato. Un nuovo tentativo per lo stesso carrello usa lo stesso numero di fattura.

Se il carrello non può essere pagato con ePay.bg, il cliente resta al checkout con un breve messaggio, per esempio ePay.bg payments are temporarily unavailable. Please choose another payment method. oppure che ePay.bg non accetta pagamenti nella valuta del carrello.

La notifica funziona anche mentre il negozio è in modalità manutenzione e non viene bloccata dalla restrizione per paese del tuo negozio.

Il modulo accetta solo pagamenti singoli su ePay.bg. Non prevede rimborsi da PrestaShop, carte salvate, abbonamenti o pagamenti ricorrenti, né codici di pagamento in contanti EasyPay o B-Pay.

Ordini

Stati dell'ordine

No order yet: il cliente è stato inviato a ePay.bg e non ha pagato, la notifica non è ancora arrivata oppure ePay.bg ha segnalato la richiesta come rifiutata o scaduta. Esiste solo il carrello.

Payment accepted, Delivered or ePay.bg payment on hold: il pagamento è stato confermato. Lo stato segue Order Status After Payment. Il pagamento viene registrato con lo STAN come ID transazione (o con il numero di fattura se non c'è lo STAN), e una nota mostra il numero di fattura, la data del pagamento, lo STAN e il codice BORICA.

ePay.bg payment on hold after payment: il pagamento è arrivato, ma non corrisponde a quanto indica ora il carrello: il totale o la valuta del carrello sono stati modificati dopo la richiesta di pagamento, oppure la notifica è arrivata in una modalità (test o live) diversa da quella della richiesta. Il pagamento non viene registrato come pagato. Lo stesso accade quando il carrello ha già un ordine non pagato, per esempio uno annullato o uno effettuato con un altro metodo di pagamento. La nota spiega il motivo. Controlla il pagamento nel pannello commerciante di ePay.bg, poi evadi o rimborsa manualmente l'ordine.

Se arriva un pagamento per un ordine già pagato o rimborsato, lo stato non cambia e una nota ti chiede di verificare un doppio pagamento nel pannello commerciante di ePay.bg. Un avviso tardivo di rifiuto o scadenza non modifica mai un ordine pagato.

Blocco pagamento ePay.bg

La pagina dell'ordine mostra un blocco ePay.bg payment con la fattura, l'importo e la valuta richiesti, l'esito della notifica, la data del pagamento, lo STAN, il codice BORICA, un badge Test mode per i pagamenti di prova e le ePay.bg notes dell'ordine.

Rimborsi

I rimborsi da PrestaShop non sono disponibili, perché l'API WEB di ePay.bg non ha una chiamata di rimborso. Rimborsa il pagamento nel pannello commerciante di ePay.bg e aggiorna manualmente l'ordine in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox ePay.bg Gateway è il primo blocco di Modules > Module Manager > VibeFox ePay.bg Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca 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 ci sono la riga Product: presta-payment-epaybg 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 un cambio dell'indirizzo del negozio, o dopo aver liberato uno slot di 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 slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, ePay.bg non viene mostrato ai clienti al checkout. Se comunque viene avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. La vetrina di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento è nascosto anche per 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.

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

ePay.bg non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che MIN e chiave segreta della modalità selezionata siano impostati e che la valuta del carrello sia BGN, EUR o USD. La pagina delle impostazioni mostra un avviso quando le credenziali mancano. 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: l'ordine viene creato solo dalla notifica di ePay.bg. Verifica che l'URL di notifica sia inserito nel profilo commerciante ePay.bg della modalità che usi (demo o live), esattamente come mostrato in Notification URL, e che la chiave segreta di quella modalità sia corretta. Controlla il campo Log nella pagina del modulo; attiva Logging per vedere ogni notifica.

La notifica risponde ERR=Not valid CHECKSUM: nessuna chiave segreta salvata corrisponde al profilo commerciante che ha inviato la notifica. ePay.bg continua a riprovare, quindi l'ordine viene creato appena la chiave è corretta.

La notifica risponde ERR=Not configured: nessuna chiave segreta è salvata. Inseriscila.

La notifica risponde STATUS=NO per una fattura: la fattura non è stata emessa da questo negozio, per esempio da un altro negozio sullo stesso account ePay.bg. Assegna a ogni negozio un proprio Invoice Prefix.

La notifica risponde STATUS=ERR: un errore temporaneo, per esempio due notifiche per lo stesso carrello nello stesso momento, oppure l'ordine non ha potuto essere creato (per esempio perché il modulo è disattivato). ePay.bg invia di nuovo la notifica. Il motivo è nel registro.

L'URL di notifica mostra ERR=Method not allowed in the browser: è normale. L'URL accetta solo richieste da ePay.bg.

L'ordine è ePay.bg payment on hold dopo il pagamento: leggi le note nel blocco ePay.bg payment (vedi Stati dell'ordine), controlla il pagamento nel pannello commerciante di ePay.bg, poi evadi l'ordine o rimborsa il pagamento lì.

Il prefisso della fattura è stato modificato al salvataggio: il prefisso può contenere solo cifre, fino a 10. Gli altri caratteri vengono rimossi.

Per gli sviluppatori, il readme cita l'hook actionEpayBpFormFields (il filtro epay_bp_form_fields della versione WooCommerce), per esempio per usare la pagina diretta della carta (PAGE=credit_paydirect).

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox ePay.bg Gateway e scegli Uninstall. La chiave di licenza e lo stato di licenza di questo modulo vengono sempre rimossi. Se Delete Data on Uninstall è attivo, vengono rimosse le impostazioni del gateway e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I record dei pagamenti ePay.bg e lo stato ordine ePay.bg payment on hold restano sempre, quindi un pagamento avviato prima di una reinstallazione viene comunque confermato. Gli ordini esistenti conservano le proprie note di pagamento e gli ID transazione.

ePay.bg è un marchio di proprietà del rispettivo titolare. Questo modulo non è affiliato a ePay.bg né approvato da ePay.bg.