VibeFox Barion for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo. Senza WooCommerce il plugin mostra un avviso nell'area di amministrazione e il metodo di pagamento non viene caricato.
PHP: 8.0 o successivo.
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 la live, secure.test.barion.com per la sandbox, in My stores e nel tuo negozio. Sandbox e live hanno credenziali diverse.
Valuta: la valuta del negozio deve essere HUF, EUR, USD o CZK. Per le altre valute il metodo di pagamento viene nascosto al checkout.
Negozio raggiungibile: Barion richiama il tuo negozio dopo ogni pagamento, quindi il sito deve essere raggiungibile da internet, senza modalità manutenzione, firewall o autenticazione di base davanti a /wc-api/.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo 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 la cartella wcp_barion_gateway in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Barion > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Inserisci la POSKey di test e l'e-mail del wallet di test, lascia attivo Test Mode e attiva Enable/Disable. Effettua un ordine di prova.
6. Quando tutto funziona, inserisci le credenziali live e deseleziona Test Mode.
L'URL di callback viene inviato automaticamente a Barion con ogni pagamento. Non serve configurare nulla nel portale Barion.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Barion. Se la valuta del negozio non è supportata, la pagina lo segnala in rosso nella sezione Barion shop credentials ed elenca le valute supportate; il metodo di pagamento viene poi nascosto al checkout.
Generali
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. Predefinito: Barion.
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
Trovi la POSKey e l'e-mail del wallet nel portale Barion: secure.barion.com (live) oppure secure.test.barion.com (sandbox), My stores, il tuo negozio. Questa sezione mostra anche l'URL di callback, per esempio https://your-site/wc-api/barion_payment_callback/. Viene inviato a Barion con ogni pagamento; deve solo essere raggiungibile da internet.
Test Mode: Enable Barion test/sandbox mode. La modalità sandbox usa le credenziali di test qui sotto e la sandbox Barion (api.test.barion.com); non viene addebitato denaro reale. Predefinito: attivato. Deselezionalo per accettare pagamenti reali.
Test POSKey: la chiave segreta (POSKey) del tuo negozio nel sistema sandbox di Barion (secure.test.barion.com, My stores).
Test Payee Email: l'indirizzo e-mail del tuo wallet Barion di test 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.
Ordini
Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento riuscito e verificato.
Avanzate
Logging: Enable debug logging. I registri vengono salvati in WooCommerce > Status > Logs, origine wcp_barion_gateway. Le chiavi segrete non vengono mai registrate. Predefinito: disattivato.
Delete Data on Uninstall: Remove the plugin settings when the plugin is deleted. Gli ordini e i loro dati di pagamento Barion vengono sempre conservati. Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Barion) e fa l'ordine. Il plugin avvia un pagamento Barion per il totale dell'ordine nella valuta dell'ordine e invia il cliente alla pagina di pagamento Barion. Articoli, spedizione, commissioni e imposte dell'ordine vengono elencati nel pagamento, l'e-mail di fatturazione del cliente viene passata come suggerimento e la lingua della pagina segue quella del negozio dove Barion la supporta.
Dopo il pagamento, il cliente torna al tuo negozio. Anche Barion richiama l'URL di callback. Nessuna delle due richieste segna da sola l'ordine come pagato: il plugin chiede a Barion lo stato del pagamento con la tua POSKey, e l'ordine viene segnato come pagato solo quando Barion lo conferma e importo e valuta corrispondono all'ordine. Il link di ritorno contiene la chiave dell'ordine, e vengono verificati solo i pagamenti avviati per quell'ordine.
Se il pagamento è riuscito o è ancora in corso presso Barion, il cliente arriva alla pagina Ordine ricevuto. Altrimenti torna al checkout e vede Payment was not completed. Please try again. Il cliente può riprovare; ogni tentativo viene memorizzato, quindi un pagamento tardivo di un tentativo precedente completa comunque l'ordine.
Se non è possibile avviare il pagamento, il cliente vede The Barion payment could not be started. Please try again or choose another payment method. I gestori del negozio che hanno effettuato l'accesso vedono anche il motivo tecnico. I dettagli vanno nel registro.
Il metodo di pagamento funziona con il checkout classico e con il blocco Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin gestisce solo pagamenti immediati. Non gestisce pagamenti con riserva o acquisizione differita, WooCommerce Subscriptions 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
Pending payment: il pagamento Barion è stato avviato e Barion non lo ha ancora confermato. La nota dell'ordine mostra il PaymentId Barion, l'importo e, in modalità sandbox, (test mode).
Processing or Completed: Barion ha confermato il pagamento. Lo stato segue Order Status After Payment. La nota dell'ordine mostra importo, PaymentId e transazione. L'ID transazione è l'ID transazione Barion.
On hold: Barion ha segnalato un importo o una valuta diversi dal totale dell'ordine, per esempio perché l'ordine è stato modificato dopo l'avvio del pagamento. Verifica il pagamento nel portale Barion e completa o rimborsa l'ordine manualmente.
Cancelled: l'ultimo tentativo di pagamento è stato annullato o è scaduto presso Barion.
Failed: l'ultimo tentativo di pagamento non è riuscito.
Un ordine pagato o rimborsato non viene mai modificato da un callback successivo. Se un altro pagamento riesce per un ordine già pagato, una nota ti chiede di verificarlo nel portale Barion e di rimborsarlo se è un duplicato.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Barion. Sono supportati rimborsi totali e parziali. Il motivo del rimborso viene inviato a Barion come commento. I rimborsi in HUF devono essere importi interi. Il rimborso viene inviato nella modalità (sandbox o live) in cui l'ordine è stato pagato, quindi la POSKey di quella modalità deve essere impostata. Se Barion non accetta o non conferma il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con la transazione Barion e lo stato.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Barion. 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 verificare di nuovo 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 solo dominio. Rimuovere la chiave da un sito non libera il posto del dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, il metodo di pagamento 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. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.
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
Barion non appare 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, e che la valuta del negozio sia HUF, EUR, USD o CZK.
Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: l'ordine viene completato quando Barion richiama l'URL di callback oppure quando il cliente torna al tuo negozio. Verifica che il sito sia raggiungibile da internet (niente modalità manutenzione, firewall o autenticazione di base davanti a /wc-api/). Controlla che la POSKey della modalità in cui è stato pagato l'ordine sia corretta, perché il plugin 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. Barion richiama il callback.
Il callback risponde API error: il negozio non è riuscito a leggere lo stato del pagamento da Barion. Controlla la POSKey della modalità in cui è stato pagato l'ordine.
Un ordine è On hold con una nota di mancata corrispondenza: importo o valuta comunicati da Barion sono diversi dal totale dell'ordine. Verifica il pagamento nel portale Barion e completa o rimborsa manualmente.
Perché non posso rimborsare 10.50 HUF: Barion gestisce l'HUF senza decimali. Inserisci un importo intero.
Il rimborso segnala che la POSKey della modalità di questo ordine non è configurata: l'ordine è stato pagato in modalità sandbox o live, e la POSKey di quella modalità è vuota. Inseriscila e riprova.
Il blocco 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.
Disinstallazione
Disattivare il plugin mantiene 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 vengono rimosse solo se Delete Data on Uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini e i loro dati di pagamento Barion vengono sempre conservati. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.
Barion è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da Barion.