VibeFox Ozow for WooCommerce — Guida

Requisiti

WordPress: 6.2 o successivo.

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

PHP: 8.0 o successivo.

Valuta: rand sudafricano (ZAR). Il metodo di pagamento viene nascosto per le altre valute. Ozow addebita centesimi interi, quindi WooCommerce 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. L'API Key è facoltativa ma consigliata. Ozow usa lo stesso Site Code e le stesse chiavi per i pagamenti di test e quelli reali.

Sito raggiungibile: il tuo sito deve essere raggiungibile da Internet, senza modalità manutenzione, protezione con password o firewall che blocchi Ozow, così che le notifiche di Ozow arrivino.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un 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_ozow_pay in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Ozow > 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 il Site Code e la Private Key e, preferibilmente, la API Key dalla dashboard del commerciante Ozow.

6. Attiva Enable/Disable. Effettua un pagamento di prova con Test mode attivo, poi disattiva la modalità test per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Ozow. Sopra i campi, la pagina avvisa quando mancano il Site Code o la Private Key (Ozow viene allora nascosto al checkout), quando la valuta del negozio non è ZAR e quando WooCommerce usa più di 2 decimali, e mostra Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. finché la modalità test è attiva. Nell'elenco dei metodi di pagamento, Ozow risulta da configurare finché non vengono compilati il Site Code e la Private Key.

Generali

Enable/Disable: Enable Ozow payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. 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 viene aggiunta la riga TEST MODE: no money will be charged.

Credenziali Ozow

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

Site Code: il Site Code del sito Ozow che riceve i pagamenti. Le risposte relative a 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 viene 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 riportare il pagamento come completato, per questo ordine, con lo stesso importo, la stessa valuta e lo stesso Site Code.

Test mode: Enable Ozow test mode. Ozow usa lo stesso Site Code e le stesse chiavi per i test: i pagamenti vengono creati con IsTest=true e non si muove denaro. Gli ordini pagati in modalità test ricevono una nota; non spedirli. Disattiva la modalità test per accettare pagamenti reali. Un pagamento di prova non paga mai un ordine in modalità live. Predefinito: attivo.

Notifiche di pagamento

Gli URL di notifica, di successo, di annullamento e di 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 con URL fissi. La sezione mostra l'URL di notifica. Ha questo aspetto: https://your-site/wc-api/ozow_pay/?ozow_notify=1. Se il tuo sito Ozow usa URL fissi, copialo esattamente come lo mostrano le impostazioni.

Avanzate

Debug log: Log payment requests and Ozow responses scrive i dettagli in WooCommerce > Status > Logs, origine wcp_ozow_pay. Errori e avvisi vengono sempre registrati. Chiavi, hash e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Ozow data saved on orders is kept). Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Instant EFT (Ozow)) e conferma l'ordine. Il plugin invia il cliente alla pagina di pagamento ospitata da Ozow con una richiesta firmata per il totale dell'ordine in ZAR. Il riferimento sull'estratto conto bancario è Order seguito dal numero d'ordine (fino a 20 lettere latine, cifre, spazi e trattini). Il nome del cliente viene passato a Ozow. Sulla pagina di Ozow il cliente sceglie una banca sudafricana e approva il pagamento nell'app della banca.

Ozow notifica poi il negozio e rimanda il cliente indietro. Entrambi contengono la stessa risposta firmata e vengono elaborati allo stesso modo, quindi l'ordine viene aggiornato anche se uno dei due si perde. 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 contenere la chiave di questo ordine e importo e valuta devono corrispondere all'ordine. Con una API Key, il pagamento viene verificato anche tramite l'API GetTransaction.

Dopo un pagamento riuscito, il cliente arriva alla pagina di conferma dell'ordine. Se Ozow non ha ancora confermato il pagamento, la pagina riporta 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, riporta Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed.

Se il cliente annulla nella pagina di Ozow o il pagamento non riesce, l'ordine passa a Failed e il cliente torna alla pagina Pay for order con 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. Il cliente può pagare di nuovo lo stesso ordine.

Il metodo di pagamento funziona al checkout classico, nel blocco Checkout e nella pagina Pay for order (solo per ordini in ZAR). È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin accetta solo pagamenti una tantum in ZAR. Non prevede rimborsi da WooCommerce, abbonamenti, conti bancari salvati o tokenizzazione, né l'invio di link di pagamento dall'amministrazione.

Ordini

Stati dell'ordine

Pending payment: il cliente è stato inviato a Ozow e non ha ancora pagato, oppure Ozow non ha ancora confermato il pagamento.

Processing: il pagamento è stato confermato. È lo stato standard di WooCommerce dopo il pagamento; gli ordini con soli prodotti virtuali scaricabili passano a Completed. La nota dell'ordine mostra importo e ID di transazione Ozow, e se il pagamento è stato confermato dall'API GetTransaction. L'ID di transazione dell'ordine è il TransactionId di Ozow. Un pagamento di prova riceve la nota TEST MODE — no money was received, do not ship this order.

On hold: la nota dell'ordine spiega il motivo. Ozow o la banca stanno verificando il pagamento (l'ordine viene aggiornato quando Ozow invia lo stato finale); l'importo o la valuta pagati non corrispondono all'ordine; è arrivato un pagamento per un ordine già annullato; oppure, con una API Key, l'API GetTransaction non è ancora riuscita a 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.

Failed: il cliente ha annullato il pagamento, il pagamento è stato abbandonato o Ozow ha segnalato un errore. Il cliente può pagare di nuovo dall'ordine.

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, una nota ti chiede di rimborsare il duplicato nella tua dashboard Ozow. Se un ordine è in sospeso per un altro motivo, per esempio impostato da te, un pagamento successivo aggiunge solo una nota e sei tu a impostare l'ordine su Processing.

Rimborsi

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

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Ozow. 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 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, Ozow non viene mostrato ai clienti al checkout. Se un pagamento viene comunque avviato, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio con accesso continuano a vedere 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 continuano a essere confermati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Ozow non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che il Site Code e la Private Key siano compilati e che la valuta del negozio o dell'ordine sia ZAR. La pagina delle impostazioni mostra un avviso quando manca qualcosa.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: la notifica di Ozow non ha raggiunto il negozio e il cliente non è tornato. Verifica che il sito sia raggiungibile da Internet (nessuna modalità manutenzione, protezione con password o firewall che blocchi Ozow). Se il tuo sito Ozow usa URL fissi, controlla che l'URL di notifica sia esattamente quello mostrato nelle impostazioni. Attiva Debug log e controlla WooCommerce > Status > Logs, origine wcp_ozow_pay.

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.

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 ordine di questo negozio. Non viene modificato nulla.

La notifica risponde Gateway not configured: manca il Site Code o la Private Key. Inseriscili; Ozow potrebbe riprovare.

La notifica risponde Order busy: un'altra risposta di Ozow per lo stesso ordine era in elaborazione nello stesso momento. La risposta non viene applicata; la notifica successiva o il ritorno del cliente la applicherà.

La notifica risponde Payment not confirmed yet: con una API Key, l'API GetTransaction non è riuscita a confermare il pagamento. L'ordine è in sospeso e la notifica successiva lo completerà. Se resta in sospeso, controlla la API Key e il pagamento nella dashboard Ozow.

Il cliente vede Ozow accepts payments in South African rand (ZAR) only: l'ordine è in un'altra valuta. Ozow non può essere usato per questo ordine.

Un pagamento di prova non ha pagato l'ordine: il gateway è in modalità live. I pagamenti di prova non pagano mai un ordine in modalità live; una nota sull'ordine lo segnala.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine e controlla il pagamento nella dashboard Ozow, poi imposta l'ordine su Processing o rimborsa il pagamento in Ozow.

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.

Disinstallazione

Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, le altre opzioni del plugin e i suoi registri vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID di transazione.

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