VibeFox Tpay for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza WooCommerce.

PHP: 8.0 o successivo. L'estensione OpenSSL e le connessioni HTTPS in uscita verso secure.tpay.com sono necessarie per la verifica della firma JWS delle notifiche.

Valuta del negozio: solo złoty polacco (PLN). Tpay regola i pagamenti in PLN e la sua Open API non ha un campo valuta, quindi il metodo di pagamento viene nascosto quando il negozio (o l'ordine da pagare) usa un'altra valuta.

Accesso a Internet al tuo sito: Tpay invia le notifiche di pagamento al tuo negozio, quindi l'indirizzo di notifica deve essere raggiungibile da Internet (non bloccato dalla modalità manutenzione, 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 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_tpay_payment in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Tpay > 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 le chiavi Sandbox e le chiavi di produzione (vedi Configurazione). Nel pannello Tpay non serve impostare nulla tranne il codice di sicurezza: l'indirizzo di notifica viene inviato con ogni transazione.

6. Attiva Enable/Disable, prova un pagamento in modalità sandbox, poi deseleziona Sandbox mode per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Tpay. 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. Avvisa quando le chiavi della modalità corrente sono incomplete (in tal caso Tpay non viene mostrato al checkout), quando la valuta del negozio non è PLN e quando manca l'estensione PHP OpenSSL mentre la verifica JWS è attiva (i pagamenti non verrebbero confermati). Nell'elenco dei metodi di pagamento, Tpay risulta da configurare finché non vengono inserite le chiavi della modalità corrente. Gli spazi incollati con il Merchant ID o il Client ID vengono rimossi al salvataggio.

Generali

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. Predefinito: Tpay.

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: Use the Tpay sandbox (test payments, no real money). La modalità sandbox usa le chiavi Sandbox e l'API sandbox di Tpay. Disattivala per accettare pagamenti reali con le chiavi di produzione. I rimborsi vanno sempre all'ambiente in cui l'ordine è stato pagato. Predefinito: attivato.

Chiavi di produzione

Dove trovarle: nel pannello commerciante di Tpay, in 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.

Chiavi sandbox

La sandbox è un account di prova Tpay separato con le 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 per le notifiche dell'account sandbox.

Notifiche di pagamento

Tpay conferma i pagamenti all'indirizzo mostrato in questa sezione. Ha questo aspetto: https://your-site/wc-api/wc_tp_payment/. L'indirizzo viene inviato automaticamente con ogni transazione; nel pannello Tpay non serve impostare nulla tranne il codice di sicurezza. Un ordine viene segnato come pagato solo dopo una notifica con somma di controllo e firma valide e con importo corrispondente. Tpay ripete una notifica finché il tuo negozio non la accetta.

Firma JWS: Also verify the X-JWS-Signature of notifications with the Tpay certificate (recommended). Richiede l'estensione PHP OpenSSL e connessioni HTTPS in uscita verso secure.tpay.com. La somma di controllo MD5 viene sempre verificata. Predefinito: attivato.

Avanzate

Debug log: Log payment events. Solo eventi tecnici (nessuna chiave, nessun dato dei clienti) in WooCommerce > Status > Logs, origine wcp_tpay_payment. Predefinito: disattivato.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. La disattivazione non rimuove mai nulla. Gli ordini e i loro dati di pagamento Tpay vengono sempre conservati. Predefinito: disattivato.

Le impostazioni della versione 1.0 vengono trasferite automaticamente: le chiavi usate con la modalità test attiva diventano le chiavi Sandbox.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Tpay) e conferma l'ordine. In modalità sandbox il checkout mostra Sandbox mode — no real money is charged. Il plugin crea una transazione Tpay per il totale dell'ordine in PLN con la descrizione Order # e il numero dell'ordine, passa nome, e-mail, indirizzo e telefono del cliente e reindirizza il cliente alla pagina di pagamento Tpay. La pagina è mostrata in polacco, inglese o ucraino, secondo la lingua del sito (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.

L'ordine viene segnato come pagato solo dopo la conferma di Tpay. Tpay invia una notifica al tuo negozio; il plugin verifica la somma di controllo MD5 con il codice di sicurezza, il Merchant ID e (se attiva) la firma JWS, poi l'importo: deve essere uguale all'importo richiesto per questo tentativo di pagamento e al totale dell'ordine, e l'importo pagato non può essere inferiore. Le notifiche senza somma di controllo o firma valide vengono rifiutate.

Dopo il pagamento il cliente torna alla pagina di ricezione dell'ordine. Il solo ritorno non segna l'ordine come pagato. Se la notifica non è ancora arrivata, la pagina chiede all'API di Tpay lo stato della transazione (al massimo ogni 10 secondi) e applica gli stessi controlli. Finché il pagamento non è confermato, la pagina 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 link Pay again. Quando Tpay segnala un pagamento non riuscito, la pagina mostra Tpay reports that the payment did not go through. You can try again: con lo stesso link. Se il pagamento fallisce sulla pagina di Tpay, Tpay riporta il cliente alla pagina Pay for order dello stesso ordine.

Ogni tentativo di pagamento ha un proprio riferimento. Quando il cliente paga di nuovo, le precedenti transazioni Tpay non pagate dell'ordine vengono annullate presso Tpay; un pagamento già completato tramite un link precedente viene comunque accettato. Lo stesso annullamento avviene quando un ordine non pagato viene annullato, ad esempio per il timeout di blocco scorte di WooCommerce.

Se Tpay non riesce ad avviare il pagamento, il cliente vede The Tpay payment could not be started. Please try again or choose another payment method. e il motivo viene scritto nel log.

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

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

Ordini e rimborsi

Stati dell'ordine

Pending payment: la transazione Tpay è stata creata e il pagamento non è ancora confermato. La nota dell'ordine mostra la transazione Tpay e l'ambiente.

Processing: Tpay ha confermato il pagamento. È lo stato standard di WooCommerce dopo il pagamento (gli ordini con soli prodotti virtuali scaricabili passano a Completato). La nota indica se il pagamento è stato confermato dalla notifica o dalla verifica dello stato e mostra eventuali pagamenti in eccesso. L'ID della transazione è il titolo della transazione Tpay (TR-...).

On hold: è arrivato un pagamento, ma il suo importo era diverso da quello richiesto o dal totale dell'ordine, è stata pagata solo una parte, oppure l'ordine era stato annullato. La nota dell'ordine lo spiega. Controlla il pagamento nel pannello Tpay e completa o rimborsa l'ordine.

Failed: Tpay ha segnalato che il pagamento non è riuscito. Solo un ordine in attesa di pagamento viene segnato come Non riuscito. Il cliente può pagare di nuovo.

Se Tpay segnala un altro pagamento per un ordine già pagato o rimborsato, l'ordine non cambia; una nota ti chiede di rimborsare il pagamento in più nel pannello Tpay, se necessario. Una contestazione (chargeback) segnalata da Tpay aggiunge una nota.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Tpay (il pulsante mostra il tuo Title). Sono supportati rimborsi totali e parziali per gli ordini con un pagamento ricevuto tramite Tpay; per gli ordini non pagati il pulsante non viene mostrato. 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 in WooCommerce. Un rimborso riuscito viene aggiunto alle note dell'ordine, insieme al motivo inserito (il motivo non viene inviato a Tpay).

I rimborsi effettuati nel pannello commerciante di Tpay non vengono aggiunti automaticamente a WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Tpay. 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 lo slot del dominio. Libera lo slot dal 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. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Nella pagina Plugins e nelle pagine di WooCommerce compare un promemoria. 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 supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

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 negozio (o la valuta dell'ordine nella pagina Pay for order) sia PLN. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: Tpay non è riuscito a consegnare la notifica oppure è stata rifiutata. Attiva Debug log e controlla WooCommerce > Status > Logs, origine wcp_tpay_payment. Le cause più comuni sono un codice di sicurezza o un Merchant ID errati per la modalità corrente, un indirizzo di notifica bloccato (modalità manutenzione, firewall, autenticazione HTTP) oppure un server senza OpenSSL o senza HTTPS in uscita per la verifica JWS. La pagina di ricezione dell'ordine controlla anche lo stato quando il cliente torna.

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: la firma non può essere verificata, ad esempio perché manca OpenSSL o il certificato Tpay non può essere scaricato. Correggi il server oppure, se necessario, disattiva JWS signature; la somma di controllo MD5 continua a essere verificata.

L'ordine è On hold: leggi la nota dell'ordine. L'importo pagato non corrispondeva all'ordine, oppure il pagamento è arrivato per un ordine annullato. Controlla il pagamento nel pannello Tpay e completa o rimborsa l'ordine.

Il cliente ha visto The Tpay payment could not be started: le chiavi della modalità corrente sono errate oppure Tpay ha rifiutato la richiesta. Il log mostra l'errore di 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 Tpay non ha confermato il rimborso, controlla la transazione nel pannello commerciante di Tpay prima di riprovare.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Ad 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

La disattivazione del 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, così come i token di accesso Tpay e i certificati in cache. Le impostazioni del gateway e i log vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le proprie note di pagamento, i dati delle transazioni Tpay e gli ID delle transazioni.

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