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

Valuta: EUR. Paytrail accetta solo euro. Per un carrello in un'altra valuta il metodo di pagamento viene nascosto nel checkout. Gli importi vengono inviati in centesimi.

Accesso a Internet al tuo negozio: Paytrail conferma ogni pagamento con un callback server-to-server, quindi il negozio deve essere raggiungibile da Internet. Senza callback, gli ordini vengono comunque creati quando il cliente torna da Paytrail.

Account Paytrail: ti servono il tuo Merchant ID e la tua Secret key, visibili nel Pannello commerciante di Paytrail (dettagli dell'account o dell'integrazione). Per i test non serve alcun account: la modalità di prova usa l'account di prova pubblico di Paytrail. I metodi di pagamento stessi si abilitano nel tuo account Paytrail.

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 fai clic su Upload a module. Scegli il file ZIP del modulo.

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

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

4. Per provare prima il modulo, attiva Test mode. Per i pagamenti reali, disattivalo e inserisci il tuo Merchant ID e la tua Secret key. Non occorre configurare alcun URL di callback in Paytrail.

5. Attiva Enable/Disable e fai clic su Save.

All'installazione il modulo crea due stati dell'ordine, Awaiting Paytrail payment e Paytrail payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Paytrail Gateway > Configure. Ogni sezione ha un proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Test mode is active. Payments use the public Paytrail test account — no real money is charged. mentre la modalità di prova è attiva. In modalità live avvisa quando mancano il Merchant ID o la Secret key, oppure quando il Merchant ID è l'account di prova pubblico 375917. Avvisa anche quando la valuta del negozio non è EUR. In tutti questi casi Paytrail non viene mostrato nel checkout.

Al salvataggio, un Merchant ID che contiene caratteri diversi dalle cifre non viene salvato: appare l'errore Paytrail merchant ID must contain digits only. The previous value was kept.. Il campo Title non può essere vuoto.

Paytrail

Enable/Disable: Enable Paytrail attiva o disattiva il metodo di pagamento. Predefinito: off.

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

Description: il testo mostrato ai clienti sotto il metodo di pagamento durante il checkout. Predefinito: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

Credenziali API

Il tuo Merchant ID e la tua Secret key sono visibili nel Pannello commerciante di Paytrail (dettagli dell'account o dell'integrazione). La sezione rimanda al Pannello commerciante. Sono supportati solo pagamenti in EUR.

Test mode: usa l'account di prova pubblico di Paytrail (Merchant ID 375917) per i nuovi pagamenti, al posto delle tue credenziali. Non viene addebitato denaro reale e non servono chiavi. I clienti vedono Test mode: no real payment will be made. sotto il metodo di pagamento. La Secret key dell'account di prova è pubblica, quindi chiunque potrebbe simulare un pagamento effettuato in modalità di prova. Non lasciare mai la modalità di prova attiva in un negozio live. Predefinito: off.

Merchant ID: il tuo Merchant ID Paytrail (solo cifre). Viene usato quando la modalità di prova è disattivata.

Secret key: la tua Secret key Paytrail. Viene usata quando la modalità di prova è disattivata. La chiave salvata non viene mai più mostrata. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

Clear saved secret key: spunta Secret key e fai clic su Save per rimuovere la chiave salvata. Un campo vuoto mantiene il valore salvato.

Callback e rimborsi usano sempre le credenziali della modalità in cui è stato effettuato il pagamento, quindi passare dalla prova al live non interrompe gli ordini precedenti.

Ordini

Callback URL: mostra l'URL a cui Paytrail conferma ogni pagamento server-to-server. Con URL semplificati ha questo aspetto: https://your-shop/module/wcp_paytrail_gateway/callback. Viene inviato con ogni pagamento, quindi nel pannello di Paytrail non c'è nulla da configurare, ma il negozio deve essere raggiungibile da Internet.

Order status after payment: lo stato di un ordine pagato.

I pagamenti in sospeso restano in Awaiting Paytrail payment. Le differenze di importo e gli altri problemi vanno sempre in Paytrail payment on hold.

Avanzate

Debug log: registra richieste API e callback in logs/ptg_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Dati personali e chiavi non vengono registrati. Errori e avvisi vengono sempre registrati. 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, la disinstallazione del modulo rimuove le impostazioni e il registro. Disattivare il modulo non cancella nulla. I dati delle transazioni Paytrail degli ordini vengono sempre conservati, perché i rimborsi degli ordini vecchi ne hanno bisogno. Predefinito: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Paytrail) e conferma. Il modulo crea un pagamento Paytrail per il totale del carrello in euro e vi invia le righe dell'ordine: prodotti dopo le regole del carrello, spedizione e confezione regalo, ciascuno con la propria aliquota IVA a una cifra decimale. Le righe corrispondono sempre all'importo del pagamento; una differenza di arrotondamento viene assorbita in una riga oppure inviata come riga Rounding. Gli indirizzi di fatturazione e di consegna vengono inviati solo se completi, e i valori troppo lunghi vengono abbreviati entro i limiti di Paytrail. La lingua della pagina di pagamento è finlandese, svedese o inglese, in base alla lingua del carrello. A questo punto non esiste ancora alcun ordine.

Il cliente viene reindirizzato alla pagina di pagamento Paytrail, sceglie un metodo di pagamento abilitato per il tuo account Paytrail e paga. Paytrail conferma poi il pagamento due volte: rimanda il cliente al tuo negozio e chiama l'URL di callback server-to-server. Entrambe le conferme sono accettate solo con una firma valida creata con le credenziali di quel tentativo di pagamento, e solo per un tentativo creato per quel carrello. L'importo pagato viene confrontato con il totale del carrello. L'ordine viene segnato come pagato solo dopo che Paytrail lo conferma in questo modo. Il modulo gestisce questi stati Paytrail:

Dopo un pagamento riuscito il cliente vede la pagina standard di conferma dell'ordine con Your Paytrail payment has been received. Per un pagamento in sospeso la pagina mostra Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again. Se il callback sta registrando il pagamento proprio in quel momento, una pagina Payment confirmation chiede al cliente di non pagare di nuovo e offre un pulsante Check again.

Dopo un pagamento annullato o non riuscito il cliente torna al checkout con The Paytrail payment was cancelled or failed. You can try again or choose another payment method. Se il pagamento non è ancora concluso, il messaggio è The Paytrail payment has not been completed yet. You can try again or choose another payment method. Il carrello viene conservato. Un ritorno che non può essere verificato mostra Payment verification failed. e non modifica nulla.

Se Paytrail non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, per esempio Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method. (credenziali errate) oppure Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method. Il motivo tecnico viene scritto nel registro. Un totale fuori dai limiti di Paytrail mostra This order total cannot be paid with Paytrail. Please choose another payment method.

Un pagamento Paytrail non può essere annullato tramite API. Ogni nuovo tentativo per il carrello è un nuovo pagamento Paytrail. Se il cliente paga anche una vecchia pagina di pagamento ancora aperta, il secondo pagamento viene segnalato sull'ordine come duplicato da rimborsare.

Il callback funziona mentre il negozio è in modalità manutenzione e non viene bloccato dalla restrizione per paese del tuo negozio.

Il cliente sceglie il metodo di pagamento sulla pagina di Paytrail, non nel tuo checkout. Il modulo non prevede tokenizzazione delle carte né carte salvate, abbonamenti, shop-in-shop, attivazione manuale delle fatture né report di liquidazione.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Paytrail e non ha pagato, oppure Paytrail non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted or Delivered: il pagamento è stato confermato. Lo stato segue Order status after payment. Il pagamento viene registrato con l'ID transazione Paytrail, e una nota mostra la transazione, il metodo di pagamento usato su Paytrail e l'importo.

Awaiting Paytrail payment: il pagamento è in sospeso presso il fornitore (fattura o pagamento differito). L'ordine passa allo stato pagato quando Paytrail conferma il pagamento, oppure a Payment error se fallisce.

Paytrail payment on hold: l'importo pagato è diverso dal totale dell'ordine (viene registrato l'importo effettivamente pagato), il pagamento è arrivato dopo che l'ordine era stato annullato, oppure è stato ricevuto un pagamento di prova mentre il negozio è live (nessun denaro reale, nulla viene registrato). La nota spiega il motivo. Controlla l'ordine, poi gestiscilo o rimborsa il pagamento.

Payment error: un pagamento in sospeso è fallito o è stato annullato.

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

Callback ripetuti o paralleli non creano mai un secondo ordine né note duplicate. Se viene pagato un secondo tentativo di un carrello già pagato, l'ordine non cambia; una nota Duplicate payment ti chiede di rimborsarlo nel Pannello commerciante di Paytrail.

Blocco pagamento Paytrail

La pagina dell'ordine mostra un blocco Paytrail payment con l'ID transazione, la modalità (un badge TEST mode per i pagamenti di prova), il metodo di pagamento, lo stato Paytrail, l'importo pagato e rimborsato, il modulo di rimborso, lo storico dei rimborsi, i tentativi di pagamento del carrello e le Paytrail notes dell'ordine.

Rimborsi

Nel blocco Paytrail payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo per la nota dell'ordine, e fai clic su Refund via Paytrail. Conferma la domanda Refund this amount through Paytrail? This cannot be undone. Sono supportati rimborsi completi e parziali, solo per importo. Ti serve il permesso di modificare gli ordini; l'accesso alle pagine Moduli non è necessario. Puoi rimborsare fino all'importo effettivamente incassato da Paytrail, quindi dopo una differenza di importo il limite è ciò che ha pagato il cliente, non il totale dell'ordine. Il rimborso usa le credenziali della modalità in cui è stato effettuato il pagamento, quindi per un pagamento live devono essere impostate le credenziali live. I rimborsi sono disponibili solo dopo la conferma del pagamento da parte di Paytrail.

Se il metodo di pagamento non supporta i rimborsi diretti, il modulo avvia automaticamente un rimborso via e-mail: Paytrail invia al cliente un'e-mail per inserire un conto bancario. Serve l'indirizzo e-mail del cliente sull'ordine. La nota indica quale tipo di rimborso è stato avviato.

Un rimborso può essere completato subito oppure elaborato più tardi. La conferma successiva di Paytrail viene aggiunta come nota. Se Paytrail non è riuscito a completare il rimborso, una nota indica che il denaro non è stato restituito al cliente, e il rimborso non risulta più come effettuato; rimborsa il cliente in un altro modo. Se Paytrail rifiuta subito il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso completo 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 Paytrail. I rimborsi effettuati nel Pannello commerciante di Paytrail non vengono sincronizzati con PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Paytrail Gateway è il primo blocco di Modules > Module Manager > VibeFox Paytrail 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 (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 ci sono la riga Product: presta-payment-paytrail 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 cambiare 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 o 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: il dominio 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, Paytrail non viene mostrato ai clienti nel checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. Il negozio PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento è 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 tramite i callback e il ritorno del cliente, e i rimborsi funzionano.

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

Paytrail non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che sia attivo Test mode oppure che Merchant ID e Secret key siano compilati (non l'account di prova pubblico 375917). Verifica che la valuta del carrello sia EUR. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente. La pagina delle impostazioni mostra un avviso in caso di credenziali mancanti o valuta del negozio errata.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: il callback non riesce a raggiungere il tuo negozio, e il cliente non è tornato al negozio. La Callback URL mostrata nella sezione Ordini deve essere raggiungibile da Internet (senza autenticazione di base né firewall di mezzo).

Callback o ritorno risponde Payment verification failed.: la firma non è valida, oppure il pagamento non appartiene a un tentativo di pagamento del carrello. Non cambia nulla. Verifica che la Secret key sia corretta e appartenga al Merchant ID.

Il callback risponde Temporarily unavailable: l'ordine era in fase di conferma da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (ad esempio il modulo è disattivato). Paytrail richiama. Controlla il campo Log per il motivo.

Il cliente vede un errore scegliendo Paytrail: controlla il campo Log nella pagina del modulo. Per esempio, Paytrail API error (401) indica credenziali errate. Attiva Debug log per maggiori dettagli.

Il Merchant ID non viene salvato: deve contenere solo cifre. Copialo di nuovo dal Pannello commerciante di Paytrail.

L'ordine è Paytrail payment on hold: leggi le note nel blocco Paytrail payment. Il motivo è un importo pagato diverso, un pagamento dopo l'annullamento o un pagamento di prova in modalità live.

Il rimborso non riesce: leggi il messaggio. This order has no confirmed Paytrail payment. Refund it manually. significa che non c'è alcun pagamento Paytrail confermato da rimborsare. The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. significa che il pagamento è stato effettuato in modalità live e le credenziali live non sono impostate. Invalid refund amount: at most … significa che l'importo è superiore a quanto resta da rimborsare. Se il metodo di pagamento supporta solo rimborsi via e-mail, l'ordine richiede l'indirizzo e-mail del cliente.

Hook per sviluppatori: l'hook actionWcpPaytrailPaymentRequest modifica la richiesta di pagamento prima che venga firmata e inviata.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Paytrail 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 il registro. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. Le transazioni e i rimborsi Paytrail e gli stati dell'ordine Awaiting Paytrail payment e Paytrail 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 transazione.

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