VibeFox Tpay 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. Per la verifica della firma JWS delle notifiche servono l'estensione OpenSSL e le connessioni HTTPS in uscita verso secure.tpay.com.

Valuta del negozio: solo zloty polacco (PLN). Tpay regola i pagamenti in PLN e la sua Open API non ha un campo per la valuta, quindi il metodo di pagamento viene nascosto quando il carrello usa un'altra valuta.

Accesso a Internet al tuo negozio: Tpay invia le notifiche di pagamento al tuo negozio, quindi l'indirizzo di notifica deve essere raggiungibile da Internet (non bloccato da un firewall o dall'autenticazione HTTP).

Account Tpay: ti servono questi valori dal pannello commerciante di Tpay: il Merchant ID (l'ID del tuo account Tpay), le chiavi Open API Client ID e Client secret (Integration, API) e il codice di sicurezza (Settings, Notifications). Le chiavi sandbox provengono da un account sandbox Tpay separato.

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 più tardi VibeFox Tpay Payment 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 fai clic su Activate (vedi Chiave di licenza).

4. Inserisci le chiavi Sandbox e le chiavi Production (vedi Configuration). Nel pannello Tpay non serve impostare nulla tranne il codice di sicurezza: l'indirizzo di notifica viene inviato con ogni transazione.

5. Attiva Enable/Disable e clicca su Save. Prova un pagamento in modalità sandbox, poi disattiva Sandbox mode per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine Tpay payment on hold. PrestaShop propone un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences; il PLN deve restare consentito per il modulo.

Configuration

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Tpay Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged. finché la modalità sandbox è attiva. Ti avvisa quando le chiavi della modalità corrente sono incomplete (Tpay non viene allora mostrato al checkout), quando la valuta predefinita del negozio non è PLN e quando manca l'estensione OpenSSL di PHP mentre la verifica JWS è attiva (i pagamenti non verrebbero confermati). Gli spazi incollati insieme al Merchant ID o al Client ID vengono rimossi al salvataggio.

Tpay

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

Title: il titolo del metodo di pagamento mostrato ai clienti al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Tpay. Obbligatorio.

Description: la descrizione del metodo di pagamento mostrata ai clienti al checkout. Predefinito: Pay with BLIK, online bank transfer or card on the secure Tpay page.

Sandbox mode: usa la sandbox di Tpay (pagamenti di prova, nessun denaro reale) con le chiavi Sandbox e openapi.sandbox.tpay.com. Disattivalo per accettare pagamenti reali con le chiavi Production. I rimborsi vanno sempre nell'ambiente in cui l'ordine è stato pagato. Predefinito: attivo.

Production keys

Dove trovarle: nel pannello commerciante di Tpay, sotto Integration, API (chiavi Open API: Client ID e Secret); il Merchant ID è l'ID del tuo account Tpay; il codice di sicurezza si trova in Settings, Notifications.

Merchant ID: l'ID del tuo account Tpay (cifre). Tpay lo invia in ogni notifica.

Client ID: l'Open API Client ID.

Client secret: l'Open API Client secret.

Security code: serve a verificare la somma di controllo MD5 delle notifiche Tpay.

Sandbox keys

La sandbox è un account di prova Tpay separato con proprie chiavi (vedi la documentazione dell'API Tpay). Vengono usate solo quando Sandbox mode è attivo.

Sandbox Merchant ID: il Merchant ID dell'account sandbox.

Sandbox Client ID: l'Open API Client ID dell'account sandbox.

Sandbox Client secret: l'Open API Client secret dell'account sandbox.

Sandbox Security code: il codice di sicurezza delle notifiche dell'account sandbox.

I segreti salvati (Client secret e Security code di entrambi gli ambienti) non vengono 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: spunta un segreto e clicca su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Payment notifications

Notification URL: Tpay conferma i pagamenti all'indirizzo mostrato qui. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_tpay_payment/notify, eventualmente con un codice lingua come /en/. L'indirizzo viene inviato automaticamente con ogni transazione; nel pannello Tpay va impostato solo il codice di sicurezza. Un ordine viene creato solo dopo una notifica con somma di controllo e firma valide e importo corrispondente (oppure dopo una verifica dello stato corrispondente quando il cliente torna al negozio). Tpay ripete una notifica finché il tuo negozio non la accetta.

JWS signature: verifica anche la X-JWS-Signature delle notifiche con il certificato Tpay (consigliato). Richiede l'estensione OpenSSL di PHP e le connessioni HTTPS in uscita verso secure.tpay.com. I certificati vengono memorizzati nella cache per un giorno. La somma di controllo MD5 viene sempre verificata. Predefinito: attivo.

Advanced

Debug log: registra gli eventi di pagamento: solo eventi tecnici (nessuna chiave, nessun dato del cliente) in logs/wc_tp_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Predefinito: disattivato. Finché è disattivato non viene scritto nulla, errori compresi; attivalo quindi prima di cercare la causa di un problema.

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

Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le sue impostazioni e il registro. Gli ordini e i loro dati di pagamento Tpay vengono sempre conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Tpay). In modalità sandbox l'opzione di pagamento mostra Sandbox mode - no real money is charged. Dopo la conferma, il modulo crea una transazione Tpay per il totale del carrello in PLN con la descrizione Cart # e il numero del carrello, passa nome, e-mail, indirizzo di fatturazione e telefono del cliente, e invia il cliente alla pagina di pagamento Tpay. La pagina viene mostrata in polacco, inglese o ucraino, in base alla lingua del negozio (le altre lingue ricevono l'inglese). Lì il cliente sceglie BLIK, un bonifico bancario, una carta o un altro metodo attivato sul tuo account Tpay, e paga. A questo punto non esiste ancora alcun ordine.

L'ordine viene segnato come pagato solo dopo la conferma di Tpay. Tpay invia una notifica al tuo negozio; il modulo verifica la somma di controllo MD5 con il codice di sicurezza, il Merchant ID e (se attiva) la firma JWS, usando le chiavi dell'ambiente in cui è stato avviato il pagamento, e poi l'importo: deve essere uguale all'importo richiesto per questo tentativo di pagamento e al totale del carrello, e l'importo pagato non può essere inferiore. Le notifiche senza somma di controllo o firma valide vengono rifiutate. Poi l'ordine viene creato e il cliente riceve la normale pagina di conferma dell'ordine.

Dopo il pagamento il cliente torna nel tuo negozio. Il solo ritorno non segna nulla come pagato. Se la notifica non è ancora arrivata, il modulo chiede all'API Tpay lo stato della transazione (al massimo ogni 10 secondi) e applica gli stessi controlli. Finché il pagamento non è confermato, una pagina Payment confirmation mostra Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again: con un pulsante Refresh e un pulsante Pay again che riporta al checkout. La notifica crea l'ordine non appena arriva.

Se Tpay segnala che il pagamento non è andato a buon fine, il cliente torna al checkout con il messaggio Tpay reports that the payment did not go through. Please try again or choose another payment method. Se il pagamento fallisce sulla pagina di Tpay, Tpay rimanda il cliente alla pagina del checkout. Il carrello viene conservato in entrambi i casi. Se l'ordine è stato messo in attesa, la pagina di conferma mostra Your payment is being verified. We will contact you as soon as it is confirmed.

Ogni tentativo di pagamento ha un proprio riferimento. Quando il cliente paga di nuovo, le transazioni Tpay precedenti non pagate del carrello vengono annullate presso Tpay; un pagamento già effettuato tramite un link precedente viene comunque accettato. Se il carrello ha già un ordine, il cliente va alla pagina di conferma di quell'ordine invece di avviare un nuovo pagamento.

Se Tpay non riesce ad avviare il pagamento, il cliente resta al checkout con il messaggio The Tpay payment could not be started. Please try again or choose another payment method. e il motivo viene scritto nel registro (quando Debug log è attivo).

L'indirizzo di notifica funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo funziona solo in PLN. Nel negozio non c'è la scelta della banca o del codice BLIK (il cliente sceglie sulla pagina Tpay), né carte salvate, abbonamenti, pulsanti Apple Pay o Google Pay nel negozio e calcolatori di rate.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Tpay e non ha pagato, oppure Tpay non ha ancora confermato il pagamento. Esiste solo il carrello. Un pagamento non riuscito non crea alcun ordine.

Payment accepted: Tpay ha confermato il pagamento. Il pagamento viene registrato con il titolo della transazione Tpay (TR-...) come ID transazione. Una nota indica se è stato confermato dalla notifica o dalla verifica dello stato, l'ambiente e un eventuale pagamento in eccesso.

Tpay payment on hold: è arrivato un pagamento, ma il suo importo era diverso da quello richiesto o dal totale del carrello (per esempio, il carrello è stato modificato dopo l'avvio del pagamento), è stata pagata solo una parte, oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota lo spiega. Controlla il pagamento nel pannello Tpay, poi evadi o rimborsa l'ordine. Se il cliente paga poi l'importo corretto con un nuovo tentativo, l'ordine passa a Payment accepted.

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

Se Tpay segnala un altro pagamento per un ordine già pagato o rimborsato, l'ordine non viene modificato; una nota ti chiede di rimborsare il pagamento in più dal pannello Tpay, se necessario. Un addebito contestato (chargeback) segnalato da Tpay aggiunge una nota.

Blocco pagamento Tpay

La pagina dell'ordine mostra un blocco Tpay payment con il titolo e l'ID della transazione Tpay, il riferimento del pagamento (CRC), l'ambiente (con l'etichetta Sandbox per i pagamenti sandbox), lo stato del pagamento e come è stato confermato, l'importo pagato, il totale dell'ordine e l'importo rimborsato, lo storico dei rimborsi, tutti i Payment attempts del carrello e le Payment notes dell'ordine.

Rimborsi

Nel blocco Tpay payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Tpay. Conferma la domanda Refund this amount through Tpay? This cannot be undone. Sono supportati rimborsi totali e parziali per ordini con un pagamento ricevuto tramite Tpay, anche per gli ordini in attesa. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine Modules. Puoi rimborsare fino all'importo incassato dalla transazione Tpay che ha effettuato il pagamento, al massimo il totale dell'ordine: dopo un pagamento parziale o un carrello modificato il blocco mostra Refundable (paid through Tpay). Il rimborso viene inviato all'ambiente (sandbox o produzione) in cui l'ordine è stato pagato, quindi devono essere impostate le chiavi di quell'ambiente. Il rimborso si considera eseguito solo quando Tpay lo conferma; un rimborso rifiutato o non confermato da Tpay viene mostrato come errore e non viene registrato. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note, insieme al motivo che hai inserito (il motivo non viene inviato a Tpay). Il rimborso dell'intero importo rimborsabile 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 Tpay. I rimborsi effettuati nel pannello commerciante di Tpay non vengono aggiunti automaticamente in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Tpay Payment è il primo blocco di Modules > Module Manager > VibeFox Tpay Payment > Configure, sopra le impostazioni. Incolla la chiave in License key e fai clic 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 verificare 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-tpay 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 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il relativo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Tpay 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. La vetrina di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo nel checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati 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

Tpay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che siano inserite tutte e quattro le chiavi della modalità corrente (Merchant ID, Client ID, Client secret, Security code). Verifica che la valuta del carrello sia PLN e che il modulo sia consentito per PLN, per il paese del cliente e per il gruppo del cliente in Payment > Preferences. La pagina delle impostazioni mostra un avviso per le chiavi mancanti e per una valuta del negozio diversa da PLN.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: Tpay non è riuscito a consegnare la notifica oppure la notifica è stata rifiutata. Attiva Debug log e controlla il campo Log nella pagina del modulo. Le cause più comuni sono un codice di sicurezza o un Merchant ID errati per l'ambiente del pagamento, un indirizzo di notifica bloccato (firewall, autenticazione HTTP) oppure un server senza OpenSSL o senza HTTPS in uscita per la verifica JWS. L'ordine viene creato anche quando il cliente torna nel negozio dopo aver pagato.

Notification answered FALSE - invalid checksum: il Merchant ID o il codice di sicurezza nelle impostazioni non corrispondono all'account Tpay (sandbox o produzione) del pagamento.

Notification answered FALSE - invalid JWS signature: non è stato possibile verificare la firma, per esempio perché manca OpenSSL o perché il certificato Tpay non può essere scaricato. Correggi il server oppure, se necessario, disattiva JWS signature; la somma di controllo MD5 viene comunque verificata.

Notification answered FALSE - busy, retry later or FALSE - order could not be created: il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). Tpay ripete la notifica automaticamente. Attiva Debug log per vedere il motivo.

L'URL di notifica mostra FALSE - POST only in the browser: è normale. L'URL accetta solo notifiche da Tpay.

L'ordine è in Tpay payment on hold: leggi le note nel blocco Tpay payment (vedi Stati dell'ordine), controlla il pagamento nel pannello Tpay, poi evadi l'ordine o rimborsa il pagamento.

Il cliente ha visto The Tpay payment could not be started: le chiavi della modalità corrente sono errate oppure Tpay ha rifiutato la richiesta. Attiva Debug log; il registro mostra l'errore di Tpay.

Il cliente ha visto We could not match this payment to an order: il link di ritorno non apparteneva al carrello del cliente. Se il cliente è stato addebitato, la notifica crea comunque l'ordine; controlla il pannello Tpay.

Il rimborso non riesce: se il messaggio dice che mancano le chiavi, inserisci le chiavi dell'ambiente in cui l'ordine è stato pagato. Se il messaggio dice che l'importo è troppo alto, si può rimborsare al massimo l'importo indicato. Se Tpay non ha confermato il rimborso, controlla la transazione nel pannello commerciante di Tpay prima di riprovare.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Tpay Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. I token di accesso Tpay e i certificati memorizzati nella cache vengono sempre rimossi. Se Delete data on uninstall è attivo, vengono rimosse anche le impostazioni del modulo e il registro. Se è disattivo, le impostazioni vengono conservate per una reinstallazione futura. Le transazioni e i rimborsi Tpay e lo stato dell'ordine Tpay payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID delle transazioni.

Tpay è un marchio registrato del rispettivo titolare. Questo modulo non è affiliato né approvato da Tpay.