VibeFox TrustPay 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.

Account finby (TrustPay): ti serve un progetto nel Merchant Portal di finby 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 negozio da internet. Un firewall, un accesso di manutenzione o l'autenticazione HTTP davanti al negozio bloccano le notifiche di pagamento.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento fai clic su Configure, oppure cerca più tardi VibeFox TrustPay Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in cima alla pagina Configure e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci il Project ID e la Secret key del tuo progetto di test e, per i pagamenti reali, quelli del tuo progetto live (vedi Configurazione).

5. Attiva Enable / Disable e fai clic su Save. Effettua un pagamento di prova con Test mode attivo, poi disattiva Test mode per accettare pagamenti reali.

All'installazione il modulo crea due stati dell'ordine, Awaiting TrustPay payment e TrustPay payment on hold. PrestaShop collega un nuovo modulo di pagamento ai paesi attivi al momento dell'installazione. Per i paesi che aggiungi in seguito, spunta il modulo in Payment > Preferences. Lì puoi anche limitare il modulo per valuta e gruppo di clienti.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox TrustPay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa quando il modulo è attivo ma il Project ID o la Secret key della modalità corrente sono vuoti, e quando la valuta predefinita del negozio non è supportata. In entrambi i casi il metodo di pagamento viene nascosto al checkout.

TrustPay / finby

Enable / Disable: Enable TrustPay / finby card payments attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Card payment (TrustPay). Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely by card on the TrustPay / finby payment page.

Credenziali API

Copia il Project ID e la Secret key del tuo progetto dal Merchant Portal di finby (TrustPay). 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: usa il progetto di test (nessun pagamento reale). I nuovi pagamenti e rimborsi usano le credenziali di test. I rimborsi di un ordine vengono sempre effettuati sul progetto con cui l'ordine è stato pagato. Predefinito: on. Finché è attivo, i clienti vedono Test mode: no real payment will be taken. sotto il metodo di pagamento.

Live Project ID: il Project ID numerico del tuo progetto live.

Live Secret key: la Secret key del progetto live. Serve 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.

Un Project ID deve contenere solo cifre. Se salvi un altro valore, la pagina mostra must contain digits only — the previous value was kept. e gli altri campi vengono salvati. Le Secret key vengono salvate esattamente come le inserisci; vengono rimossi solo gli spazi all'inizio e alla fine. Le Secret key salvate non vengono più mostrate. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo. Salvare le impostazioni elimina anche i token di accesso alle API in cache, così le nuove credenziali vengono usate subito.

Clear saved secrets: spunta una Secret key e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Notifiche di pagamento

L'ordine viene segnato come pagato solo quando finby lo conferma con una notifica firmata. Il modulo invia automaticamente l'URL di notifica con ogni pagamento, quindi non devi configurarlo. La sezione mostra l'URL sotto Notification URL. Con gli URL SEO appare così: https://your-shop/module/wcp_trustpay_gateway/callback, eventualmente con un codice lingua. Puoi anche inserirlo come URL di notifica dei tuoi progetti nel Merchant Portal. Le notifiche senza una firma valida vengono rifiutate.

Il modulo non chiede a finby lo stato del pagamento di propria iniziativa. Se una notifica non riesce a raggiungere il tuo negozio, nessun ordine viene creato finché finby non la consegna. finby ripete le notifiche.

Avanzate

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: aggiunge le richieste API e le notifiche a logs/trustpay_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche quando questa opzione è disattivata. Il registro non contiene chiavi, token, dati della carta né dati dei clienti. Predefinito: off.

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

Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni del modulo e il registro. I dati degli ordini vengono conservati: ordini, registrazioni dei pagamenti TrustPay e rimborsi, e gli stati degli ordini. Predefinito: off.

Checkout

Al passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Card payment (TrustPay)) e conferma l'ordine. Il metodo di pagamento viene offerto solo nelle valute supportate: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF e USD. Gli importi in HUF vengono inviati senza decimali.

I pagamenti con carta richiedono un indirizzo. 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 modulo crea presso finby una richiesta di pagamento con carta per il totale del carrello nella valuta del carrello. Nome, indirizzo ed e-mail del cliente vengono inviati per 3-D Secure, e il numero del carrello viene inviato come riferimento. A questo punto l'ordine non esiste ancora. Il cliente viene reindirizzato alla pagina di pagamento di finby e paga con la carta. La pagina si apre nella lingua del carrello, quando finby la supporta, altrimenti in inglese.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando finby lo conferma con la notifica firmata. Il ritorno in sé non cambia mai lo stato del pagamento. Se la notifica è già arrivata, il cliente vede la normale pagina di conferma dell'ordine. In caso contrario appare una pagina Payment confirmation, che indica che finby sta confermando il pagamento con carta e che l'ordine verrà creato non appena sarà confermato. Ha un pulsante Check again e un pulsante Back to checkout. Finché l'ordine è in Awaiting TrustPay payment o TrustPay payment on hold, la pagina di conferma mostra Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Se finby ha rifiutato il pagamento o l'ordine non pagato è stato annullato, mostra Your card payment was not completed. Please contact us about this order.

Se il cliente annulla nella pagina di pagamento, torna al checkout con il messaggio The card payment was cancelled. You can try again or choose another payment method. Se la pagina di pagamento restituisce un errore, oppure finby ha già rifiutato il pagamento, il messaggio è The card payment was not completed. Please try again or choose another payment method. Il carrello viene conservato e il cliente può pagare di nuovo.

Se finby non riesce ad avviare il pagamento, il cliente resta al checkout con il messaggio 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.

La notifica funziona anche quando il negozio è in modalità manutenzione e non viene bloccata dalla restrizione per paese del tuo negozio.

Il modulo accetta solo pagamenti con carta, come acquisto in un unico passaggio sulla pagina di finby. Non prevede bonifici bancari né altri metodi di pagamento finby, pulsanti Apple Pay o Google Pay sul tuo sito, carte salvate, abbonamenti o pagamenti ricorrenti, autorizzazione e acquisizione separate, né verifica dello stato.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato reindirizzato a finby e non ha pagato, oppure la notifica non è ancora arrivata. Esiste solo il carrello.

Payment accepted or Delivered: finby ha confermato il pagamento, e importo e valuta corrispondono alla richiesta di pagamento e al totale del carrello. Lo stato segue Order status after payment. Il pagamento viene registrato con l'ID della richiesta di pagamento finby come ID transazione, e una nota mostra l'importo, la richiesta di pagamento e il progetto (test o live).

Awaiting TrustPay payment: finby ha segnalato che l'ultimo pagamento è in attesa. L'ordine passa allo stato pagato quando finby conferma il pagamento.

TrustPay payment on hold: viene impostato in due casi. Il pagamento è stato solo autorizzato, non acquisito: acquisiscilo o annullalo nel Merchant Portal di finby, poi aggiorna l'ordine. Oppure l'importo o la valuta pagati differiscono dalla richiesta di pagamento o dal totale del carrello, ad esempio perché il carrello è stato modificato dopo che il cliente è stato reindirizzato alla pagina di pagamento: verifica il pagamento prima della spedizione. La nota spiega il caso.

Payment error: finby ha rifiutato l'ultimo pagamento di un ordine in attesa. La nota mostra il motivo quando finby lo invia. Un pagamento confermato successivamente porta comunque l'ordine allo stato pagato.

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

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. Gli storni e le contestazioni segnalati da finby vengono aggiunti come note.

Blocco di pagamento TrustPay / finby

La pagina dell'ordine mostra un blocco TrustPay / finby payment con l'ID della richiesta di pagamento, l'ID del pagamento finby, il progetto, lo stato del pagamento, gli importi richiesto e pagato, l'importo rimborsato, un badge Test project per i pagamenti di prova, la cronologia dei rimborsi e le TrustPay notes dell'ordine.

Rimborsi

Nel blocco TrustPay / finby payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via TrustPay. Conferma la domanda Refund this amount through TrustPay? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il diritto di modificare gli ordini; non è necessario l'accesso alle pagine Moduli. I rimborsi vengono effettuati nell'importo e nella valuta che finby ha indicato per il pagamento, quindi, dopo una differenza di importo, puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. I rimborsi in HUF devono essere importi interi.

Il rimborso va al progetto con cui l'ordine è stato pagato (test o live), anche se nel frattempo hai cambiato modalità. Per quel progetto devono essere impostati Project ID e Secret key, e il suo Project ID non deve essere cambiato. Un rimborso viene registrato solo quando finby lo accetta. Altrimenti il blocco mostra TrustPay refused the refund: con il motivo, e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e alle note. 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 finby. I rimborsi effettuati nel Merchant Portal di finby non vengono registrati come rimborsi. Se finby invia una notifica al riguardo, viene aggiunta come nota e lo stato dell'ordine non cambia.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox TrustPay Gateway è il primo blocco di Modules > Module Manager > VibeFox TrustPay Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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 si trovano la riga Product: presta-payment-trustpay 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, ad esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on con 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 dominio: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il pagamento con carta 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. Lo storefront 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 testarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati dalla notifica TrustPay e dal ritorno al negozio, e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene verificato 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 alla 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

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 suo Project ID e la sua 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 carrello deve essere una delle valute supportate. La pagina delle impostazioni mostra un avviso quando le credenziali mancano o la valuta predefinita non è supportata. In Payment > Preferences verifica 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 ha raggiunto il tuo negozio. Verifica che l'URL mostrato sotto Notification URL sia raggiungibile da internet (nessun firewall, accesso di manutenzione o autenticazione HTTP). finby ripete la notifica e l'ordine viene creato quando arriva. Attiva Debug logging e controlla il campo Log nella pagina del modulo.

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 non viene modificato nulla. Verifica il Project ID e la Secret key della modalità in cui è stato effettuato il pagamento.

Il registro mostra Notification ignored: la notifica riguarda una richiesta di pagamento che questo negozio non ha creato per quel carrello, oppure un altro progetto o una modalità diversa da quella con cui il pagamento è stato avviato. Non viene modificato nulla.

La notifica riceve la risposta Busy, retry later o Temporary error: il carrello era in aggiornamento da parte di un'altra notifica nello stesso momento, oppure non è stato possibile creare l'ordine (ad esempio perché il modulo è disattivato). finby la ripete. Il registro mostra il motivo.

Il cliente vede We could not start the card payment: apri il registro. Un Project ID o una Secret key errati producono un messaggio che indica che finby ha rifiutato le credenziali del progetto. Verifica che le credenziali di test siano nei campi di test e quelle live nei campi live.

Card payment is temporarily unavailable: il cliente vede questo messaggio quando la modalità corrente non ha Project ID o Secret key. Inseriscili e salva.

L'ordine è in TrustPay payment on hold: leggi le note nel blocco TrustPay / finby payment (vedi Stati dell'ordine). Verifica il pagamento nel Merchant Portal prima della spedizione, poi evadi l'ordine o rimborsa il pagamento.

Il rimborso fallisce con un messaggio sul progetto: l'ordine è stato pagato tramite il progetto di test o quello 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 o rimborsa il pagamento nel Merchant Portal di finby.

Invalid refund amount: at most … can be refunded: l'importo è superiore all'importo pagato meno i rimborsi già effettuati tramite il modulo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox TrustPay Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. I token di accesso alle API in cache vengono sempre rimossi. Se Delete data on uninstall è attivo, vengono rimosse le impostazioni del modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le registrazioni dei pagamenti TrustPay e i rimborsi, e gli stati degli ordini Awaiting TrustPay payment e TrustPay payment on hold, vengono sempre conservati, così gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID di transazione.

TrustPay e finby sono marchi dei rispettivi titolari. Questo modulo non è affiliato né approvato da TrustPay o finby.