VibeFox TrustPay for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
PHP: 8.0 o successivo.
Account finby (TrustPay): ti serve un progetto nel finby Merchant Portal con il suo Project ID e la sua Secret key. Per i pagamenti di prova ti serve un progetto di test (playground) separato, con il proprio Project ID e la propria Secret key. Non servono altre chiavi: la Secret key viene usata sia per ottenere l'accesso alle API sia per verificare la firma delle notifiche di pagamento.
URL di notifica raggiungibile: finby deve poter raggiungere il tuo sito da internet. Un firewall, la modalità di manutenzione o la protezione con password del sito bloccano le notifiche di pagamento.
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 fai clic su Install Now. Puoi anche caricare la cartella wcp_trustpay_gateway in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > TrustPay / finby, 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 Project ID e la Secret key del tuo progetto live e, per i test, quelli del tuo progetto di test (vedi Configurazione).
6. Attiva Enable / Disable e salva. Effettua un pagamento di prova con Test mode attivo, poi disattiva Test mode per accettare pagamenti reali.
Quando aggiorni dalla versione 1.0, il tuo Project ID e la tua Secret key restano come credenziali live e la modalità test viene disattivata. Controlla le impostazioni dopo l'aggiornamento.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > TrustPay / finby. Sopra i campi, la pagina ti avvisa quando il gateway è attivo ma il Project ID o la Secret key della modalità corrente sono vuoti, e quando la valuta del negozio non è supportata. In entrambi i casi il metodo di pagamento viene nascosto al checkout. Nell'elenco dei metodi di pagamento, il gateway risulta da configurare finché la modalità corrente non ha il proprio Project ID e la propria Secret key.
General
Enable / Disable: Enable TrustPay / finby card payments attiva o disattiva il metodo di pagamento. Predefinito: disattivo.
Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: Card payment (TrustPay).
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely by card on the TrustPay / finby payment page.
API credentials
Copia il Project ID e la Secret key del tuo progetto dal finby (TrustPay) Merchant Portal. La sezione contiene un link al Merchant Portal. I pagamenti di prova usano un progetto di test (playground) separato, con il proprio Project ID e la propria Secret key. Lì non viene addebitato denaro reale.
Test mode: Use the test project (no real payments). I nuovi pagamenti e i rimborsi usano le credenziali di test. I rimborsi di un ordine vengono sempre effettuati sul progetto con cui l'ordine è stato pagato. Predefinito: attivo.
Live Project ID: il Project ID numerico del tuo progetto live.
Live Secret key: la Secret key del progetto live. Viene usata per ottenere i token di accesso alle API e per verificare le notifiche di pagamento.
Test Project ID: il Project ID numerico del tuo progetto di test (playground).
Test Secret key: la Secret key del progetto di test.
Il Project ID deve contenere solo cifre. Se salvi un altro valore, la pagina mostra un errore e resta il valore precedente. Le Secret key vengono salvate esattamente come le inserisci; vengono rimossi solo gli spazi iniziali e finali.
Payment notifications
L'ordine viene segnato come pagato solo dopo che finby conferma il pagamento con una notifica firmata. Il plugin invia automaticamente l'URL di notifica con ogni pagamento, quindi non devi configurarlo. La sezione mostra l'URL, per esempio https://your-site/wc-api/trustpay_payment_callback/. Puoi anche inserirlo come URL di notifica dei tuoi progetti nel Merchant Portal. Le notifiche senza firma valida vengono rifiutate.
Il plugin non chiede da solo a finby lo stato del pagamento. Se una notifica non riesce a raggiungere il tuo sito, l'ordine resta in Pending payment finché finby non la consegna.
Advanced
Order status after payment: lo stato dell'ordine impostato dopo un pagamento riuscito. Lo stato viene impostato in un unico passaggio, così il cliente riceve una sola e-mail.
Debug logging: Log API requests and notifications aggiunge dettagli al registro. Gli errori vengono sempre registrati, anche quando questa opzione è disattivata. I registri si trovano in WooCommerce > Status > Logs, origine wcp_trustpay_gateway, e non contengono chiavi, token, dati della carta né dati dei clienti. Predefinito: disattivo.
Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (order data is kept). Predefinito: disattivo.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Card payment (TrustPay)) e invia l'ordine. In modalità test il checkout mostra Test mode: no real payment will be taken. sotto la descrizione.
I pagamenti con carta richiedono l'indirizzo di fatturazione. Se mancano via, città, CAP o paese, il cliente vede Please enter your billing address (street, city, postcode and country) — it is required for card payments.
Il plugin crea una richiesta di pagamento con carta presso finby per il totale dell'ordine nella valuta dell'ordine. Nome, indirizzo e e-mail del cliente vengono inviati per 3-D Secure, e l'ID dell'ordine viene inviato come riferimento. Il cliente viene reindirizzato alla pagina di pagamento di finby e paga con la carta lì. La pagina si apre nella lingua del tuo negozio, quando finby la supporta, altrimenti in inglese. Una nota sull'ordine mostra la richiesta di pagamento, l'importo e il progetto (test o live).
Dopo il pagamento, il cliente torna alla pagina di conferma ordine del tuo negozio e il carrello viene svuotato. L'ordine viene segnato come pagato solo quando finby lo conferma con la notifica firmata. Il ritorno in sé non modifica mai lo stato del pagamento.
Se il cliente annulla nella pagina di pagamento, o se la pagina di pagamento restituisce un errore, il cliente torna alla pagina Pay for order con il messaggio The card payment was cancelled. You can try again or choose another payment method. oppure The card payment was not completed. Please try again or choose another payment method. Viene aggiunta una nota all'ordine. Il cliente può pagare di nuovo da quella pagina.
Se finby non riesce ad avviare il pagamento, il cliente vede We could not start the card payment. Please try again in a moment or choose another payment method. Il motivo tecnico viene scritto nel registro.
Valute: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF e USD. Gli importi in HUF vengono inviati senza decimali. Nella pagina Pay for order viene verificata la valuta dell'ordine.
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 include traduzioni in inglese, slovacco e ceco.
Il plugin accetta solo pagamenti con carta, come acquisto in un unico passaggio nella pagina di finby. Non prevede bonifici bancari né altri metodi di pagamento finby, pulsanti Apple Pay o Google Pay, carte salvate, abbonamenti o pagamenti ricorrenti, autorizzazione e acquisizione separate, né verifica dello stato.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a finby e non ha ancora pagato, oppure la notifica non è ancora arrivata.
Processing or Completed: finby ha confermato il pagamento, e importo e valuta corrispondono alla richiesta di pagamento e al totale dell'ordine. Lo stato segue Order status after payment. La nota dell'ordine mostra importo, richiesta di pagamento e progetto. L'ID transazione è l'ID della richiesta di pagamento finby.
On hold: viene impostato in tre casi. Il pagamento è ancora in sospeso presso finby e l'ordine attende l'esito finale. Il pagamento è stato solo autorizzato, non acquisito: acquisiscilo o annullalo nel finby Merchant Portal, poi aggiorna l'ordine. Oppure l'importo o la valuta pagati differiscono dalla richiesta di pagamento o dal totale dell'ordine, per esempio perché l'ordine è stato modificato dopo l'invio del cliente alla pagina di pagamento: verifica il pagamento prima della spedizione. La nota dell'ordine spiega il caso.
Failed: finby ha rifiutato l'ultimo pagamento dell'ordine. La nota mostra il motivo quando finby lo invia. Il cliente può pagare di nuovo da Pay for order.
Gli ordini annullati o rimborsati non vengono mai riaperti da un pagamento tardivo. Una nota ti chiede di ripristinare l'ordine o di rimborsare il pagamento nel Merchant Portal. Se arriva un secondo pagamento per un ordine già pagato, l'ordine non viene modificato e una nota ti chiede di rimborsare il duplicato nel Merchant Portal. Chargeback e contestazioni segnalati da finby vengono aggiunti come note.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Card payment (TrustPay) (il pulsante mostra il tuo Title). Sono supportati rimborsi totali e parziali. Il rimborso viene inviato al progetto con cui l'ordine è stato pagato (test o live), anche se nel frattempo hai cambiato modalità, quindi il Project ID e la Secret key di quella modalità devono essere impostati. I rimborsi in HUF devono essere importi interi.
Un rimborso viene registrato solo quando finby lo accetta. Altrimenti WooCommerce mostra TrustPay refused the refund: con il motivo, e nessun rimborso viene creato. Un rimborso riuscito viene aggiunto alle note dell'ordine.
I rimborsi effettuati nel finby Merchant Portal non vengono registrati come rimborsi WooCommerce. Se finby invia una notifica su di essi, viene aggiunta come nota dell'ordine e lo stato dell'ordine non cambia.
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 > TrustPay / finby. 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 controllare 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. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, il metodo di pagamento 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 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 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 controllato di nuovo automaticamente in background.
Risoluzione dei problemi
Card payment (TrustPay) non compare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che la modalità corrente abbia il Project ID e la Secret key: Test Project ID e Test Secret key in modalità test, Live Project ID e Live Secret key in modalità live. La valuta del negozio, o la valuta dell'ordine nella pagina Pay for order, deve essere una delle valute supportate. La pagina delle impostazioni mostra un avviso in entrambi i casi. Gli sviluppatori possono modificare l'elenco delle valute con il filtro trustpay_p_supported_currencies.
Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: la notifica non è arrivata al tuo negozio. Verifica che https://your-site/wc-api/trustpay_payment_callback/ sia raggiungibile da internet (nessun firewall, modalità di manutenzione o protezione con password). finby ripete la notifica. Controlla WooCommerce > Status > Logs, origine wcp_trustpay_gateway.
Il registro mostra Notification rejected: invalid signature or unknown project: la notifica proviene da un progetto il cui Project ID non è nelle impostazioni, oppure la Secret key di quel progetto è errata. Il negozio risponde Invalid signature e l'ordine non viene modificato. Verifica il Project ID e la Secret key della modalità in cui è stato effettuato il pagamento.
Il registro mostra Notification ignored: la notifica appartiene a una richiesta di pagamento che questo negozio non ha creato per quell'ordine, oppure a un progetto diverso da quello con cui il pagamento è stato avviato. L'ordine non viene modificato.
La notifica riceve la risposta Busy, retry later: l'ordine era in aggiornamento da parte di un'altra notifica nello stesso momento. finby la ripete.
Il cliente vede We could not start the card payment: apri il registro. Un Project ID o una Secret key errati producono un messaggio secondo cui finby ha rifiutato le credenziali del progetto. Verifica che le credenziali di test siano nei campi di test e quelle live nei campi live.
Il pagamento con carta è temporaneamente non disponibile: il cliente vede questo messaggio quando la modalità corrente non ha Project ID o Secret key. Inseriscili e salva.
L'ordine è On hold con una nota di differenza di importo o valuta: la notifica era autentica, ma l'importo o la valuta pagati differiscono dalla richiesta di pagamento o dal totale dell'ordine. Verifica il pagamento nel Merchant Portal prima della spedizione, poi evadi l'ordine o rimborsa il pagamento.
Il rimborso non riesce con un messaggio sul progetto: l'ordine è stato pagato tramite il progetto di test o live, e il Project ID o la Secret key di quella modalità non sono impostati, oppure ora è salvato un altro Project ID. Inserisci le credenziali di quel progetto, oppure rimborsa il pagamento nel finby Merchant Portal.
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 della licenza di questo plugin, così come i token di accesso alle API in cache, vengono sempre rimossi. Le impostazioni del gateway e i registri del plugin (file di log, inclusi i vecchi file ruotati, e voci di log nel database) vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti vengono conservati per una eventuale reinstallazione. I dati degli ordini vengono conservati: gli ordini esistenti mantengono le note di pagamento, gli ID delle richieste di pagamento e gli ID delle transazioni.
TrustPay e finby sono marchi dei rispettivi proprietari. Questo plugin non è affiliato a TrustPay o finby né approvato da essi.