VibeFox ePay.bg 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: lev bulgaro (BGN), euro (EUR) o dollaro statunitense (USD). L'ordine viene addebitato nella sua valuta con 2 decimali. Per le altre valute il metodo di pagamento viene 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 inoltre inserire l'URL di notifica del tuo negozio nel profilo commerciante.

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

2. Fai clic su Activate. WooCommerce deve essere attivo.

3. Apri le impostazioni: WooCommerce > Settings > Payments > ePay.bg > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina dei plugin.

4. Inserisci la tua chiave di licenza VibeFox nel blocco della licenza in cima alla pagina e fai clic su Activate.

5. Inserisci il MIN e la chiave segreta di test e/o live (vedi Configurazione).

6. Copia l'URL di notifica mostrato nella sezione Payment notifications (IPN) nel campo URL for receiving notifications del profilo commerciante ePay.bg, sia nel profilo demo sia in quello live. Senza di esso gli ordini restano In attesa di pagamento.

7. Attiva Enable/Disable. Effettua un ordine di prova in modalità test, poi deseleziona Test Mode.

Configurazione

Tutte le impostazioni si trovano in una sola pagina: WooCommerce > Settings > Payments > ePay.bg. Sopra i campi la pagina mostra un errore quando la valuta del negozio non è BGN, EUR o USD, un avviso quando il gateway è attivo ma il MIN o la chiave segreta della modalità selezionata è vuoto (in tal caso viene nascosto al checkout e il salvataggio mostra lo stesso errore), e Test mode is on: payments go to demo.epay.bg and no real money is charged. finché la modalità test è attiva. Nell'elenco dei metodi di pagamento, ePay.bg è contrassegnato come da configurare finché non vengono inserite le credenziali della modalità selezionata.

Generale

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

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). Gli spazi e i ritorni a capo nelle chiavi segrete incollate vengono rimossi al salvataggio.

Test Mode: Enable test mode (use demo.epay.bg and the test credentials). Quando è attiva, i clienti vengono indirizzati all'ambiente demo di ePay.bg e le richieste sono firmate con le credenziali di test. Predefinito: attivata.

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.

Se aggiorni dalla versione 1.0, l'unico insieme di credenziali di quella versione viene spostato nei campi di test se la modalità test era attiva.

Notifiche di pagamento (IPN)

La notifica comunica al tuo negozio che una richiesta di pagamento è stata pagata, rifiutata o è scaduta. Questa sezione mostra l'URL di notifica, che ha questo aspetto: https://your-site/wc-api/epaybg_payment_callback/. Inseriscilo come URL for receiving notifications nel profilo commerciante ePay.bg, live e test. Gli ordini vengono segnati come pagati solo da queste notifiche firmate; il ritorno del cliente nel negozio non segna un ordine come pagato.

ePay.bg comunica questi risultati per ogni fattura:

Ogni notifica viene controllata con la chiave segreta della modalità selezionata. Le notifiche senza un checksum valido vengono rifiutate e ePay.bg continua a inviarle. Senza l'URL di notifica nel profilo commerciante, nessun ordine viene segnato come pagato.

Richiesta di pagamento

Invoice Prefix: solo cifre (fino a 10), poste davanti all'ID dell'ordine per formare il numero di fattura ePay.bg, per esempio 00001 + 123 = 00001123. Usa prefissi diversi per negozi diversi sullo stesso account ePay.bg. Gli altri caratteri vengono rimossi al salvataggio. Cambiare il prefisso in seguito è sicuro: gli ordini in attesa vengono trovati tramite la fattura salvata nell'ordine. Predefinito: 00001.

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

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

Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento riuscito. Lo stato viene impostato subito, senza un secondo cambio di stato.

Avanzate

Logging: Enable logging scrive le richieste di pagamento e le notifiche in WooCommerce > Status > Logs, origine wcp_epaybg_gateway, senza chiavi segrete né dati della carta. Predefinito: disattivato.

Delete Data on Uninstall: Remove all plugin data when uninstalled. Se selezionata, le impostazioni del gateway, i dati ePay.bg salvati negli ordini e i registri del plugin vengono eliminati quando il plugin viene disinstallato. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita ePay.bg) ed effettua l'ordine. Il cliente vede Redirecting to ePay.bg for payment... e viene indirizzato a ePay.bg con una richiesta di pagamento firmata per il totale dell'ordine nella valuta dell'ordine, con il numero di fattura e il tempo di scadenza. La pagina ha anche un pulsante Pay via ePay.bg nel caso in cui il reindirizzamento non parta, e un pulsante Cancel order. Su ePay.bg il cliente paga con una carta bancaria o con un account ePay.bg.

Dopo il pagamento, il cliente torna alla pagina di ordine ricevuto del tuo negozio. L'ordine viene segnato come pagato solo quando arriva la notifica firmata di ePay.bg. Il carrello viene svuotato solo nella pagina di ordine ricevuto.

Se il cliente annulla su ePay.bg, l'ordine viene annullato nel modo standard di WooCommerce e il carrello viene conservato, così il cliente può scegliere un altro metodo di pagamento.

Se l'ordine non può essere pagato con ePay.bg, il cliente vede un breve messaggio, per esempio ePay.bg payments are temporarily unavailable. Please choose another payment method., oppure l'indicazione che ePay.bg non accetta pagamenti nella valuta dell'ordine.

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).

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

Ordini

Stati dell'ordine

Pending payment: il cliente è stato indirizzato a ePay.bg e non ha ancora pagato, oppure la notifica non è ancora arrivata. La nota dell'ordine dice Awaiting ePay.bg payment.

Processing, Completed or On Hold: il pagamento è stato confermato. Lo stato segue l'impostazione Order Status After Payment. La nota dell'ordine mostra il numero di fattura, la data del pagamento, lo STAN e il codice BORICA. L'ID transazione è lo STAN (o il numero di fattura se non c'è lo STAN).

On hold after payment: il pagamento è arrivato, ma non per ciò che l'ordine indica adesso: il totale o la valuta sono stati modificati dopo la richiesta di pagamento, la richiesta è stata fatta nell'altra modalità o il gateway è stato poi commutato tra test e live, il metodo di pagamento dell'ordine è stato cambiato, oppure l'ordine era stato annullato in precedenza. La nota dell'ordine ne spiega il motivo. Controlla il pagamento nel pannello commerciante di ePay.bg e completa o rimborsa l'ordine manualmente.

Cancelled: ePay.bg ha segnalato la richiesta di pagamento come rifiutata o scaduta, oppure il cliente ha annullato su ePay.bg. WooCommerce ripristina le scorte. Un ordine annullato non può essere pagato di nuovo, perché il numero di fattura ePay.bg è il prefisso più l'ID dell'ordine. Il cliente effettua un nuovo ordine.

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

Rimborsi

I rimborsi da WooCommerce non sono disponibili, perché la WEB API di ePay.bg non ha una chiamata di rimborso. Rimborsa il pagamento nel pannello commerciante di ePay.bg e registra il rimborso manualmente in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > ePay.bg. 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 ricontrollare 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 posto di dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, ePay.bg non viene mostrato ai clienti al checkout. Se un pagamento viene comunque avviato, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio che hanno effettuato l'accesso vedono comunque il metodo di pagamento, contrassegnato (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina dei plugin e nelle pagine di WooCommerce. 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 un rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

ePay.bg non compare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivato, che il MIN e la chiave segreta della modalità selezionata siano impostati e che la valuta del negozio sia BGN, EUR o USD. La pagina delle impostazioni mostra un avviso in ciascuno di questi casi.

Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: l'ordine viene segnato come pagato solo dalla notifica di ePay.bg. Controlla che l'URL di notifica sia inserito nel profilo commerciante ePay.bg della modalità che usi (demo o live) e che la chiave segreta della modalità attiva sia corretta. Attiva Logging e guarda WooCommerce > Status > Logs, origine wcp_epaybg_gateway.

La notifica risponde ERR=Not valid CHECKSUM: la chiave segreta nelle impostazioni non corrisponde al profilo commerciante che ha inviato la notifica. Le notifiche vengono controllate con la chiave della modalità selezionata in quel momento e poi con la chiave dell'altra modalità, così le richieste di pagamento fatte prima del cambio di modalità vengono comunque accettate. ePay.bg continua a riprovare, quindi l'ordine viene aggiornato una volta corretta la chiave.

La notifica risponde ERR=Not configured: la chiave segreta della modalità selezionata è vuota. Inseriscila.

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

La notifica risponde STATUS=ERR: un errore temporaneo, per esempio due notifiche per lo stesso ordine nello stesso momento. ePay.bg invia di nuovo la notifica.

L'ordine è In sospeso dopo il pagamento: leggi la nota dell'ordine. Il totale o la valuta sono cambiati dopo la richiesta di pagamento, la richiesta è stata fatta nell'altra modalità o la modalità è stata poi commutata, il metodo di pagamento è cambiato oppure l'ordine era stato annullato. Controlla il pagamento nel pannello commerciante di ePay.bg.

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

Il blocco della 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, il readme cita il filtro epay_bp_form_fields, per esempio per usare la pagina diretta della carta (PAGE=credit_paydirect).

Disinstallazione

Disattivare il plugin conserva 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, i dati ePay.bg salvati negli ordini e i registri vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le loro note di pagamento e gli ID transazione.

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