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

Valuta del negozio: EUR. Paytrail accetta solo euro. Con qualsiasi altra valuta, il metodo di pagamento rimane nascosto al checkout. Gli importi vengono inviati in centesimi.

Accesso a Internet per il tuo sito: Paytrail conferma ogni pagamento con un callback server-to-server, quindi il sito deve essere raggiungibile da Internet. Anche senza callback, gli ordini vengono comunque confermati quando il cliente torna da Paytrail.

Account Paytrail: sono necessari il tuo Merchant ID e la tua Secret key, visualizzati nel Pannello commerciante di Paytrail (dettagli dell'account o dell'integrazione). Per i test non è richiesto alcun account: la modalità di prova utilizza l'account di prova pubblico di Paytrail. I metodi di pagamento veri e propri vengono abilitati nel tuo account Paytrail.

Chiave di licenza VibeFox: acquistata 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_paytrail_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Paytrail > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel riquadro della licenza in cima alla pagina e fai clic su Activate.

5. Per provare prima il plugin, seleziona Test mode. Per i pagamenti reali, deselezionalo e inserisci i tuoi Merchant ID e Secret key. Nessun URL di callback deve essere configurato in Paytrail.

6. Attiva Enable/Disable e salva.

Configurazione

Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Payments > Paytrail. Sopra i campi la pagina mostra Test mode is active. quando la modalità di prova è attiva. In modalità reale ti avvisa se mancano il Merchant ID o la Secret key e se la valuta del negozio non è EUR. In entrambi i casi Paytrail non viene mostrato al checkout. Nell'elenco dei metodi di pagamento, Paytrail è contrassegnato come da configurare finché la modalità reale non dispone di credenziali.

Al momento del salvataggio, un Merchant ID contenente caratteri diversi dalle cifre non viene salvato: viene mostrato un errore e viene mantenuto il valore precedente.

General

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

Title: il titolo mostrato ai clienti durante il checkout. Predefinito: Paytrail.

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

API credentials

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

Test mode: Use the Paytrail test account. I nuovi pagamenti utilizzano l'account di prova pubblico di Paytrail (Merchant ID 375917) anziché le tue credenziali. Non viene addebitato denaro reale. I clienti vedono Test mode: no real payment will be made. al checkout. La Secret key dell'account di prova è pubblica, pertanto chiunque potrebbe simulare un pagamento per un ordine creato in modalità di prova. Non lasciare mai la modalità di prova attiva in un negozio reale. Predefinito: disattivato.

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

Secret key: la tua Secret key di Paytrail. Utilizzata quando la modalità di prova è disattivata.

I callback e i rimborsi utilizzano sempre le credenziali della modalità in cui è stato effettuato il pagamento, quindi il passaggio da test a reale non interferisce con gli ordini precedenti.

Orders

Questa sezione mostra l'URL di callback, simile a https://your-site/wc-api/ptg_paytrail/. Paytrail conferma ogni pagamento server-to-server a questo URL. Viene inviato a ogni pagamento, quindi non occorre configurare nulla nel pannello di Paytrail, ma il sito deve essere raggiungibile da Internet.

Order status after payment: lo stato di un ordine pagato. Lo stato viene impostato in un unico passaggio, così il cliente riceve una sola serie di e-mail.

Advanced

Debug log: Log API requests and callbacks. Registrato in WooCommerce > Status > Logs, origine wcp_paytrail_gateway, senza dati personali o chiavi. Gli errori vengono sempre registrati. Predefinito: disattivato.

Delete data on uninstall: Delete settings, logs and Paytrail order data when the plugin is deleted. La disattivazione del plugin non cancella mai nulla. Senza i dati delle transazioni Paytrail, i rimborsi dei vecchi ordini non sono più possibili da WooCommerce. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Paytrail) ed effettua l'ordine. Il plugin crea un pagamento Paytrail per il totale dell'ordine in euro e invia le righe dell'ordine: prodotti, spedizione e commissioni, ciascuno con la propria aliquota IVA a una cifra decimale. Le righe corrispondono sempre all'importo del pagamento; un'eventuale differenza di arrotondamento viene inclusa in una riga o inviata come riga Rounding. Gli indirizzi di fatturazione e di spedizione vengono inviati solo quando completi, e i valori lunghi vengono accorciati secondo i limiti di Paytrail. La lingua della pagina di pagamento è finlandese, svedese o inglese, in base alle impostazioni locali del negozio.

Il cliente viene reindirizzato alla pagina di pagamento Paytrail, sceglie un metodo di pagamento abilitato per il tuo account Paytrail e paga. Paytrail conferma quindi il pagamento due volte: rimanda il cliente al tuo negozio e richiama l'URL di callback server-to-server. Entrambi sono accettati solo con una firma valida creata con le credenziali di quel tentativo di pagamento e solo per il tentativo creato per quell'ordine. L'importo pagato viene confrontato con il totale dell'ordine. L'ordine viene contrassegnato come pagato solo dopo la conferma di Paytrail in questo modo. Il plugin gestisce questi stati di Paytrail:

Dopo un pagamento riuscito il cliente visualizza la pagina dell'ordine ricevuto. Dopo un pagamento annullato o non riuscito, il cliente passa alla pagina Pay for order con il messaggio The Paytrail payment was cancelled or failed. You can try again or choose another payment method. Se il pagamento non è ancora completato, il messaggio è The Paytrail payment has not been completed yet. You can try again or choose another payment method.

Se Paytrail non riesce ad avviare il pagamento, il cliente visualizza un breve messaggio, ad esempio Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method. (credenziali errate) o Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method. Il motivo tecnico viene aggiunto alle note dell'ordine e al registro. Gli ordini superiori all'importo massimo di Paytrail non possono essere pagati con Paytrail.

Un pagamento Paytrail non può essere annullato tramite l'API. Se il cliente avvia un nuovo pagamento e poi paga anche su una pagina di pagamento precedente ancora aperta, il secondo pagamento viene segnalato nelle note dell'ordine come duplicato da rimborsare.

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 cliente sceglie il metodo di pagamento sulla pagina di Paytrail, non nel tuo checkout. Il plugin non prevede la tokenizzazione o il salvataggio delle carte, né WooCommerce Subscriptions, shop-in-shop, attivazione manuale delle fatture o report di liquidazione.

Ordini e rimborsi

Stati degli ordini

Pending payment: il pagamento Paytrail è stato creato e il cliente non ha ancora pagato. La nota dell'ordine mostra l'ID transazione Paytrail, l'importo e la modalità.

Processing or Completed: il pagamento è stato confermato. Lo stato segue Order status after payment. La nota dell'ordine mostra la transazione, il metodo di pagamento utilizzato su Paytrail e l'importo. L'ID transazione è l'ID transazione di Paytrail.

On hold: il pagamento è in sospeso presso il fornitore (fattura o pagamento differito), l'importo pagato differisce dal totale dell'ordine, il pagamento è arrivato dopo l'annullamento dell'ordine oppure è stato ricevuto un pagamento di prova mentre il negozio è in modalità reale (nessun denaro reale). La nota dell'ordine ne spiega il motivo. Controlla l'ordine, quindi elaboralo o rimborsa il pagamento.

Failed: l'ultimo tentativo di pagamento non è riuscito o è stato annullato dal cliente. Il cliente può pagare di nuovo.

I callback ripetuti o paralleli non creano mai note duplicate, riduzioni di magazzino o e-mail duplicate. Se viene pagato un secondo tentativo di un ordine già pagato, l'ordine non viene modificato nuovamente; una nota Duplicate payment invita a effettuare il rimborso nel Pannello commerciante di Paytrail.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Paytrail (il pulsante mostra il tuo Title). Sono supportati rimborsi completi e parziali, solo per gli importi (nessuna riga di articolo di rimborso). Il pulsante è disponibile solo per gli ordini con un pagamento Paytrail confermato. Il rimborso utilizza le credenziali della modalità in cui è stato effettuato il pagamento, quindi per un pagamento reale devono essere impostate le credenziali reali.

Se il metodo di pagamento non supporta i rimborsi diretti, il plugin avvia automaticamente un rimborso via e-mail: Paytrail invia un'e-mail al cliente per l'inserimento di un conto bancario. A questo scopo è necessario un indirizzo e-mail di fatturazione nell'ordine. La nota dell'ordine specifica quale tipo di rimborso è stato avviato.

Un rimborso può essere completato immediatamente o elaborato in seguito. La conferma successiva di Paytrail viene aggiunta come nota. Se Paytrail non ha potuto completare il rimborso, una nota indica che il denaro non è stato restituito al cliente: rimborsalo in altro modo ed elimina il rimborso di WooCommerce. Se Paytrail rifiuta immediatamente il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato.

I rimborsi effettuati nel Pannello commerciante di Paytrail non vengono sincronizzati con WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il riquadro della licenza si trova in alto in WooCommerce > Settings > Payments > Paytrail. Incolla la chiave in License key e fai clic su Activate. Il riquadro mostra lo stato, ad esempio la data fino a cui 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 su vibefox.net.

Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera il relativo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Paytrail non viene mostrato ai clienti al checkout. Se un pagamento viene comunque avviato, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio che hanno effettuato l'accesso continuano a vedere il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria viene mostrato nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non vengono influenzati: i pagamenti già iniziati continuano a essere confermati e i rimborsi funzionano.

Alla scadenza della licenza, il plugin continua a funzionare, ma per gli aggiornamenti e l'assistenza è necessario un rinnovo. Lo stato viene verificato nuovamente in modo automatico in background.

Risoluzione dei problemi

Paytrail non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che sia attiva la Test mode oppure che Merchant ID e Secret key siano compilati. Verifica che la valuta del negozio (o la valuta dell'ordine nella pagina Pay for order) sia EUR. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi.

Il pagamento è andato a buon fine, ma l'ordine resta su Pending payment: il callback non riesce a raggiungere il tuo sito e il cliente non è tornato al negozio. L'URL di callback mostrato nella sezione Orders deve essere raggiungibile da Internet (senza modalità di manutenzione, autenticazione di base o firewall di mezzo).

Il callback o il ritorno risponde con Payment verification failed.: la firma non è valida o il pagamento non appartiene a un tentativo di pagamento dell'ordine. L'ordine non viene modificato. Verifica che la Secret key sia corretta e appartenga al Merchant ID.

Il pagamento non viene creato: la nota dell'ordine e il registro mostrano l'errore di Paytrail, ad esempio Paytrail API error (401): … per credenziali errate. Attiva Debug log e controlla in WooCommerce > Status > Logs, origine wcp_paytrail_gateway.

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

L'ordine è in On hold: leggi la nota dell'ordine. Il motivo è un pagamento in sospeso o differito, un importo pagato differente, un pagamento successivo all'annullamento o un pagamento di prova in modalità reale.

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. Un messaggio relativo alle credenziali reali mancanti indica che il pagamento è stato effettuato in modalità reale e le credenziali reali non sono state impostate. Se il metodo di pagamento supporta solo rimborsi via e-mail, l'ordine necessita di un'e-mail di fatturazione.

Hook per sviluppatori: il filtro ptg_payment_request modifica la richiesta di pagamento prima che venga firmata e inviata; il filtro ptg_icon modifica l'icona del checkout.

Il riquadro della licenza mostra un errore: segui il messaggio nel riquadro. Ad esempio, se la chiave è già utilizzata 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. Le impostazioni del gateway, il registro di questo plugin e i dati di Paytrail memorizzati sugli ordini (tentativi di pagamento, dati delle transazioni, registrazioni dei rimborsi) vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti rimangono per una successiva reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID di transazione; senza i dati di Paytrail, i vecchi ordini non possono più essere rimborsati da WooCommerce.

Paytrail è un marchio del rispettivo proprietario. Questo plugin non è affiliato né approvato da Paytrail.