VibeFox Barion for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo rifiuta di installarsi su versioni di PHP precedenti.

Negozio Barion: ti servono la POSKey (chiave segreta) del tuo negozio e l'indirizzo e-mail del wallet Barion che riceve i pagamenti. Entrambi si trovano nel portale Barion: secure.barion.com per il live, secure.test.barion.com per il test, in My stores e nel tuo negozio. Le credenziali di test e quelle live sono diverse.

Valuta: la valuta del carrello deve essere HUF, EUR, USD o CZK. Per le altre valute il metodo di pagamento è nascosto al checkout.

Negozio raggiungibile: Barion richiama il tuo negozio dopo ogni pagamento, quindi il sito deve essere raggiungibile da internet, senza firewall o autenticazione di base davanti.

Chiave di licenza VibeFox: si acquista 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 Barion Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua 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 la POSKey di test e l'e-mail del wallet di test, lascia attivo Test Mode, attiva Enable/Disable e fai clic su Save. Effettua un ordine di prova.

5. Quando tutto funziona, inserisci le credenziali live e disattiva Test Mode.

L'URL di callback viene inviato a Barion automaticamente con ogni pagamento. Non c'è nulla da configurare nel portale Barion.

All'installazione il modulo crea due stati dell'ordine, Awaiting Barion payment e Barion 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 Barion Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa quando la modalità corrente non ha una POSKey o un'e-mail del beneficiario (il metodo di pagamento viene allora nascosto al checkout) e quando la valuta predefinita del tuo negozio non è supportata da Barion, con l'elenco delle valute supportate. Mentre la modalità test è attiva, mostra La modalità test è attiva: i pagamenti vanno alla sandbox di Barion (api.test.barion.com), non viene addebitato alcun importo reale.

Barion

Enable/Disable: Enable Barion Payment 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: Barion. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay.

Credenziali del negozio Barion

Recupera la POSKey e l'e-mail del wallet nel portale Barion: secure.barion.com (live) oppure secure.test.barion.com (test), My stores, il tuo negozio. La modalità test usa solo le credenziali di test, la modalità live solo quelle live.

Test Mode: usa le credenziali di test indicate sotto e la sandbox di Barion (api.test.barion.com). Non viene addebitato alcun importo reale. Predefinito: attivo. Disattivalo per accettare pagamenti reali. Mentre è attivo, i clienti vedono Modalità test: non viene effettuato alcun pagamento reale. sotto il metodo di pagamento.

Test POSKey: la chiave segreta (POSKey) del tuo negozio nel sistema di test di Barion (secure.test.barion.com, My stores).

Test Payee Email: l'indirizzo e-mail del tuo wallet di test Barion che riceve i pagamenti di prova.

Live POSKey: la chiave segreta (POSKey) del tuo negozio nel sistema live di Barion (secure.barion.com, My stores).

Live Payee Email: l'indirizzo e-mail del tuo wallet Barion che riceve i pagamenti.

Le POSKey salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Salvata — lascia vuoto per mantenerla. Inserisci un nuovo valore solo se vuoi cambiarla.

Clear saved POSKeys: seleziona una chiave e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Callback URL: l'indirizzo che Barion richiama dopo ogni pagamento, per esempio https://your-shop/module/wcp_barion_gateway/callback con URL semplificati, eventualmente con un codice lingua come /en/. Viene inviato a Barion con ogni pagamento, quindi non c'è nulla da configurare. Deve solo essere raggiungibile da internet.

Ordini

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

I pagamenti ancora in elaborazione presso Barion restano in Awaiting Barion payment. Le differenze di importo o di valuta vanno sempre in Barion payment on hold.

Avanzate

Logging: scrive le richieste e i callback di Barion in logs/barion_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Le chiavi segrete e le e-mail dei wallet non vengono registrate. Predefinito: disattivato. Mentre è disattivato non viene scritto nulla, nemmeno gli errori.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del modulo e il registro. Gli ordini, i loro dati di pagamento Barion e gli stati dell'ordine vengono sempre conservati. Predefinito: disattivato.

Checkout

Al checkout il cliente sceglie il metodo di pagamento (per impostazione predefinita Barion) e vede la nota Verrai reindirizzato alla pagina di pagamento sicura di Barion. Dopo la conferma, il modulo avvia un pagamento Barion per il totale del carrello nella valuta del carrello e invia il cliente alla pagina di pagamento di Barion. Prodotti, spedizione, confezione regalo e imposte sono elencati nel pagamento, il pagamento compare come Cart con il numero del carrello, l'e-mail del cliente viene passata come suggerimento e la lingua della pagina segue quella del carrello, dove Barion la supporta. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna al tuo negozio, e Barion richiama anche l'URL di callback. Nessuna delle due richieste segna nulla come pagato da sola: il modulo chiede a Barion lo stato del pagamento con la POSKey della modalità in cui è stato avviato. L'ordine viene segnato come pagato solo dopo la conferma di Barion, e solo se importo e valuta corrispondono al carrello. Il link di ritorno contiene la chiave sicura del carrello, e vengono verificati solo i pagamenti avviati per quel carrello.

Se il pagamento è riuscito, l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine con Il tuo pagamento con Barion è stato ricevuto. Se il pagamento è ancora in elaborazione presso Barion, l'ordine viene creato in Awaiting Barion payment e la pagina mostra Il tuo pagamento è in fase di conferma da parte di Barion. Riceverai un'e-mail non appena sarà confermato. Se tale pagamento viene successivamente annullato, scade o fallisce presso Barion, la pagina mostra Il tuo pagamento con Barion non è stato completato. Contattaci per questo ordine. Se Barion non è raggiungibile quando il cliente torna, una pagina Conferma del pagamento mostra lo stesso testo «in fase di conferma» e un pulsante Check again; il callback crea l'ordine non appena Barion conferma il pagamento.

Se il pagamento non è stato completato (annullato, scaduto o fallito), non viene creato alcun ordine, il carrello viene conservato e il cliente torna al checkout con Il pagamento non è stato completato. Riprova. Il cliente può riprovare. Ogni tentativo viene memorizzato, quindi un pagamento tardivo di un tentativo precedente crea comunque l'ordine, e un tentativo precedente che scade non annulla un ordine di un tentativo più recente.

Se il pagamento non può essere avviato, il cliente resta al checkout con un breve messaggio: Impossibile avviare il pagamento con Barion. Riprova o scegli un altro metodo di pagamento., Barion non supporta i pagamenti in valuta del carrello, oppure Barion non può elaborare un ordine con totale zero. I dettagli vengono scritti nel registro se Logging è attivo.

Il callback funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo gestisce solo pagamenti immediati. Non gestisce pagamenti con riserva o acquisizione differita, abbonamenti o pagamenti ricorrenti, carte salvate, Barion Pixel né dati aggiuntivi 3-D Secure; Barion gestisce il 3-D Secure sulla sua pagina di pagamento.

Ordini e rimborsi

Stati dell'ordine

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

Awaiting Barion payment: Barion segnala il pagamento come ancora in elaborazione. Una nota mostra il PaymentId di Barion, l'importo e, in modalità test, (test mode). L'ordine passa a «Pagamento accettato» quando Barion conferma il pagamento.

Payment accepted or Delivered: Barion ha confermato il pagamento. Lo stato segue Order Status After Payment. Il pagamento viene registrato con l'ID transazione di Barion e una nota mostra l'importo, il PaymentId e la transazione.

Barion payment on hold: Barion ha comunicato un importo o una valuta diversi dal totale dell'ordine, per esempio perché il carrello è stato modificato dopo l'avvio del pagamento. La nota mostra entrambi gli importi. Controlla il pagamento nel portale Barion, poi evadi l'ordine oppure rimborsa il pagamento nel portale Barion.

Canceled: l'ultimo tentativo di pagamento di un ordine in attesa è stato annullato o è scaduto presso Barion.

Payment error: l'ultimo tentativo di pagamento di un ordine in attesa è fallito.

Refunded: il pagamento è stato rimborsato integralmente tramite il modulo.

Se un pagamento dell'ordine riesce ancora dopo che l'ordine è stato annullato o è fallito, l'ordine diventa pagato. Un ordine pagato o rimborsato non viene mai modificato da un callback successivo. Se un altro pagamento riesce per un ordine pagato, una nota ti chiede di verificarlo nel portale Barion e di rimborsarlo se è un duplicato. Le note sono messaggi privati nella pagina dell'ordine.

Blocco pagamento Barion

La pagina dell'ordine mostra un blocco Barion payment con il PaymentId, la transazione Barion, lo stato del pagamento, l'importo pagato e rimborsato, un badge Test mode per i pagamenti di test e la cronologia dei rimborsi.

Rimborsi

Nel blocco Barion payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Barion. Conferma la domanda Rimborsare questo importo tramite Barion? Questa operazione non può essere annullata. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini. Il motivo viene inviato a Barion come commento. I rimborsi in HUF devono essere importi interi. Il rimborso viene inviato nella modalità (test o live) in cui è stato effettuato il pagamento, quindi la POSKey di quella modalità deve essere impostata. Se Barion non accetta o non conferma il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e alle note, con la transazione e lo stato di Barion. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.

I rimborsi sono disponibili una volta che Barion ha confermato il pagamento e l'ordine è pagato tramite Barion. Un pagamento con differenza di importo o di valuta non può essere rimborsato da PrestaShop; rimborsalo nel portale Barion. Il modulo non crea note di credito, e i pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Barion.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Barion Gateway è il primo blocco di Modules > Module Manager > VibeFox Barion Gateway > Configure, sopra le impostazioni. Incolla 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 di essi ci sono la riga Product: presta-payment-barion 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 incluse le lingue inglese e russa).

Se la chiave non viene accettata, il blocco spiega il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on con 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, Barion 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. La vetrina di PrestaShop non sa che hai effettuato l'accesso 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 i rimborsi funzionano.

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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Barion non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità corrente abbia una POSKey e un'e-mail del beneficiario (la pagina delle impostazioni mostra un avviso se ne manca una) e che la valuta del carrello sia HUF, EUR, USD o CZK. 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 quando Barion richiama l'URL di callback o quando il cliente torna al tuo negozio. Assicurati che il sito sia raggiungibile da internet (nessun firewall o autenticazione di base davanti all'URL di callback). Verifica che la POSKey della modalità in cui è stato effettuato il pagamento sia corretta, perché il modulo la usa per chiedere a Barion lo stato del pagamento. Attiva Logging per vedere il callback.

Il callback risponde Busy, retry: l'ordine era in elaborazione per il ritorno del cliente nello stesso momento, oppure l'ordine non è stato creato (per esempio perché il modulo è disattivato). Barion richiama il callback. Attiva Logging per vedere il motivo.

Il callback risponde API error: il negozio non è riuscito a leggere lo stato del pagamento da Barion, oppure la POSKey della modalità in cui è stato effettuato il pagamento non è impostata. Controlla questa POSKey.

Il callback risponde Order not found: il PaymentId non è stato avviato da questo negozio. Le chiamate di Barion per altri negozi o sistemi di test vengono ignorate.

Il cliente vede «Verifica del pagamento non riuscita»: il link di ritorno non corrisponde al carrello, per esempio perché è stato aperto in un'altra sessione del browser o modificato. Lo stato del pagamento viene comunque confermato dal callback.

Il cliente vede un errore quando sceglie Barion: attiva Logging e controlla il campo Log nella pagina del modulo. Una POSKey o un'e-mail del beneficiario errata produce Impossibile avviare il pagamento con Barion.

L'ordine è in Barion payment on hold: leggi la nota di discrepanza sull'ordine, controlla il pagamento nel portale Barion, poi evadi l'ordine oppure rimborsalo nel portale Barion.

Perché non posso rimborsare 10,50 HUF?: Barion elabora gli HUF senza decimali. Inserisci un importo intero.

Il rimborso indica che la POSKey Barion per la modalità di questo ordine non è configurata: il pagamento è stato effettuato in modalità test o live, e la POSKey di quella modalità è vuota. Inseriscila e riprova.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Barion 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 modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I dati di pagamento Barion degli ordini e gli stati dell'ordine Awaiting Barion payment e Barion payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID di transazione.

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