VibeFox Viva Wallet for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successivo (testato su 4.1.0.3).

PHP: 8.0 o successivo.

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 per rispondere alla verifica dell'URL del webhook da parte di Viva.

Valuta: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK o CHF. La valuta selezionata dal cliente nel negozio deve essere una di queste; in altre valute il metodo di pagamento viene nascosto al checkout.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un dominio.

Installazione

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 wcp_viva_gateway-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 wcp_viva_gateway.ocmod.zip. Installa solo il pacchetto per la tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nell'area di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_viva_gateway-oc3-(version).ocmod.zip. L'estensione non ha modifiche OCMOD, quindi Extensions > Modifications non deve essere aggiornato. In alternativa all'installer puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella radice del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo Payments. Trova VibeFox Viva Wallet Gateway e clicca su Install (il pulsante verde +). Il tuo utente amministratore deve avere il permesso di modificare l'elenco delle estensioni di pagamento.

3. Clicca su Edit (il pulsante a matita) per aprire la pagina delle impostazioni. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco della licenza in cima alla pagina, e clicca su Activate (vedi License key).

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

5. Attiva Enable/Disable e clicca su Save. Effettua un pagamento demo con una carta demo di Viva mentre Test Mode è attivo, poi disattiva Test Mode per passare alla modalità reale.

OpenCart 4

1. Nell'area di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_viva_gateway.ocmod.zip. Non rinominare il file: OpenCart 4 ricava il codice dell'estensione dal nome del file, e un pacchetto rinominato non funziona.

2. Il pacchetto compare nell'elenco delle estensioni installate nella stessa pagina. Clicca su Install (il pulsante verde +) accanto ad esso.

3. Vai su Extensions > Extensions e scegli il tipo Payments. Trova VibeFox Viva Wallet Gateway, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a matita).

4. Inserisci la chiave di licenza, le credenziali Viva, la fonte di pagamento e il webhook come nei passaggi da 3 a 5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni. Cambiano solo gli indirizzi per l'account Viva (vedi Configuration).

Una nuova installazione parte con il metodo di pagamento disattivato e la modalità test attiva.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Payments > VibeFox Viva Wallet Gateway > Edit. Le sezioni sono elencate a sinistra; il pulsante Save sotto l'elenco salva l'intera pagina. Sopra le impostazioni la pagina ti avvisa quando 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à reale) e quando la valuta predefinita del negozio non è supportata. Con la modalità test attiva mostra Test mode is on: payments go to the Viva demo environment. Senza il permesso di modificare l'estensione, la pagina mostra le impostazioni ma non può salvarle.

Al salvataggio, Title non può essere vuoto e deve avere al massimo 128 caratteri (Enter a title for the payment method (at most 128 characters).), Sort Order deve essere un numero intero (Sort Order must be a whole number.), Total deve essere un numero maggiore o uguale a 0 (Total: enter a number, 0 or greater.), e la zona geografica e gli stati ordine selezionati devono esistere; altrimenti non viene salvato nulla e la pagina mostra l'errore. Il salvataggio delle impostazioni elimina 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: off.

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome salvato nell'ordine. Predefinito: Viva Wallet. Obbligatorio, massimo 128 caratteri.

Description: il testo mostrato al cliente nel passaggio Confirm Order, sopra il pulsante di conferma. 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 nel passaggio Confirm Order i clienti vedono (Test mode: use Viva demo cards, no real money is charged.) Predefinito: on. 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 eseguiti.

Sort Order: la posizione di Viva Wallet tra i metodi di pagamento al checkout. Lascia vuoto o inserisci un numero intero; sono ammessi numeri negativi.

Geo Zone: offri Viva Wallet solo per gli indirizzi di pagamento nella zona geografica selezionata. Predefinito: All zones. Le zone geografiche si configurano in System > Localisation > Geo Zones.

Total: il totale del checkout, nella valuta predefinita del negozio, che un ordine deve raggiungere prima che venga offerto Viva Wallet: un numero maggiore o uguale a 0. Lascia vuoto per offrirlo per qualsiasi totale.

Demo account (test mode) and Live account

Entrambe le sezioni hanno gli stessi campi: uno 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): il Client ID OAuth 2.0 di Smart Checkout dell'account. Obbligatorio per i pagamenti.

Client Secret (Demo) / Client Secret (Live): il Client Secret OAuth 2.0 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 URL di successo e di errore devono puntare a questo negozio (vedi sotto). Obbligatorio per i pagamenti.

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

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

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

Clear saved secrets: alla fine della sezione Live account. Spunta un segreto salvato e clicca su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Return URLs and webhook

Addresses for the Viva account: questo campo mostra i tre indirizzi del tuo negozio da inserire nell'account Viva. Vengono costruiti a partire dall'indirizzo della vetrina della tua installazione di OpenCart e hanno questo aspetto: https://your-store/index.php?route=extension/payment/wcp_viva_gateway/success&, https://your-store/index.php?route=extension/payment/wcp_viva_gateway/fail& e https://your-store/index.php?route=extension/payment/wcp_viva_gateway/webhook su OpenCart 3, e su OpenCart 4 https://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.success&, https://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.fail& e https://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.webhook. Copiali esattamente come li mostrano le impostazioni. Il & alla fine degli indirizzi di successo e di errore è necessario: Viva aggiunge la transazione all'indirizzo, e senza di esso OpenCart risponde con una pagina non trovata.

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 che seguono il dominio negli indirizzi di successo e di errore.

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

Viva verifica l'URL prima di salvarlo. L'estensione 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 l'estensione non si fida mai del webhook da solo: ogni pagamento viene verificato con l'API di Viva prima che l'ordine riceva il suo stato. Senza il webhook, un ordine riceve il suo stato solo quando il cliente torna nel negozio dopo il pagamento.

Webhook Verification Key: facoltativo. Lascia 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.

Order statuses

OpenCart crea l'ordine nel passaggio Confirm Order senza stato (un ordine mancante). L'ordine riceve uno stato solo dopo che il pagamento Viva è stato verificato. I campi di stato elencano i tuoi stati ordine OpenCart.

Order Status After Payment: lo stato che riceve un ordine pagato. Viene impostato subito, con un unico cambio di stato.

Processing Status: lo stato di un ordine pagato per Default e Processing. Predefinito: Processing.

Complete Status: lo stato di un ordine pagato per Completed. Predefinito: Complete.

On Hold Status: lo stato di un ordine pagato per On Hold, e di un ordine il cui pagamento Viva non corrisponde all'importo o alla valuta dell'ordine (trattenuto per verifica, non pagato; la nota ne indica il motivo). Predefinito: Pending, perché OpenCart non ha lo stato On hold. Puoi creare un tuo stato in System > Localisation > Order Statuses e selezionarlo qui.

Cancelled Order Status: un pagamento Viva ricevuto per un ordine in questo stato non lo riapre mai; una nota ti chiede di ripristinare l'ordine o di rimborsare il pagamento. L'estensione non imposta mai questo stato. Predefinito: Canceled.

Refunded Status: impostato quando il pagamento viene rimborsato per intero dalla scheda dell'ordine. Un pagamento successivo non riapre nemmeno un ordine così. Predefinito: Refunded.

Advanced Settings

Brand Color: un codice colore HEX a 6 cifre per la pagina di pagamento Viva, per esempio 0000ff. Un # iniziale viene rimosso. Lascia vuoto per il colore predefinito. Qualsiasi altro valore non viene salvato: il resto delle impostazioni viene salvato, e 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 viva_wp_debug.log.php nella cartella dei log di OpenCart (storage/logs, su OpenCart 4 system/storage/logs). Il file non può essere aperto dal web. Chiavi, token e dati dei clienti non vengono registrati. Gli errori vengono sempre registrati, anche se questa opzione è disattivata. Predefinito: off.

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

Delete Data on Uninstall: se attivo, la disinstallazione dell'estensione rimuove le impostazioni del gateway e il registro. Gli ordini e i loro dati di pagamento (tentativi di pagamento Viva, rimborsi) non vengono mai eliminati. Predefinito: off.

Import / Export

Export: Download JSON salva le impostazioni in un file JSON. I segreti non vengono esportati.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni. I segreti salvati vengono mantenuti.

Checkout

Nel passaggio Payment Method il cliente sceglie il metodo di pagamento (per impostazione predefinita Viva Wallet). Nel passaggio Confirm Order il cliente vede la tua descrizione e la nota You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). OpenCart crea l'ordine in questo passaggio, ancora senza stato. Su OpenCart 4 il cliente sceglie il metodo di pagamento con il pulsante Choose del blocco del metodo di pagamento, nella finestra Payment method options, e clicca su Confirm Order in fondo alla pagina del checkout. Quando il cliente clicca su Confirm Order, l'estensione crea un ordine di pagamento Viva per il totale dell'ordine nella valuta dell'ordine e invia il cliente alla pagina Smart Checkout di Viva, con il tuo Brand Color se ne è impostato uno. Lì il cliente paga con uno dei metodi abilitati nel tuo account Viva. L'e-mail, il nome, il telefono, il paese e la lingua del negozio del cliente vengono passati a Viva. Il pagamento compare in Viva come OpenCart # e il numero dell'ordine, e viene descritto al cliente come Order, il numero dell'ordine, at e il nome del tuo negozio. L'ordine di pagamento Viva scade dopo 30 minuti.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando Viva lo conferma: l'estensione rilegge la transazione dall'API di Viva, sia al ritorno del cliente sia con il webhook. L'ordine riceve poi il suo stato nel modo standard di OpenCart, con le consuete e-mail d'ordine e l'aggiornamento del magazzino, e il cliente vede la pagina di successo dell'ordine di OpenCart. 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 carrello viene conservato finché il pagamento non è confermato; il webhook imposta lo stato dell'ordine appena Viva conferma. Su OpenCart 4, quando il cliente torna dalla pagina di Viva, una breve pagina intermedia riapre l'indirizzo di ritorno del tuo negozio, così il carrello e la sessione del cliente vengono conservati.

Se il pagamento fallisce o il cliente annulla nella pagina di Viva, l'ordine resta senza stato 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. Ogni nuovo tentativo avvia un nuovo ordine di pagamento Viva. Un carrello viene pagato una sola volta: se il carrello è già pagato da un altro ordine della stessa operazione di checkout, il cliente passa direttamente alla pagina di successo. Su OpenCart 4 questi messaggi sono mostrati sopra la pagina del checkout. OpenCart 3 crea un nuovo ordine ogni volta che viene mostrato il passaggio Confirm Order, mentre OpenCart 4 aggiorna l'ordine del checkout. Una modifica del carrello, incluso un nuovo quantitativo, conta come un nuovo carrello che richiede un pagamento proprio.

Su OpenCart 4 l'ordine resta nel checkout fino alla visualizzazione della pagina di successo. Dopo un pagamento non riuscito o annullato, il cliente paga di nuovo lo stesso ordine con un nuovo ordine di pagamento Viva. Se nel frattempo quell'ordine è stato chiuso (per esempio l'hai annullato), oppure era stato pagato per un carrello che nel frattempo è cambiato, il cliente torna al checkout con This order can no longer be paid. Please confirm your order again., e il successivo Confirm Order paga un nuovo ordine.

Se Viva non riesce ad avviare il pagamento, il cliente resta nel passaggio Confirm Order con un messaggio sopra il pulsante: 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 pagina di successo dell'ordine solo al cliente che ha pagato. Chiunque altro apra l'indirizzo di ritorno viene inviato alla cronologia ordini o al checkout senza dettagli dell'ordine.

Il webhook funziona anche mentre il negozio è in modalità manutenzione, perché OpenCart lascia passare le richieste delle estensioni di pagamento. Su OpenCart 4 un'azione di avvio dell'estensione lascia passare il webhook e gli indirizzi di successo e di errore.

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

Nessuno stato (ordine mancante): il cliente è stato inviato a Viva e non ha pagato, il pagamento è fallito o è stato annullato, oppure Viva non ha ancora finalizzato il pagamento. Il cliente può pagare di nuovo. In Sales > Orders questi ordini vengono mostrati solo con il filtro Order Status impostato su Missing Orders. Su OpenCart 4.1 questo ordine può avere anche lo stato Voided, che OpenCart imposta quando il passaggio di conferma viene mostrato di nuovo; l'estensione lo considera un ordine senza stato.

Order Status After Payment (predefinito Processing): il pagamento è stato confermato. 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).

On Hold Status dopo una discrepanza (predefinito Pending): Viva ha comunicato un importo o una valuta diversi dal totale dell'ordine. L'ordine non viene segnato come pagato, e la nota Viva Wallet payment held for review ne indica il motivo. Confronta il pagamento nella dashboard di Viva con l'ordine e gestiscilo manualmente: evadilo o rimborsalo. Se più tardi arriva un pagamento corrispondente per lo stesso ordine, l'ordine passa allo stato pagato.

Un pagamento che arriva per un ordine in Cancelled Order Status o Refunded Status non cambia lo stato dell'ordine; una nota ti chiede di ripristinare l'ordine o di rimborsare il pagamento nella dashboard di Viva. Se arriva un secondo pagamento per un ordine già pagato, o per un altro ordine di un carrello già pagato, l'ordine non viene modificato; una nota sull'ordine pagato ti chiede di rimborsare il duplicato nella dashboard di Viva.

Le note sono voci della History dell'ordine che il cliente non vede. I cambi di stato non avvisano il cliente da soli; OpenCart invia la consueta e-mail d'ordine quando un ordine pagato riceve per la prima volta il suo stato.

VibeFox Viva Wallet Gateway tab

In Sales > Orders apri un ordine pagato con Viva Wallet. In fondo alla pagina dell'ordine, accanto a History e Additional, la scheda VibeFox Viva Wallet Gateway mostra il Viva order code, il Transaction ID con un'etichetta Demo per i pagamenti demo, l'Environment / Source Code, lo Viva status, gli importi Paid / refunded, il modulo di rimborso, lo storico dei rimborsi, i Viva payment attempts dell'ordine (se ce n'è più di uno) e le Viva Wallet notes dell'ordine. La scheda viene mostrata agli utenti che hanno accesso all'estensione.

Refunds

Nella scheda VibeFox Viva Wallet Gateway inserisci l'Amount (viene compilato l'importo non ancora rimborsato), facoltativamente un Reason (optional), e clicca su Refund via Viva Wallet. Conferma la domanda Refund this amount via Viva Wallet? This cannot be undone. I rimborsi totali e parziali sono supportati per gli ordini con un pagamento Viva confermato. Ti serve il permesso di modificare l'estensione (impostato in System > Users > User Groups). 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, la scheda mostra l'errore e nessun rimborso viene registrato. 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 Status senza avvisare il cliente e senza rimettere i prodotti in magazzino, come un cambio di stato manuale. Un rimborso parziale non modifica lo stato. Un ordine trattenuto per verifica dopo una discrepanza non ha un pagamento confermato e non può essere rimborsato dalla scheda.

I resi di prodotti in Sales > Returns non restituiscono denaro tramite Viva. I rimborsi effettuati nella dashboard di Viva non vengono importati. Aggiorna l'ordine manualmente se necessario.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco della licenza License — VibeFox Viva Wallet Gateway è il primo blocco della pagina Extensions > Extensions > Payments > VibeFox Viva Wallet Gateway > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo l'attivazione il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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 ci sono la riga Product: opencart-payment-viva e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso Modify sull'estensione possono cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (sono incluse le lingue inglese e russa).

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 che è cambiato l'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, clicca su Check now. Se il server delle licenze non è raggiungibile, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: l'indirizzo del negozio nella configurazione di OpenCart. Rimuovere la chiave dal negozio 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 comunque un pagamento viene avviato, il cliente vede This payment method is not available. Please choose another one. Un utente amministratore connesso al pannello nello stesso browser vede ancora il metodo di pagamento nel negozio, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso dell'amministratore, quindi senza una chiave attiva il metodo di pagamento è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati dal webhook di Viva e dal ritorno nel negozio, e i rimborsi funzionano.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Viva Wallet non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia il suo Client ID, il suo Client Secret e il suo Source Code (i campi Demo in modalità test, i campi Live in modalità reale). La valuta selezionata nel negozio deve essere una tra EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK o CHF. Verifica anche che l'indirizzo di pagamento sia nella Geo Zone selezionata e che l'ordine raggiunga il Total impostato nelle impostazioni. La pagina delle impostazioni mostra un avviso quando mancano le credenziali.

Il pagamento è andato a buon fine, ma l'ordine resta senza stato: 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 Transaction Payment Created sia selezionato. Verifica che Client ID e Client Secret dell'account di quel pagamento siano ancora inseriti: l'estensione li usa per verificare il pagamento. Attiva Debug Logging e controlla il campo Log. L'ordine riceve comunque il suo stato quando il cliente torna nel negozio dopo aver pagato.

Il cliente torna su una pagina non trovata: il Success URL o il Failure URL della fonte di pagamento non termina con &. Copia i percorsi esattamente come li mostrano le impostazioni.

Viva non riesce a verificare l'URL del webhook: inserisci il Merchant ID e la API Key della modalità corrente (oppure la chiave di verifica stessa in Webhook Verification Key), salva e verifica di nuovo in Viva. Per verificare il webhook dell'altro account, cambia 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 impostare lo stato dell'ordine. 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 dopo Confirm Order: controlla il campo Log nella pagina dell'estensione. Un Client ID o un Client Secret errati 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. This payment method is not available. significa che la sessione di checkout non corrisponde più all'ordine: il cliente ricarica il checkout.

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 è nello stato di verifica dopo il pagamento: leggi le note nella scheda VibeFox Viva Wallet Gateway (vedi Order statuses), poi evadi l'ordine oppure rimborsa il pagamento.

Nessun modulo di rimborso nella scheda: la scheda indica il motivo: l'ordine non ha un pagamento Viva confermato (Transaction ID not found. Cannot process refund.), è rimborsato per intero, mancano le credenziali dell'account del pagamento, oppure il tuo gruppo utenti non ha il permesso di modificare l'estensione.

Il rimborso fallisce 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 messaggio di Viva.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Payments e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Viva Wallet Gateway. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart rimuove sempre le proprie impostazioni dell'estensione: Enable/Disable, Sort Order, Geo Zone, Total e i campi di stato della sezione Order statuses, che tornano ai valori predefiniti in caso di reinstallazione. I token di accesso Viva e le chiavi dei webhook in cache vengono sempre rimossi. Su OpenCart 4 vengono sempre rimossi anche l'evento dell'estensione e la sua azione di avvio, che in modalità manutenzione lascia passare il webhook e gli indirizzi di ritorno. Se Delete Data on Uninstall è attivo, vengono rimosse anche le altre impostazioni del gateway (titolo, descrizione, modalità test, credenziali, stato dell'ordine dopo il pagamento, colore del brand, registrazione) e il registro. Se è disattivo, vengono conservate per una reinstallazione successiva. I tentativi di pagamento Viva e i rimborsi vengono sempre conservati, quindi gli ordini pagati in precedenza possono ancora essere rimborsati dopo una reinstallazione. Gli ordini esistenti mantengono le loro note di pagamento.

Su OpenCart 4, per rimuovere anche i file dell'estensione, vai su Extensions > Installer dopo la disinstallazione e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Viva Wallet Gateway nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

Viva Wallet è un marchio del rispettivo titolare. Questa estensione non è affiliata né approvata da Viva Wallet.