VibeFox Viva Wallet for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni PHP precedenti.

Account Viva: un account commerciante Viva. Puoi usare un account demo (demo.vivapayments.com) per i test e un account live (www.vivapayments.com) per i pagamenti reali. 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. Merchant ID e API Key sono facoltativi: servono solo a rispondere alla verifica dell'URL del webhook di Viva.

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

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 fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure oppure, più tardi, trova VibeFox Viva Wallet Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in cima alla pagina Configure e fai clic su Activate (vedi Chiave di licenza).

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

5. Attiva Enable/Disable e fai clic su Save. Effettua un pagamento demo con una carta demo di Viva mentre Test Mode è attivo, poi disattiva Test Mode per andare in produzione.

All'installazione il modulo crea lo stato ordine Viva Wallet payment on hold. Il modulo viene proposto per i paesi attivi al momento dell'installazione. Puoi modificare valute, paesi e gruppi di clienti in Payment > Preferences; in seguito potrai aggiungere lì nuovi paesi.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa se la modalità corrente 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 se la valuta predefinita del negozio non è supportata. Mentre la modalità test è attiva, mostra Test mode is on: payments go to the Viva demo environment. Salvare le impostazioni rimuove i token di accesso Viva in cache, così le nuove credenziali vengono usate subito.

Viva Wallet

Enable/Disable: Enable Viva Wallet 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: Viva Wallet. Obbligatorio: un titolo vuoto non viene salvato e la pagina mostra Enter a title for the payment method.

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: usa l'ambiente demo di Viva (demo.vivapayments.com). I nuovi pagamenti e le chiamate API usano le credenziali dell'account demo. Non viene addebitato denaro reale e al checkout il cliente vede (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 l'API Key. Il Source Code si trova in Sales > Online payments > Websites / apps.

Client ID (Demo) / Client ID (Live): l'OAuth 2.0 Client ID di Smart Checkout dell'account. Obbligatorio per i pagamenti.

Client Secret (Demo) / Client Secret (Live): l'OAuth 2.0 Client Secret di Smart Checkout dell'account. Obbligatorio per i pagamenti.

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

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

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

I Client Secret e le API Key salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved secrets: seleziona un segreto e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

URL di ritorno e webhook

Addresses for the Viva account: questo campo mostra i tre indirizzi del tuo negozio da inserire nell'account Viva. Con URL leggibili hanno questo aspetto: https://your-shop/module/wcp_viva_gateway/success, https://your-shop/module/wcp_viva_gateway/fail e https://your-shop/module/wcp_viva_gateway/webhook, eventualmente con un codice lingua come /en/. Copiali esattamente come li mostrano le impostazioni.

Payment source: in Sales > Online payments > Websites / apps crea una fonte di pagamento per il dominio del tuo negozio, in ciascun account che usi. Come Success URL e Failure URL inserisci la parte degli indirizzi di successo e di errore che segue il dominio.

Webhook: in Settings > API Access > Webhooks aggiungi l'indirizzo del webhook per questi eventi:

Viva controlla l'URL prima di salvarlo. Il modulo risponde con la chiave di verifica del tuo account: la recupera con il Merchant ID e l'API Key della modalità corrente, 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 modulo non si fida mai del webhook da solo: ogni pagamento viene verificato con l'API di Viva prima che l'ordine venga creato. Senza il webhook, un ordine viene creato solo quando il cliente torna al negozio dopo aver pagato.

Webhook Verification Key: facoltativo. Lascialo vuoto per recuperare la chiave automaticamente con il Merchant ID e l'API Key della modalità corrente, 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 non viene salvato: la pagina mostra Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept.

Debug Logging: scrive le richieste API in logs/viva_wp_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi, token e dati dei clienti non vengono registrati. Gli errori vengono sempre registrati, anche quando l'opzione è disattivata. Predefinito: disattivato.

Log: mostra le dimensioni e le voci più recenti del registro. Fai clic su Clear log per svuotarlo.

Delete Data on Uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni e i registri del modulo. Ordini e relativi dati di pagamento (tentativi di pagamento Viva, rimborsi, stato dell'ordine) non vengono mai eliminati. Predefinito: disattivato.

Checkout

Al momento del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Viva Wallet) e vede la nota You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). Dopo la conferma, il modulo crea un ordine di pagamento Viva per il totale del carrello nella valuta del carrello e invia il cliente alla pagina Viva Smart Checkout. Lì il cliente paga con uno dei metodi attivati nel tuo account Viva. E-mail, nome, telefono e paese del cliente vengono passati a Viva, e la pagina si apre nella lingua del carrello se Viva la supporta. Nel pagamento su Viva compare come Cart #, il numero del carrello e il nome del tuo negozio. L'ordine di pagamento Viva scade dopo 30 minuti. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Viva: il modulo rilegge la transazione dall'API di Viva, al ritorno del cliente e sul webhook. Quindi l'ordine viene creato e il cliente vede la normale pagina di conferma dell'ordine. Se il pagamento non è ancora confermato, una pagina Payment confirmation mostra We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. con i pulsanti Check again e Back to checkout; il webhook crea l'ordine non appena Viva conferma il pagamento.

Se il pagamento fallisce o il cliente annulla sulla pagina di Viva, non viene creato alcun ordine e il carrello viene conservato. Il cliente torna al checkout 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 resta al checkout con 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 registro.

Le pagine di ritorno mostrano la conferma dell'ordine solo al cliente che ha pagato. Chiunque altro apra l'indirizzo di ritorno viene reindirizzato allo storico ordini o al checkout, senza dettagli dell'ordine.

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

Il modulo accetta solo pagamenti una tantum, addebitati subito sulla pagina di Viva. Non prevede pre-autorizzazione e cattura, rate, carte salvate, abbonamenti, Viva Native Checkout (campi carta nella propria 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

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Viva e non ha pagato, il pagamento non è riuscito o è stato annullato, oppure Viva non ha ancora finalizzato il pagamento. Esiste solo il carrello, e il cliente può pagare di nuovo.

Payment accepted, Delivered o Viva Wallet payment on hold: il pagamento è stato confermato. Lo stato segue Order Status After Payment. Il pagamento viene registrato con l'ID della transazione Viva e una nota mostra l'importo, la transazione, il codice ordine Viva, l'ambiente (demo o live) e come è stato confermato (webhook o ritorno del cliente).

Viva Wallet payment on hold dopo una discrepanza: Viva ha segnalato un importo o una valuta diversi dal totale del carrello, ad esempio perché il carrello è stato modificato dopo che il cliente ha iniziato a pagare. L'ordine viene creato senza un pagamento registrato, e la nota Viva Wallet payment held for review ne indica il motivo. Il cliente vede la normale pagina di conferma dell'ordine, senza alcuna promessa di conferma da parte di Viva. Confronta il pagamento nella dashboard di Viva con l'ordine ed evadilo o rimborsalo manualmente. Se in seguito arriva un pagamento corrispondente per lo stesso carrello, l'ordine passa allo stato pagato.

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

Blocco Viva Wallet payment

La pagina dell'ordine mostra un blocco Viva Wallet payment con il codice ordine Viva, l'ID della transazione, l'ambiente e il Source Code, lo stato Viva, gli importi pagati e rimborsati, un badge Demo per i pagamenti demo, lo storico dei rimborsi, i tentativi di pagamento del carrello (quando ce n'è stato più di uno) e le Viva Wallet notes dell'ordine.

Rimborsi

Nel blocco Viva Wallet payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Viva Wallet. Conferma la domanda Refund this amount via Viva Wallet? This cannot be undone. Sono supportati rimborsi totali e parziali per ordini con una transazione Viva confermata. Ti serve il permesso di modificare gli ordini; l'accesso ai moduli non è necessario. Puoi rimborsare fino all'importo addebitato da Viva per il pagamento, anche se l'ordine è stato modificato in seguito. Il rimborso viene inviato all'account in 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, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note, con la transazione di rimborso Viva. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. Un ordine trattenuto per verifica senza un pagamento confermato non può essere rimborsato dal blocco.

Il modulo non crea note di credito. I pulsanti standard di rimborso di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Viva. I rimborsi effettuati nella dashboard di Viva non vengono importati. Aggiorna l'ordine manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Viva Wallet Gateway è il primo blocco di Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo, 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 compaiono la riga Product: presta-payment-viva 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 modificare 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 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: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il relativo 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 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 sei connesso 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 dal webhook di Viva e dal ritorno al negozio, e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a 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

Viva Wallet non compare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia Client ID, Client Secret e Source Code (i campi Demo in modalità test, i campi Live in modalità live). La valuta del carrello deve essere una tra EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK o CHF. In Payment > Preferences controlla che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo di clienti. La pagina delle impostazioni mostra un avviso quando mancano le credenziali.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: il webhook non funziona. In Viva controlla che il webhook esista nell'account che usi (demo o live), che il suo URL sia esattamente quello mostrato nelle impostazioni e che Transaction Payment Created sia selezionato. Controlla che Client ID e Client Secret dell'account di quel pagamento siano ancora inseriti: il modulo ne ha bisogno per verificare il pagamento. Attiva Debug Logging e controlla il campo Log. L'ordine viene creato anche quando il cliente torna al negozio dopo aver pagato.

Viva non riesce a verificare l'URL del webhook: inserisci il Merchant ID e l'API Key della modalità corrente (oppure la chiave di verifica stessa in Webhook Verification Key), salva, poi verifica di nuovo in Viva. Per verificare il webhook dell'altro account, attiva prima 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 falliti. verification_failed (HTTP 500) significa che non è stato possibile raggiungere l'API di Viva per verificare il pagamento, oppure che non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). 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 a pagamenti di altri negozi sullo stesso account Viva ricevono la risposta ignored.

Il cliente vede un errore quando sceglie Viva Wallet: controlla il campo Log nella pagina del modulo. Un Client ID o un Client Secret errati mostrano il messaggio che i pagamenti con 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.

Il cliente torna e vede We could not find your order. If you were charged, please contact us.: il codice ordine Viva nell'indirizzo di ritorno non è un pagamento di questo negozio, per esempio perché la fonte di pagamento di un altro negozio punta qui. Controlla il Success URL e il Failure URL della fonte di pagamento.

L'ordine è in Viva Wallet payment on hold dopo il pagamento: leggi le note nel blocco Viva Wallet payment (vedi Stati dell'ordine), poi evadi l'ordine o 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 indica Transaction ID not found. Cannot process refund.: l'ordine non ha un pagamento Viva confermato, per esempio dopo una discrepanza di importo. Se necessario, rimborsa il pagamento nella dashboard di Viva.

Disinstallazione

Disattivare il modulo conserva tutti i dati; vengono rimossi solo i token di accesso Viva in cache. Per rimuoverlo, vai su Modules > Module Manager, apri il menu accanto a VibeFox Viva Wallet Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. I token di accesso in cache e le chiavi dei webhook vengono sempre rimossi. Se Delete Data on Uninstall è attivo, vengono rimosse le impostazioni e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I tentativi di pagamento Viva, i rimborsi e lo stato ordine Viva Wallet payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID delle transazioni.

Viva Wallet è un marchio di proprietà del rispettivo titolare. Questo modulo non è affiliato né approvato da Viva Wallet.