VibeFox Ozow for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

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

Valuta: rand sudafricano (ZAR). Il metodo di pagamento viene mostrato solo per i carrelli in ZAR. Ozow addebita in centesimi interi, quindi la valuta deve usare 2 decimali.

Account Ozow: un account commerciante Ozow con il Site Code e la Private Key del tuo sito Ozow, che trovi nella dashboard del commerciante Ozow. La API Key è facoltativa ma consigliata. Ozow usa lo stesso Site Code e le stesse chiavi per i pagamenti di prova e quelli reali.

Sito raggiungibile: il negozio deve essere raggiungibile da Internet, senza protezione con password né firewall che blocchi Ozow, affinché arrivino le notifiche di Ozow. La notifica viene accettata anche mentre il negozio è in modalità manutenzione.

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 trova più tardi VibeFox Ozow Pay nell'elenco dei moduli e fai clic su Configure.

3. Incolla 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 il Site Code e la Private Key, e preferibilmente la API Key, dalla dashboard del commerciante Ozow.

5. Attiva Enable/Disable e fai clic su Save. Effettua un pagamento di prova con Test mode attivo, poi disattiva la modalità test per accettare pagamenti reali.

All'installazione il modulo crea due stati dell'ordine: Awaiting Ozow payment e Ozow 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; lì ZAR deve essere consentito per il modulo. Un paese abilitato in seguito deve essere spuntato anche per il modulo in quella stessa sezione.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Ozow Pay > Configure. Ogni sezione con un pulsante Save salva l'intera pagina. Sopra i campi, la pagina ti avvisa quando manca il Site Code o la Private Key (Ozow viene allora nascosto al checkout), quando la valuta predefinita del negozio non è ZAR, quando la valuta ha più di 2 decimali (impostala a 2 in International > Localization > Currencies), e mostra Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. mentre la modalità test è attiva.

Ozow

Enable/Disable: Enable Ozow payments 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 del metodo di pagamento salvato nell'ordine. Predefinito: Instant EFT (Ozow).

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment. In modalità test, sotto il testo viene aggiunta la riga TEST MODE: no money will be charged. (solo se la descrizione non è vuota).

Credenziali Ozow

Copia il Site Code, la Private Key e la API Key dalla dashboard del commerciante Ozow (Merchant details / Sites). La sezione contiene un link alla documentazione di integrazione di Ozow su hub.ozow.com.

Site Code: il Site Code del sito Ozow che riceve i pagamenti. Le risposte per un altro Site Code vengono rifiutate.

Private Key: firma ogni richiesta di pagamento e verifica ogni risposta di Ozow. Tienila riservata. Senza di essa il metodo di pagamento è nascosto e nessuna risposta di Ozow viene accettata.

API Key (recommended): facoltativa. Con una API Key, ogni pagamento riuscito viene confermato anche tramite l'API GetTransaction di Ozow prima che l'ordine venga segnato come pagato. L'API deve indicare il pagamento come completato, per questo carrello, con lo stesso importo, la stessa valuta e lo stesso Site Code.

Le chiavi salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarlo.

Clear saved secrets: spunta Private Key o API Key e salva per rimuovere una chiave salvata. Un campo vuoto mantiene il valore salvato.

Test mode: Ozow usa lo stesso Site Code e le stesse chiavi per i test: i pagamenti vengono creati con IsTest=true e nessun denaro viene movimentato. Gli ordini pagati in modalità test ricevono un messaggio nell'ordine; non spedirli. Disattiva la modalità test per accettare pagamenti reali. Un pagamento di prova non paga mai un ordine in modalità reale. Predefinito: on.

Notifiche di pagamento

Gli URL di notifica, successo, annullamento ed errore vengono inviati a Ozow con ogni pagamento, quindi non c'è nulla da configurare nella dashboard di Ozow, a meno che il tuo sito Ozow non sia impostato su URL fissi. La sezione mostra tutti e quattro gli URL: Notification URL, Success URL, Cancel URL e Error URL. Sono link del modulo del tuo negozio (controller notify e return). Se il tuo sito Ozow usa URL fissi, copiali esattamente come li mostrano le impostazioni.

Avanzate

Debug log: registra le richieste di pagamento e le risposte di Ozow in logs/ozow_p_debug.log.php, nella cartella del modulo (non leggibile dal web). Errori e avvisi vengono sempre registrati. Chiavi, hash, token e dati dei clienti non vengono mai registrati. Predefinito: off.

Log: mostra la dimensione attuale e la fine del registro, con un pulsante Clear log.

Delete data on uninstall: alla disinstallazione rimuove le impostazioni e i registri di questo modulo (i dati Ozow salvati sugli ordini vengono conservati). Predefinito: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Instant EFT (Ozow)) e conferma l'ordine. Il modulo invia il cliente alla pagina di pagamento ospitata da Ozow con una richiesta firmata per il totale del carrello in ZAR. Il riferimento sull'estratto conto bancario è Cart e il numero del carrello (fino a 20 lettere latine, cifre, spazi e trattini). Il nome del cliente viene passato a Ozow. A questo punto non esiste ancora alcun ordine. Sulla pagina di Ozow il cliente sceglie una banca sudafricana e approva il pagamento nell'app della banca.

Ozow poi avvisa il negozio e rimanda il cliente indietro. Entrambi contengono la stessa risposta firmata e vengono elaborati allo stesso modo, così l'ordine viene creato anche se uno dei due va perso. L'ordine viene segnato come pagato solo dopo la conferma di Ozow: l'hash deve essere verificato con la tua Private Key, il Site Code deve essere il tuo, la risposta deve appartenere a questo tentativo di pagamento del carrello, e importo e valuta devono corrispondere al carrello. Con una API Key il pagamento viene verificato anche tramite l'API GetTransaction.

Dopo un pagamento riuscito il cliente vede la pagina standard di conferma dell'ordine. Se Ozow o la banca stanno ancora esaminando il pagamento, la pagina dice We are waiting for Ozow to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Se l'ordine è in sospeso, dice Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed. Se un pagamento esaminato fallisce in seguito o l'ordine non pagato viene annullato, dice Your Ozow payment was not completed. Please contact us about this order. Se Ozow non ha ancora confermato il pagamento quando il cliente torna, una pagina mostra il testo di attesa con i pulsanti Check again e Back to checkout.

Se il cliente annulla sulla pagina di Ozow o il pagamento fallisce, non viene creato alcun ordine. Il cliente torna al checkout con lo stesso carrello e vede The Ozow payment was cancelled. You can try again or choose another payment method. oppure The Ozow payment was not completed. You can try again or choose another payment method.

Se il carrello non è in ZAR, il cliente vede Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.

Il modulo accetta solo pagamenti una tantum in ZAR. Non gestisce rimborsi da PrestaShop, né abbonamenti, né conti bancari salvati o tokenizzazione, né l'invio di link di pagamento dal back office.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Ozow e non ha pagato, ha annullato, oppure Ozow non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted: il pagamento è stato confermato. Il messaggio dell'ordine mostra l'importo e l'ID transazione Ozow, e se il pagamento è stato confermato dall'API GetTransaction. L'ID transazione del pagamento dell'ordine è il TransactionId di Ozow. Un pagamento di prova riceve il messaggio TEST MODE — no money was received, do not ship this order.

Awaiting Ozow payment: Ozow o la banca stanno esaminando il pagamento. L'ordine viene aggiornato quando Ozow invia lo stato finale.

Ozow payment on hold: il messaggio dell'ordine indica il motivo: l'importo o la valuta pagati differiscono dal carrello; è arrivato un pagamento per un ordine già annullato; oppure, con una API Key, l'API GetTransaction non ha ancora potuto confermare il pagamento o lo contraddice. Controlla il pagamento nella tua dashboard Ozow e cambia lo stato dell'ordine. Se l'API non ha potuto rispondere, la notifica successiva di Ozow completa l'ordine.

Errore di pagamento: un pagamento in esame è stato annullato, abbandonato o è fallito. Una risposta riuscita successiva di Ozow per quel pagamento segna comunque l'ordine come pagato.

Un ordine già pagato non viene mai riportato indietro, e un ordine annullato o rimborsato non viene mai riaperto. Se per un ordine già pagato arriva un secondo pagamento, un messaggio ti chiede di rimborsare il duplicato nella tua dashboard Ozow. Se un ordine è in sospeso per un altro motivo, ad esempio impostato da te, un pagamento successivo aggiunge solo un messaggio e sei tu a impostare l'ordine su Payment accepted.

Blocco pagamento Ozow

La pagina dell'ordine mostra un blocco Ozow payment con il riferimento e il tentativo della transazione, l'ID transazione Ozow, lo stato, l'importo richiesto, l'importo indicato da Ozow, il messaggio di Ozow e un contrassegno TEST MODE per i pagamenti di prova.

Rimborsi

I rimborsi da PrestaShop non sono supportati. Rimborsa il pagamento nella tua dashboard del commerciante Ozow, poi registra manualmente il rimborso in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Ozow Pay è il primo blocco di Modules > Module Manager > VibeFox Ozow Pay > Configure, sopra le impostazioni. Incolla la chiave in License key e fai clic su Activate. Dopo di ciò il blocco mostra la chiave mascherata, lo stato (ad 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 di essi ci sono la riga Product: presta-payment-ozow 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 inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, ad 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 suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Ozow 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. Lo storefront di PrestaShop non sa che hai effettuato l'accesso 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.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Ozow non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che Site Code e Private Key siano compilati e che la valuta del carrello sia ZAR. In Payment > Preferences verifica che il modulo sia consentito per ZAR, per il paese del cliente e per il gruppo del cliente. La pagina delle impostazioni mostra un avviso quando manca qualcosa.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: la notifica di Ozow non ha raggiunto il negozio e il cliente non è tornato. Verifica che il tuo negozio sia raggiungibile da Internet (nessuna protezione con password né firewall che blocchi Ozow). Se il tuo sito Ozow è impostato su URL fissi, verifica che siano esattamente quelli mostrati in Payment notifications. Attiva Debug log e leggi il registro nella pagina Configure.

La notifica risponde Invalid hash: la Private Key nelle impostazioni non appartiene al sito Ozow che ha inviato la risposta. Copiala di nuovo dalla dashboard del commerciante Ozow. Non viene modificato nulla.

La notifica risponde Unknown site: la risposta proviene da un altro sito Ozow. Controlla il Site Code.

La notifica risponde Order mismatch o Order not found: la risposta non appartiene a un pagamento avviato in questo negozio. Non viene modificato nulla.

La notifica risponde Gateway not configured: manca il Site Code o la Private Key. Compilali; Ozow può riprovare.

La notifica risponde Payment not confirmed yet: la risposta non ha ancora potuto essere applicata. Con una API Key, l'API GetTransaction non ha potuto confermare il pagamento (l'ordine è in sospeso e la notifica successiva lo completa; se resta in sospeso, controlla la API Key e il pagamento nella tua dashboard Ozow). È la risposta anche quando il ritorno del cliente era in elaborazione per lo stesso carrello nello stesso momento, oppure quando non è stato possibile creare l'ordine; consulta il registro.

Un pagamento di prova non ha pagato l'ordine: il modulo è in modalità reale. I pagamenti di prova non pagano mai un ordine in modalità reale; il messaggio dell'ordine o il registro lo indicano.

L'ordine è in Ozow payment on hold dopo il pagamento: leggi il messaggio dell'ordine e controlla il pagamento nella tua dashboard Ozow, poi imposta l'ordine su Payment accepted oppure rimborsa il pagamento in Ozow.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Ozow Pay e scegli Uninstall. La chiave di licenza e lo stato di licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, le impostazioni del modulo e il registro vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I record dei pagamenti Ozow e gli stati dell'ordine Awaiting Ozow payment e Ozow payment on hold vengono sempre conservati, così le notifiche tardive dei vecchi ordini continuano a essere riconosciute dopo una reinstallazione. Gli ordini esistenti conservano i loro messaggi di pagamento e gli ID transazione.

Ozow è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Ozow né approvato da Ozow.