VibeFox Tranzila for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

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

PHP: 8.0 o successivo.

Valuta del negozio: ILS, USD, EUR o GBP. Per le altre valute il metodo di pagamento viene nascosto al checkout.

Terminale Tranzila: serve il nome del terminale. La password del terminale (TranzilaPW) è necessaria per l'handshake e per i rimborsi da WooCommerce. Alcuni terminali richiedono anche una password di credito separata (CreditPass) per i rimborsi. Il nome del terminale e le password sono forniti da Tranzila: consulta le impostazioni del terminale o chiedi all'assistenza Tranzila. Tranzila non offre una sandbox pubblica. Per i test, Tranzila ti fornisce un terminale di prova separato; inserisci il suo nome come nome del terminale.

IP reale del visitatore: le notifiche di pagamento vengono verificate in base all'indirizzo IP del server Tranzila. Se il sito si trova dietro un proxy o una CDN come Cloudflare, il server web deve passare a PHP l'IP reale del visitatore (REMOTE_ADDR).

Chiave di licenza VibeFox: si acquista 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 clicca su Install Now. In alternativa puoi caricare la cartella wcp_tranzila_payment_gateway in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Tranzila > Manage, oppure clicca su Settings sotto il nome del plugin nella pagina Plugins.

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

5. Inserisci il Terminal name (supplier) e, se usi l'handshake o i rimborsi, la Terminal password (TranzilaPW).

6. Lascia Notifications attivo e controlla Trusted IP: deve elencare gli indirizzi IP da cui Tranzila invia le notifiche. Conferma l'elenco con l'assistenza Tranzila.

7. Consigliato: attiva l'handshake nel terminale Tranzila, consenti lì l'IP del tuo server, poi attiva Handshake nel plugin.

8. Attiva Enable/Disable e prova un pagamento con il terminale di test Tranzila.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Tranzila. Sopra i campi la pagina ti avvisa quando il nome del terminale è vuoto (il metodo di pagamento viene allora nascosto al checkout), quando le notifiche sono disattivate o Trusted IP è vuoto (gli ordini pagati vengono messi in attesa di verifica manuale), quando l'handshake è attivo senza password del terminale (la pagina di pagamento non può essere aperta) e quando la valuta del negozio non è supportata. Al salvataggio, un nome del terminale non valido o una voce non valida in Trusted IP non vengono salvati: la pagina mostra un errore e resta il valore precedente. I numeri fuori dall'intervallo consentito vengono portati al valore consentito più vicino.

General

Enable/Disable: Enable Tranzila 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: Credit Card (Tranzila).

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with your credit card on the Tranzila payment page.

Terminal

Terminal name (supplier): il nome del tuo terminale Tranzila, per esempio myshop. Solo lettere, cifre, «-» e «_». Finché non viene inserito, il metodo di pagamento non viene mostrato al checkout. Per i test, inserisci il nome del tuo terminale di prova Tranzila.

Terminal password (TranzilaPW): la password API del terminale. È necessaria per l'handshake e per i rimborsi da WooCommerce.

Refund password (CreditPass): solo se il tuo terminale richiede una password separata per le transazioni di credito (rimborsi). Altrimenti lasciala vuota.

Payment page

Payment page version: la pagina Tranzila mostrata nell'iframe.

Payment page language: la lingua della pagina Tranzila: Site language, Hebrew, English, Russian, Spanish, German, French o Japanese. Predefinito: Hebrew. Site language usa la lingua della localizzazione WordPress del visitatore quando è una di queste lingue, altrimenti English.

iFrame width (px): da 300 a 1200. Predefinito: 600. Sugli schermi piccoli il riquadro non è mai più largo della pagina.

iFrame height (px): da 400 a 1500. Predefinito: 650.

Max installments: il numero massimo di rate (tashlumim) che il cliente può scegliere nella pagina di pagamento, fino a 36. 0 o 1 significa nessuna rata. Predefinito: 0. Il terminale deve essere autorizzato a elaborare le rate.

Handshake: Lock the amount with a handshake token (recommended). Prima di aprire la pagina di pagamento, il negozio chiede a Tranzila un token monouso legato all'importo dell'ordine, così che l'importo non possa essere modificato nel browser. Richiede la password del terminale, l'handshake attivo nel terminale Tranzila e l'IP del tuo server autorizzato lì. Predefinito: disattivato.

Payment confirmation

Le notifiche Tranzila non sono firmate. Un ordine viene segnato come pagato solo quando la notifica proviene da un Trusted IP e il suo codice ordine, terminale, importo e valuta corrispondono all'ordine. Con l'handshake attivo, il token deve corrispondere anche alla pagina di pagamento dell'ordine. Il ritorno del cliente dalla pagina di pagamento non segna mai un ordine come pagato.

Notifications: Confirm payments automatically with Tranzila notifications (notify URL). Predefinito: attivo. L'URL di notifica viene inviato a Tranzila con ogni pagamento, quindi non devi inserirlo nel terminale Tranzila. Ha questo aspetto: https://your-site/wc-api/tranzila_p_callback/ ed è mostrato sotto il campo. Quando le notifiche sono disattivate, un cliente che torna da una pagina di pagamento riuscita vede l'ordine messo in attesa, e tu confermi il pagamento manualmente dopo averlo controllato nel terminale Tranzila.

Trusted IP: gli indirizzi IP o gli intervalli CIDR dei server Tranzila che inviano le notifiche, separati da virgole. Predefinito: 80.244.170.7. Conferma l'elenco attuale con l'assistenza Tranzila. Le notifiche da altri indirizzi vengono rifiutate. Se il campo è vuoto, le notifiche non possono essere verificate: un pagamento riuscito segnalato mette l'ordine in attesa di verifica manuale, mentre un rifiuto segnalato non modifica l'ordine.

Advanced

Debug log: Log payment page, notification and refund events scrive in WooCommerce > Status > Logs, origine wcp_tranzila_payment_gateway. Gli errori vengono sempre registrati, anche con questa opzione disattivata. Password, token e dati dei clienti non vengono mai scritti. Predefinito: disattivato.

Delete data on uninstall: Delete the settings, logs and Tranzila order data when the plugin is deleted. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit Card (Tranzila)) e clicca su Continue to payment. L'ordine viene creato con lo stato In attesa di pagamento e il cliente passa alla pagina di pagamento dell'ordine del tuo negozio. Lì si apre la pagina di pagamento Tranzila in un iframe, con il totale dell'ordine nella valuta dell'ordine, i dati di fatturazione e un breve elenco dei prodotti ordinati. La pagina dice Enter your card details on the secure Tranzila payment page below. If it does not load, click "Proceed to payment". Il link Choose another payment method si trova sotto il riquadro. Se le rate sono consentite, il cliente ne sceglie il numero nella pagina Tranzila.

Dopo un pagamento riuscito, Tranzila riporta il cliente e l'intera finestra passa alla pagina di ordine ricevuto del tuo negozio. L'ordine viene segnato come pagato solo quando Tranzila lo conferma con una notifica. Fino ad allora la pagina mostra Your payment is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Se l'ordine è in attesa di verifica, la pagina mostra Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed.

Se il pagamento viene rifiutato o annullato, il cliente torna alla pagina di pagamento dell'ordine con il messaggio The payment was not completed. You have not been charged — please try again or choose another payment method. Quando Tranzila segnala un codice di risposta, vengono aggiunti il motivo e il codice, per esempio che la carta è scaduta. Il cliente può pagare di nuovo o scegliere un altro metodo di pagamento.

Se la pagina di pagamento non può essere aperta, per esempio quando l'handshake fallisce, il cliente vede un breve messaggio come Could not connect to Tranzila. Please try again in a moment. e il link Choose another payment method. Il motivo tecnico viene scritto nel registro.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. Nella pagina Pay for order viene offerto quando la valuta dell'ordine è supportata. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin accetta solo pagamenti con carta una tantum, nella pagina Tranzila. Non prevede carte o token salvati, abbonamenti, autorizzazione e cattura separate (J5), pulsanti propri per Bit, Apple Pay o Google Pay (ciò che offre la tua pagina di pagamento Tranzila viene mostrato dentro l'iframe) né fatture Tranzila.

Ordini e rimborsi

Order statuses

Pending payment: il cliente è stato inviato alla pagina di pagamento e non ha ancora pagato, oppure la notifica Tranzila non è ancora arrivata.

Processing or Completed: il pagamento è stato confermato da una notifica verificata. WooCommerce imposta In lavorazione, oppure Completato per gli ordini che non richiedono spedizione. La nota dell'ordine mostra l'importo, la transazione Tranzila e il numero di autorizzazione, oltre al numero di rate se presenti. L'ID transazione è l'indice di transazione Tranzila.

On hold: il pagamento è stato ricevuto ma non accettato automaticamente: importo, valuta o token dell'handshake non corrispondevano all'ordine; la notifica non ha potuto essere verificata perché Trusted IP è vuoto; oppure le notifiche sono disattivate e il cliente è tornato da una pagina di pagamento riuscita. La nota dell'ordine spiega il motivo. Controlla il pagamento nel terminale Tranzila e cambia lo stato manualmente.

Failed: Tranzila ha segnalato un pagamento rifiutato per un ordine in attesa. La nota mostra il codice di risposta e il suo significato. Un ordine già pagato non viene mai impostato su Failed.

Se arriva un pagamento per un ordine annullato, l'ordine viene riaperto con una nota che ti chiede di verificare le scorte prima della spedizione. Se il cliente ha cambiato metodo di pagamento nella pagina Pay for order ma ha pagato in una pagina Tranzila ancora aperta, il metodo di pagamento dell'ordine viene riportato su Tranzila. Se arriva un secondo pagamento per un ordine già pagato, completato o rimborsato, l'ordine non cambia. Una nota ti chiede di verificarlo e di rimborsare il duplicato nel terminale Tranzila. Le notifiche ripetute della stessa transazione vengono ignorate.

Refunds

Apri l'ordine, clicca su Refund, inserisci l'importo e clicca su Refund via Credit Card (Tranzila) (il pulsante mostra il titolo del metodo di pagamento). Sono supportati rimborsi totali e parziali. Il rimborso viene eseguito come transazione di credito Tranzila del pagamento originale. Il pulsante è disponibile quando la password del terminale è impostata e l'ordine ha una transazione Tranzila confermata con numero di autorizzazione. Un rimborso riuscito viene aggiunto alle note dell'ordine con la transazione di credito Tranzila.

Se Tranzila non accetta il rimborso, WooCommerce mostra l'errore, per esempio Tranzila declined the refund con il codice, e nessun rimborso viene registrato. Un ordine pagato su un terminale diverso da quello attualmente impostato (per esempio un terminale di prova) non può essere rimborsato da WooCommerce; rimborsalo in quel terminale Tranzila. I rimborsi effettuati nel terminale Tranzila non vengono comunicati al negozio. Se necessario, crea un rimborso manuale in WooCommerce senza usare il pulsante Tranzila.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > Tranzila. Incolla la chiave in License key e clicca 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 solo dominio. Rimuovere la chiave da un sito non libera lo slot del dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Tranzila 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 continuano a vedere il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare 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 assistenza richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Tranzila does not appear at checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che Terminal name (supplier) sia compilato e che la valuta del negozio (nella pagina Pay for order, la valuta dell'ordine) sia ILS, USD, EUR o GBP. La pagina delle impostazioni mostra un avviso quando il nome del terminale manca o la valuta non è supportata.

The payment went through, but the order stays Pending payment: la notifica non è arrivata o è stata rifiutata. Controlla che Notifications sia attivo e che Trusted IP elenchi gli indirizzi da cui Tranzila invia le notifiche. Gli errori vengono sempre scritti in WooCommerce > Status > Logs, origine wcp_tranzila_payment_gateway. Il messaggio che un IP non è nell'elenco Trusted IP significa che bisogna correggere l'impostazione Trusted IP o la configurazione del proxy: dietro un proxy o una CDN il server web deve passare a PHP l'IP reale del visitatore.

Notification answers Forbidden: proveniva da un indirizzo IP che non è in Trusted IP.

Notification answers Bad request or Not found: l'ordine, il suo codice ordine, il terminale o l'indice di transazione nella notifica non corrispondono a nessun ordine di questo negozio.

Notification answers Accepted for manual review: Trusted IP è vuoto, quindi la notifica non è stata verificata. Un pagamento riuscito mette l'ordine in attesa. Compila Trusted IP per confermare automaticamente i pagamenti.

Notification answers Busy, retry: l'ordine era in elaborazione da un'altra richiesta nello stesso momento, e la notifica non è stata applicata. Controlla il pagamento nel terminale Tranzila; se l'ordine attende ancora il pagamento e il pagamento è approvato lì, cambia lo stato manualmente.

Some paid orders are On hold: leggi la nota dell'ordine. Importo, valuta o token dell'handshake non corrispondevano, oppure la notifica non è stata verificabile (Trusted IP vuoto o notifiche disattivate). Controlla il pagamento nel terminale Tranzila e cambia lo stato manualmente.

The payment page does not open with the handshake on: verifica nome e password del terminale, che l'handshake sia attivo nel terminale Tranzila e che l'IP del tuo server sia consentito lì. Il registro mostra il motivo.

Refunds fail: i rimborsi richiedono la Terminal password (TranzilaPW). Alcuni terminali richiedono anche una password di credito separata; inseriscila in Refund password (CreditPass). Gli ordini pagati su un altro terminale vanno rimborsati in quel terminale.

Other currencies: il plugin supporta ILS, USD, EUR e GBP. Gli sviluppatori possono modificare l'elenco con il filtro tranzila_p_currency_map.

The license block shows an error: 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 clicca su Check now. Se l'indirizzo del sito è cambiato, clicca 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 nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, i dati Tranzila memorizzati sugli ordini e i registri del plugin (inclusi i file di log ruotati) vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le note di pagamento e gli ID di transazione.

Tranzila è un marchio di proprietà dei rispettivi titolari. Questo plugin non è affiliato a Tranzila né approvato da Tranzila.