VibeFox Tranzila for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP più vecchie.

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

Terminale Tranzila: ti serve il nome del terminale. La password del terminale (TranzilaPW) è necessaria per l'handshake e per i rimborsi dalla pagina dell'ordine. 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 tuo terminale o chiedi al supporto Tranzila. Tranzila non ha 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 tuo negozio 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. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure trova in seguito VibeFox Tranzila Payment Gateway nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in alto nella pagina Configure, e clicca su Activate (vedi Chiave di licenza).

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

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

6. Consigliato: attiva l'handshake nel terminale Tranzila, consenti lì l'IP del tuo server, quindi attiva Handshake nel modulo.

7. Attiva Enable/Disable, clicca su Save e prova un pagamento con il terminale di prova Tranzila.

All'installazione il modulo crea lo stato dell'ordine Tranzila payment on hold. PrestaShop assegna a un nuovo modulo di pagamento tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa quando il nome del terminale è vuoto (il metodo di pagamento viene allora nascosto in fase di checkout), quando le notifiche sono disattivate o Trusted IP è vuoto (gli ordini pagati vengono allora messi in sospeso per verifica manuale), quando l'handshake è attivo senza password del terminale (la pagina di pagamento non può essere aperta) e quando la valuta predefinita del negozio non è supportata. Al salvataggio, un nome del terminale non valido, una voce non valida in Trusted IP o un campo numerico che non è un numero intero non vengono salvati: la pagina mostra un errore e resta il valore precedente. Un numero fuori dall'intervallo consentito viene salvato come il valore consentito più vicino, e la pagina te lo segnala.

Tranzila

Enable/Disable: Enable Tranzila Payment Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede in fase di checkout e il titolo della pagina di pagamento. È anche il nome del metodo di pagamento memorizzato nell'ordine. Predefinito: Credit Card (Tranzila).

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

Terminal

Terminal name (supplier): il nome del tuo terminale Tranzila, ad esempio myshop. Solo lettere, cifre, «-» e «_». Finché non viene inserito, il metodo di pagamento non viene mostrato in fase di 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 dalla pagina dell'ordine.

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

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

Clear saved passwords: spunta una password e clicca su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Pagina di pagamento

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

Payment page language: la lingua della pagina Tranzila: Site language, ebraico, inglese, russo, spagnolo, tedesco, francese o giapponese. Predefinito: ebraico. Site language usa la lingua del carrello del cliente se è una di queste lingue, altrimenti l'inglese.

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 sulla pagina di pagamento, fino a 36. 0 o 1 significa nessuna rata. Predefinito: 0. Il terminale deve essere abilitato a elaborare le rate.

Handshake: blocca l'importo con un token di handshake (consigliato). Prima di aprire la pagina di pagamento, il negozio chiede a Tranzila un token monouso legato all'importo, 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 consentito lì. Predefinito: disattivato.

Conferma del pagamento

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

Notifications: conferma automaticamente i pagamenti con le notifiche Tranzila (notify URL). Predefinito: attivo. Quando le notifiche sono disattivate, un cliente che torna da una pagina di pagamento riuscita crea l'ordine nello stato Tranzila payment on hold, e tu confermi il pagamento manualmente dopo aver controllato il terminale Tranzila.

Notification URL: mostrato a scopo informativo. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_tranzila_payment_gateway/notify, eventualmente con un codice lingua. L'URL viene inviato a Tranzila con ogni pagamento, quindi non devi inserirlo 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 aggiornato con il supporto Tranzila. Le notifiche da altri indirizzi vengono rifiutate. Se il campo è vuoto, le notifiche non possono essere verificate: un pagamento riuscito segnalato crea l'ordine nello stato Tranzila payment on hold per la verifica manuale, e un rifiuto segnalato non cambia nulla.

Avanzate

Debug log: registra nel file logs/tranzila_p_debug.log.php, nella cartella del modulo, gli eventi della pagina di pagamento, delle notifiche e dei rimborsi. Il file non può essere aperto dal web. Avvisi ed errori vengono sempre registrati, anche quando questa opzione è disattivata. Password, token e dati dei clienti non vengono mai scritti. Predefinito: disattivato.

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

Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni e i registri. Le transazioni e i rimborsi Tranzila e lo stato dell'ordine Tranzila payment on hold restano sempre, perché i vecchi ordini ne hanno bisogno. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit Card (Tranzila)) e vede la descrizione e la nota After you confirm, you will enter your card details on the secure Tranzila payment page. The order is created once Tranzila confirms the payment. Dopo la conferma, il cliente va su una pagina di pagamento del tuo negozio. Lì si apre la pagina di pagamento Tranzila in un iframe, con il totale del carrello nella valuta del carrello, i dati di fatturazione e un breve elenco dei prodotti. 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 sono consentite le rate, il cliente ne sceglie il numero sulla pagina Tranzila. A questo punto non esiste ancora alcun ordine.

Dopo un pagamento riuscito, Tranzila riporta il cliente indietro e l'intera finestra passa avanti. L'ordine viene segnato come pagato solo dopo che Tranzila lo conferma con una notifica. Se la notifica è già arrivata, il cliente vede la normale pagina di conferma dell'ordine con Your payment with Tranzila has been received. 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 la notifica non è ancora arrivata, una pagina Payment confirmation 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. e un pulsante Check again.

Se il pagamento viene rifiutato o annullato, il cliente torna al checkout 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, ad esempio che la carta è scaduta. Il carrello viene conservato e non viene creato alcun ordine. Ogni volta che la pagina di pagamento viene aperta, si tratta di una nuova pagina di pagamento con un proprio token.

Se la pagina di pagamento non può essere aperta, ad 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 pulsante Choose another payment method. Il motivo tecnico viene scritto nel registro.

La notifica funziona mentre il negozio è in modalità manutenzione e non è bloccata dalla restrizione per paese del tuo negozio. La stessa pagina di pagamento è usata con i temi Classic e Hummingbird.

Il modulo 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

Stati dell'ordine

No order yet: il cliente è stato inviato alla pagina di pagamento e non ha pagato, il pagamento è stato rifiutato oppure la notifica Tranzila non è ancora arrivata. Esiste solo il carrello.

Payment accepted: il pagamento è stato confermato da una notifica verificata. Il pagamento viene registrato con l'indice di transazione Tranzila come ID transazione, e una nota mostra l'importo, la transazione, il numero di autorizzazione e il numero di rate, se ce ne sono.

Tranzila payment on hold: il pagamento è stato segnalato ma non accettato automaticamente: importo, valuta o token di handshake non corrispondevano, 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 spiega il motivo. Controlla il pagamento nel terminale Tranzila e cambia lo stato manualmente.

Refunded: il pagamento è stato rimborsato interamente tramite il modulo.

Se arriva un pagamento per un ordine annullato, l'ordine torna nello stato Payment accepted con una nota che ti chiede di verificare il magazzino prima della spedizione. Se arriva un secondo pagamento per un ordine già pagato o rimborsato, l'ordine non viene modificato. Una nota ti chiede di verificarlo e di rimborsare il duplicato nel terminale Tranzila. Le notifiche ripetute della stessa transazione vengono ignorate.

Blocco pagamento Tranzila

La pagina dell'ordine mostra un blocco Tranzila payment con l'indice di transazione, il numero di autorizzazione, il terminale, lo stato, l'importo pagato e rimborsato, il numero di rate, lo storico dei rimborsi, tutte le Payment pages of the cart con il loro esito e le Tranzila notes dell'ordine.

Rimborsi

Nel blocco Tranzila payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Tranzila. Conferma la domanda Refund this amount via Tranzila? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine dei Moduli. Il rimborso viene effettuato come transazione di credito Tranzila del pagamento originale, sul terminale che lo ha incassato, per l'importo e la valuta che Tranzila ha effettivamente addebitato. Quindi, dopo una discrepanza di importo o valuta, puoi rimborsare fino a quanto il cliente ha realmente pagato, non il totale dell'ordine.

Il modulo è disponibile quando la password del terminale è impostata e l'ordine ha una transazione Tranzila confermata con un numero di autorizzazione. Altrimenti il blocco spiega il motivo, ad esempio Refunds need the terminal password (TranzilaPW) in the gateway settings. Un ordine pagato su un terminale diverso da quello attualmente nelle impostazioni (ad esempio un terminale di prova) non può essere rimborsato dalla pagina dell'ordine; rimborsalo in quel terminale Tranzila.

Se Tranzila non accetta il rimborso, il blocco mostra l'errore, ad esempio Tranzila declined the refund con il codice e il suo significato, e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con la transazione di credito Tranzila. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Tranzila. I rimborsi effettuati nel terminale Tranzila non vengono comunicati al negozio. 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 Tranzila Payment Gateway è il primo blocco di Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché 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 di essi si trovano la riga Product: presta-payment-tranzila 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 oppure License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato un posto dominio nel tuo account, clicca 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto 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. Il front office 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 puoi testarlo al checkout. Un promemoria appare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati dalla notifica Tranzila 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 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 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

Tranzila non compare in fase di checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo, che Terminal name (supplier) sia compilato e che la valuta del carrello sia ILS, USD, EUR o GBP. La pagina delle impostazioni mostra un avviso quando il nome del terminale manca o la valuta predefinita non è supportata. In Payment > Preferences controlla che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: 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 nel registro; guarda il campo Log nella pagina del modulo. Il messaggio secondo cui 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. Gli sviluppatori il cui negozio si trova dietro un reverse proxy attendibile possono impostare l'IP con l'hook actionTranzilaPRemoteIp.

La notifica risponde Forbidden: proviene da un indirizzo IP che non è in Trusted IP.

La notifica risponde Bad request o Not found: il carrello, il token della pagina di pagamento, il terminale o l'indice di transazione nella notifica non corrispondono a nessuna pagina di pagamento di questo negozio.

La notifica risponde Accepted for manual review: Trusted IP è vuoto, quindi la notifica non ha potuto essere verificata. Un pagamento riuscito crea l'ordine in sospeso. Compila Trusted IP per confermare automaticamente i pagamenti.

La notifica risponde Busy, retry: il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure l'ordine non può essere creato (ad esempio perché il modulo è disattivato). Il registro mostra il motivo. Controlla il pagamento nel terminale Tranzila; se lì è approvato e non è stato creato alcun ordine, contatta il cliente o crea l'ordine manualmente.

Alcuni ordini sono in Tranzila payment on hold: leggi le note nel blocco Tranzila payment. Importo, valuta o token di handshake non corrispondevano, oppure la notifica non ha potuto essere verificata (Trusted IP vuoto o notifiche disattivate). Controlla il pagamento nel terminale Tranzila e cambia lo stato manualmente.

La pagina di pagamento non si apre con l'handshake attivo: controlla il nome del terminale e la 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.

I rimborsi non riescono: 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. Se la risposta di Tranzila è inattesa, il blocco segnala che il rimborso non è stato confermato: controlla il terminale Tranzila prima di riprovare.

Altre valute: il modulo supporta solo ILS, USD, EUR e GBP.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Tranzila Payment Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, vengono rimosse le impostazioni e i registri. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le transazioni e i rimborsi Tranzila e lo stato dell'ordine Tranzila payment on hold restano sempre, così gli ordini pagati in precedenza possono essere ancora rimborsati dopo una reinstallazione. Gli ordini esistenti mantengono le loro note di pagamento e gli ID di transazione.

Tranzila è un marchio del suo rispettivo proprietario. Questo modulo non è affiliato né approvato da Tranzila.