VibeFox Viva Wallet for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Account Viva: un account commerciante Viva. Per i test puoi usare un account demo (demo.vivapayments.com), per i pagamenti reali un account live (www.vivapayments.com). Ogni account ha le proprie credenziali. Per i pagamenti servono le credenziali Smart Checkout (Client ID e Client Secret) e il Source Code di una fonte di pagamento. Il Merchant ID e la API Key sono facoltativi: servono solo a rispondere alla verifica dell'URL del webhook da parte di Viva.

Valuta del negozio: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK o CHF. Con altre valute il metodo di pagamento viene nascosto al checkout.

Sito pubblico HTTPS: per i webhook il tuo sito deve essere raggiungibile da Internet tramite HTTPS.

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

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Viva Wallet > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

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

5. Inserisci le credenziali dell'account demo e/o live di Viva, poi configura la fonte di pagamento e il webhook (vedi Configurazione).

6. Attiva Enable/Disable. Effettua un pagamento demo con una carta demo di Viva mentre Test Mode è attivo, poi disattiva Test Mode per passare alla modalità live.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Viva Wallet. Sopra i campi la pagina ti avvisa quando la modalità attuale non ha Client ID, Client Secret o Source Code (Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered., oppure Live in modalità live) e quando la valuta del negozio non è supportata. Con la modalità test attiva mostra Test mode is on: payments go to the Viva demo environment. Nell'elenco dei metodi di pagamento, Viva Wallet risulta come da configurare finché la modalità attuale non ha questi tre valori.

General

Enable/Disable: Enable Viva Wallet 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: Viva Wallet.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: Use the Viva demo environment (demo.vivapayments.com). I nuovi pagamenti e le chiamate API usano le credenziali dell'account demo. Non viene addebitato denaro reale e, al checkout, la descrizione termina con (Test mode: use Viva demo cards, no real money is charged.) Predefinito: attivo. Disattivalo per accettare pagamenti reali con l'account live. I pagamenti già effettuati continuano a essere verificati e rimborsati nell'ambiente in cui sono stati fatti.

Account demo (modalità test) e account live

Entrambe le sezioni hanno gli stessi campi: un set per l'account demo, uno per l'account live. Nel tuo account Viva apri Settings > API Access e copia le credenziali Smart Checkout (Client ID, Client Secret), il Merchant ID e la API Key. Il Source Code si trova in Sales > Online payments > Websites / apps.

Client ID (Demo) / Client ID (Live): il Client ID OAuth 2.0 di Smart Checkout dell'account. Obbligatorio.

Client Secret (Demo) / Client Secret (Live): il Client Secret OAuth 2.0 di Smart Checkout dell'account. Obbligatorio.

Source Code (Demo) / Source Code (Live): il codice di 4 cifre della fonte di pagamento dell'account. I suoi Success URL e Failure URL devono puntare a questo negozio (vedi sotto). Obbligatorio.

Merchant ID (Demo) / Merchant ID (Live): facoltativo. Serve solo a rispondere alla verifica dell'URL del webhook da parte di Viva.

API Key (Demo) / API Key (Live): facoltativo. Serve solo a rispondere alla verifica dell'URL del webhook da parte di Viva.

URL di ritorno e webhook

Payment source: in Sales > Online payments > Websites / apps crea una fonte di pagamento per il dominio del tuo negozio, in ogni account che usi. Come Success URL e Failure URL inserisci i percorsi dopo il dominio dei due indirizzi mostrati nelle impostazioni, che hanno questo aspetto: https://your-site/wc-api/viva_payment_success/ e https://your-site/wc-api/viva_payment_fail/.

Webhook: in Settings > API Access > Webhooks aggiungi l'URL mostrato nelle impostazioni, che ha questo aspetto https://your-site/wp-json/wc-viva-gateway/v1/webhook, per questi eventi:

Viva controlla l'URL prima di salvarlo. Il plugin risponde con la chiave di verifica del tuo account: recupera la chiave con il Merchant ID e la API Key della modalità attuale, oppure usa la chiave inserita qui sotto. I webhook confermano i pagamenti anche quando il cliente chiude il browser. I webhook di Viva non sono firmati, quindi il plugin non si fida mai del webhook da solo: ogni pagamento viene verificato tramite l'API di Viva prima che l'ordine venga segnato come pagato. Senza webhook, un ordine viene confermato solo quando il cliente torna al negozio dopo aver pagato.

Webhook Verification Key: facoltativo. Lascialo vuoto per recuperare automaticamente la chiave con il Merchant ID e la API Key della modalità attuale, oppure incolla qui la chiave di verifica del tuo account Viva.

Impostazioni avanzate

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

Brand Color: un codice colore HEX a 6 cifre per la pagina di pagamento Viva, per esempio 0000ff. Un # iniziale viene rimosso. Lascialo vuoto per il colore predefinito. Qualsiasi altro valore viene rifiutato al salvataggio e resta quello precedente.

Debug Logging: Enable logging scrive le richieste API in WooCommerce > Status > Logs, origine wcp_viva_gateway. Chiavi e dati dei clienti non vengono registrati. Gli errori vengono sempre registrati, anche quando l'opzione è disattivata. Predefinito: disattivato.

Delete Data on Uninstall: Remove all plugin data when the plugin is deleted. Quando è attivo, eliminando il plugin vengono rimosse le impostazioni, la tabella dei tentativi di pagamento e i log del plugin. Note e dati degli ordini restano. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Viva Wallet) e inserisce l'ordine. Il plugin crea un ordine di pagamento Viva per il totale dell'ordine nella valuta dell'ordine e invia il cliente alla pagina Viva Smart Checkout. Lì il cliente paga con uno dei metodi attivati nel tuo account Viva, come carte, Apple Pay o Google Pay. E-mail, nome, telefono e paese del cliente vengono passati a Viva, e la pagina si apre nella lingua del tuo sito se Viva la supporta, altrimenti in inglese. Il pagamento compare in Viva come WooCommerce # e il numero dell'ordine. L'ordine di pagamento Viva scade dopo 30 minuti.

Dopo aver pagato, il cliente torna alla pagina di conferma dell'ordine del tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Viva: il plugin rilegge la transazione dall'API di Viva, al ritorno del cliente e sul webhook. Se il pagamento non è ancora confermato, la pagina mostra We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed.

Se il pagamento non riesce o il cliente annulla nella pagina di Viva, lo stato dell'ordine non cambia. Il cliente viene inviato alla pagina Pay for order con The Viva Wallet payment was not completed. Please try again or choose another payment method. oppure The Viva Wallet payment was cancelled. You can try again or choose another payment method., e può pagare di nuovo.

Se Viva non riesce ad avviare il pagamento, il cliente vede Viva Wallet payments are not available at the moment. Please choose another payment method or contact us. (credenziali mancanti o errate) oppure We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. Il motivo tecnico viene scritto nel log.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order, dove viene verificata la valuta di quell'ordine. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin accetta solo pagamenti una tantum, addebitati subito nella pagina Viva. Non prevede pre-autorizzazione e acquisizione, rate, carte salvate, WooCommerce Subscriptions, Viva Native Checkout (campi carta nella tua pagina) o terminali POS. Quando il cliente avvia un nuovo tentativo, il vecchio ordine di pagamento Viva non pagato non viene annullato; Viva lo fa scadere dopo 30 minuti.

Ordini e rimborsi

Order statuses

Pending payment: il cliente è stato inviato a Viva e non ha ancora pagato, il pagamento non è ancora stato confermato, oppure il pagamento non è riuscito o è stato annullato. Una nota mostra l'ordine di pagamento Viva e l'ambiente (demo o live). I tentativi non riusciti e annullati vengono aggiunti alle note dell'ordine, e il cliente può pagare di nuovo.

Processing, Completed or On Hold: il pagamento è stato confermato. Lo stato segue Order Status After Payment. La nota dell'ordine mostra l'importo, l'ID transazione Viva, l'ambiente e come è stato confermato (webhook o ritorno del cliente).

On hold for review: Viva ha segnalato un importo o una valuta diversi dal totale dell'ordine, per esempio quando l'ordine è stato modificato dopo che il cliente aveva iniziato a pagare. La nota Viva Wallet payment held for review indica il motivo. Confronta il pagamento nella dashboard Viva con l'ordine e completalo o rimborsalo manualmente.

Un pagamento che arriva per un ordine annullato o rimborsato non cambia lo stato dell'ordine; una nota ti chiede di ripristinare l'ordine o di rimborsare il pagamento nella dashboard Viva. Se per un ordine già pagato arriva un secondo pagamento, l'ordine non viene modificato di nuovo; una nota ti chiede di rimborsare il duplicato nella dashboard Viva.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Viva Wallet. Sono supportati rimborsi totali e parziali per gli ordini con una transazione Viva confermata. Il rimborso viene inviato all'account con cui è stato effettuato il pagamento (demo o live), nella valuta del pagamento, quindi devono essere inseriti Client ID e Client Secret di quell'account. Se Viva non accetta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con la transazione di rimborso Viva.

I rimborsi effettuati nella dashboard di Viva non vengono importati. Se necessario, crea un rimborso manuale in WooCommerce senza Refund via Viva Wallet.

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 > Viva Wallet. 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 controllare 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 suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Viva Wallet 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. Gli amministratori del negozio connessi vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins 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 il rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

Viva Wallet non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità attuale abbia il proprio Client ID, Client Secret e Source Code (i campi Demo in modalità test, i campi Live in modalità live). La valuta del negozio (nella pagina Pay for order, la valuta dell'ordine) deve essere una tra EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK o CHF. La pagina delle impostazioni mostra un avviso quando manca qualcosa.

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: il webhook non funziona. In Viva verifica che il webhook esista nell'account che usi (demo o live), che il suo URL sia esattamente quello mostrato nelle impostazioni e che sia selezionato Transaction Payment Created. Controlla che Client ID e Client Secret dell'account di quel pagamento siano ancora inseriti: il plugin li usa per verificare il pagamento. I dettagli sono in WooCommerce > Status > Logs, origine wcp_viva_gateway.

Viva non riesce a verificare l'URL del webhook: inserisci il Merchant ID e la API Key della modalità attuale (oppure la chiave di verifica stessa in Webhook Verification Key), salva e verifica di nuovo in Viva. Per verificare il webhook dell'altro account, prima passa a Test Mode oppure inserisci la chiave di quell'account.

Il webhook risponde con un errore: Viva mostra la risposta del tuo negozio e ritenta i webhook non riusciti. verification_failed (HTTP 500) significa che non è stato possibile raggiungere l'API di Viva per verificare il pagamento. busy (HTTP 503) significa che l'ordine era in elaborazione da un'altra richiesta nello stesso momento. transaction_not_found (HTTP 404) significa che la transazione non esiste nell'account di quel pagamento, per esempio per credenziali errate. Gli eventi relativi ai pagamenti di altri negozi sullo stesso account Viva ricevono la risposta ignored.

Il cliente vede un errore durante l'ordine: attiva Debug Logging e controlla WooCommerce > Status > Logs, origine wcp_viva_gateway. Un Client ID o un Client Secret errati, oppure un Source Code mancante, danno il messaggio che i pagamenti Viva Wallet non sono disponibili. Se Viva non è raggiungibile o rifiuta l'ordine di pagamento, per esempio perché il Source Code appartiene a un altro account, il cliente riceve il messaggio che il negozio non è riuscito a connettersi a Viva Wallet.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta pagati erano diversi da quelli dell'ordine. Completa l'ordine oppure rimborsa il pagamento.

Il rimborso non riesce con This payment was made in the Viva demo (or live) environment: Client ID e Client Secret dell'account in cui è stato effettuato il pagamento non sono inseriti. Inseriscili e riprova. Gli altri errori di rimborso mostrano il codice HTTP e il messaggio di Viva.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot 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 sviluppatori: il filtro viva_wp_supported_currencies attiva altre valute supportate dal tuo account Viva, viva_wp_create_order_payload modifica la richiesta dell'ordine di pagamento (importo, valuta e Source Code devono restare invariati) e viva_wp_icon modifica l'icona del checkout.

Disinstallazione

Disattivare il plugin mantiene tutti i dati; vengono rimossi solo i token di accesso Viva in cache. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin, così come i token in cache e le chiavi dei webhook, vengono sempre rimossi. Le impostazioni, la tabella dei tentativi di pagamento e i log del plugin (file di log, compresi quelli ruotati, e voci nel database) vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID di transazione.

Viva Wallet è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da Viva Wallet.