VibeFox PayPlug for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo rifiuta di installarsi su versioni di PHP più vecchie.

Valuta e importi: euro (EUR), da 0,99 a 20.000,00 per pagamento, i valori predefiniti di PayPlug. Con un'altra valuta del carrello o al di fuori di questi limiti, il metodo di pagamento viene nascosto.

Account PayPlug: ti servono le chiavi segrete del tuo account PayPlug: la chiave di test (sk_test_...) e/o la chiave live (sk_live_...). Non servono altre chiavi e non va configurata alcuna notifica in PayPlug. Il tuo negozio deve essere raggiungibile da internet per ricevere le notifiche; altrimenti gli ordini vengono creati quando il cliente torna da PayPlug.

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

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

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

4. Incolla le tue chiavi segrete dal portale PayPlug (vedi Configurazione).

5. Attiva Enable/Disable e clicca su Save. Prova un pagamento con Test Mode attivo, poi disattivalo per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine PayPlug payment on hold. PrestaShop attiva il nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

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

Checkout

Enable/Disable: Enable PayPlug Gateway 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 memorizzato nell'ordine. Predefinito: PayPlug. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely by card via PayPlug.

Chiavi API

Trovi le chiavi segrete nel portale PayPlug, alla voce Developers > API keys. La sezione contiene un link al portale.

Test Mode: usa la chiave segreta di test per i nuovi pagamenti. Non viene elaborato alcun pagamento reale. I pagamenti effettuati nell'altra modalità continuano a usare la chiave della propria modalità per le verifiche di stato e i rimborsi. Predefinito: on. Finché è attivo, i clienti vedono Test mode: no real payment will be made. sotto il metodo di pagamento.

Test Secret Key: la tua chiave segreta di test PayPlug. Inizia con sk_test_.

Live Secret Key: la tua chiave segreta live PayPlug. Inizia con sk_live_.

Una chiave con il prefisso sbagliato non viene salvata. La pagina mostra, ad esempio, Test Secret Key must start with "sk_test_". The previous value was kept. Le chiavi salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.

Clear saved keys: spunta una chiave e clicca su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Notification URL: l'indirizzo che il modulo invia a PayPlug con ogni pagamento. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_payplug_gateway/webhook. Non serve inserire nulla nel portale PayPlug. L'URL deve essere raggiungibile da internet; altrimenti gli ordini vengono creati quando il cliente torna da PayPlug.

Ordini

Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento riuscito. Lo stato viene impostato subito, senza un secondo cambio di stato.

Avanzate

Logging: registra le chiamate API e le notifiche in logs/ppg_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati. Le chiavi segrete, i dati della carta e i dati dei clienti non vengono mai registrati. Predefinito: off.

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

Delete Data on Uninstall: se attivo, le impostazioni del modulo e il suo log vengono eliminati alla disinstallazione del modulo. Gli ID di pagamento PayPlug memorizzati con gli ordini e lo stato dell'ordine PayPlug payment on hold vengono conservati. Predefinito: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita PayPlug, con il logo PayPlug). In modalità test l'opzione mostra Test mode: no real payment will be made. Dopo la conferma, il modulo crea un pagamento PayPlug per il totale del carrello in centesimi e invia il cliente alla pagina di pagamento di PayPlug. Gli indirizzi di fatturazione e di consegna, l'e-mail e la lingua del carrello vengono trasmessi a PayPlug. Lì il cliente paga con carta. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo quando PayPlug lo conferma: il modulo legge il pagamento dall'API di PayPlug quando arriva la notifica e quando il cliente torna. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your payment with PayPlug has been received. Se l'ordine è in attesa, la pagina riporta We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. Se l'ordine è in Payment error o è stato annullato senza pagamento, la pagina riporta Your PayPlug payment was not completed. Please contact us about this order. Se al ritorno del cliente non è stato possibile interrogare PayPlug, una pagina Payment confirmation mostra lo stesso testo "we are confirming" e un pulsante Check again; la notifica crea l'ordine non appena arriva.

Se il cliente annulla sulla pagina di PayPlug, la pagina di pagamento viene chiusa presso PayPlug, quindi non può essere pagata più tardi per errore. Il cliente torna al checkout con un messaggio: You cancelled the PayPlug payment. You can try again or choose another payment method., The PayPlug payment session has expired. Please try again or choose another payment method., The PayPlug payment failed. Please try again or choose another payment method. oppure, se il pagamento è rimasto aperto, Your PayPlug payment was not completed. You can try again or choose another payment method. Il carrello viene conservato.

Quando il cliente paga di nuovo lo stesso carrello, il modulo controlla prima il tentativo precedente. Se nel frattempo è stato pagato, l'ordine viene creato senza un nuovo pagamento. Se è ancora aperto per lo stesso importo, viene riutilizzata la stessa pagina di pagamento. Altrimenti la vecchia pagina viene chiusa presso PayPlug e ne viene creata una nuova.

Se PayPlug non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, ad esempio PayPlug could not accept your billing details (postcode). Please check them and try again. oppure The payment provider could not be reached. Please try again in a moment. Il motivo tecnico viene scritto nel log.

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

I pagamenti vengono addebitati immediatamente. Il modulo non include rate Oney, carte salvate con un clic, modulo di pagamento integrato, abbonamenti né addebito differito.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a PayPlug e non ha pagato, oppure PayPlug 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 di pagamento PayPlug (pay_...) come ID della transazione, e una nota mostra il pagamento PayPlug e la sua modalità.

PayPlug payment on hold: l'importo pagato o la valuta differiscono dal carrello (nota amount/currency mismatch, ad esempio il carrello è stato modificato dopo l'avvio del pagamento); oppure è stato effettuato un pagamento di test mentre il negozio era in modalità live, quindi non è arrivato alcun denaro e nessun pagamento viene registrato; oppure il pagamento è arrivato per un ordine annullato; oppure un pagamento è autorizzato ma non addebitato (addebitalo nel portale PayPlug; l'ordine viene segnato come pagato quando PayPlug lo comunica come pagato). La nota spiega cosa controllare.

Payment error: un pagamento autorizzato di un ordine in attesa non è riuscito o è stato annullato.

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

Se anche un secondo tentativo su un carrello già pagato viene pagato, l'ordine non cambia. Una nota ti chiede di rimborsare il pagamento duplicato nel portale PayPlug. Un ordine pagato, annullato o rimborsato non viene mai riaperto da una notifica successiva.

Blocco pagamento PayPlug

La pagina dell'ordine mostra un blocco PayPlug payment con l'ID del pagamento PayPlug, lo stato del pagamento, l'importo pagato e rimborsato, un badge Test mode per i pagamenti di test, lo storico dei rimborsi e le PayPlug notes dell'ordine.

Rimborsi

Nel blocco PayPlug payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via PayPlug. Conferma la domanda Refund this amount through PayPlug? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine dei moduli. I rimborsi vengono effettuati fino all'importo effettivamente addebitato da PayPlug, quindi dopo una discrepanza di importo puoi rimborsare ciò che il cliente ha pagato, non il totale dell'ordine. Il rimborso va al pagamento che ha effettivamente saldato l'ordine, con la chiave segreta della modalità (test o live) in cui è stato effettuato, quindi quella chiave deve essere configurata. Se PayPlug non accetta il rimborso, il blocco mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con l'ID del rimborso PayPlug e il motivo. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili solo quando PayPlug ha segnalato il pagamento come pagato.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite PayPlug.

I rimborsi effettuati nel portale PayPlug arrivano tramite notifica e vengono aggiunti alle note una sola volta. Non vengono conteggiati nel blocco e non modificano lo stato dell'ordine né le note di credito. Registrali manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox PayPlug Gateway è il primo blocco di Modules > Module Manager > VibeFox PayPlug Gateway > Configure, sopra le impostazioni. Incolla la chiave in License key e clicca 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 verificare 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-payplug 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, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo un cambio dell'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, clicca 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: 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, PayPlug 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 sei connesso al back office, quindi il metodo di pagamento viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo al checkout. Un promemoria appare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

PayPlug non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità corrente abbia una chiave segreta (Test Secret Key in modalità test, Live Secret Key in modalità live), che la valuta del carrello sia EUR e che il totale del carrello sia compreso tra 0,99 e 20.000,00 EUR. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente. Gli sviluppatori possono modificare valute e limiti con gli hook actionWcpPayplugSupportedCurrencies e actionWcpPayplugAmountLimits (valori in centesimi).

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: la notifica non è arrivata al tuo negozio e il cliente non è tornato. Verifica che il tuo negozio sia raggiungibile da internet all'indirizzo Notification URL mostrato nelle impostazioni, ad esempio che nessun firewall o protezione con password lo blocchi. Attiva Logging e controlla il campo Log per le notifiche rifiutate.

La notifica risponde Verification failed.: il pagamento non è stato letto dall'API di PayPlug, per esempio perché PayPlug non ha risposto o perché la chiave segreta della modalità del pagamento non è impostata. L'ordine non cambia e PayPlug invia di nuovo la notifica.

La notifica risponde Temporarily unavailable.: il carrello era in aggiornamento da un'altra richiesta nello stesso momento, per esempio il ritorno del cliente, oppure l'ordine non è stato creato (per esempio perché il modulo è disattivato). PayPlug invia di nuovo la notifica. Il log mostra il motivo.

La notifica risponde Unknown payment. o Payment does not belong to the order.: il pagamento non è stato creato da questo negozio o non per questo carrello, per esempio un pagamento di un altro negozio sullo stesso account PayPlug. Viene ignorato.

L'URL di notifica mostra Method not allowed. nel browser: è normale. L'URL accetta solo richieste da PayPlug.

Il cliente vede un errore scegliendo PayPlug: attiva Logging e controlla il campo Log. Una chiave errata dà This payment method is temporarily unavailable. Please choose another payment method.; gli altri messaggi indicano il campo di fatturazione rifiutato da PayPlug.

L'ordine è PayPlug payment on hold dopo il pagamento: leggi le note nel blocco PayPlug payment (vedi Stati dell'ordine), poi elabora l'ordine o rimborsa il pagamento.

Il rimborso non riesce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità test o live, e la chiave segreta di quella modalità non è configurata. Inseriscila e riprova.

Il rimborso non riesce con Unexpected response from PayPlug.: PayPlug ha risposto senza un rimborso valido. Non è stato registrato nulla. Controlla il rimborso nel portale PayPlug prima di riprovare.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox PayPlug 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, le impostazioni del modulo e il log vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I record dei pagamenti e dei rimborsi PayPlug e lo stato dell'ordine PayPlug payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID delle transazioni.

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