VibeFox SimplePay 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 del negozio: HUF, EUR o USD. SimplePay non accetta altre valute, e il metodo di pagamento non viene offerto per i carrelli in altre valute.

Account commerciante SimplePay: SimplePay fornisce un account commerciante separato per ogni valuta, e account separati per live e sandbox. Per ogni account ti servono il suo MERCHANT e la sua SECRET KEY dal pannello commerciante di SimplePay (admin.simplepay.hu per il live, sandbox.simplepay.hu per il sandbox), account > Technical data. Se vendi solo in HUF, basta l'account HUF. Non servono altre chiavi.

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 SimplePay 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. Inserisci MERCHANT e SECRET KEY dei tuoi account SimplePay per ogni valuta in cui vendi: account sandbox per i test e account live per i pagamenti reali (vedi Configurazione).

5. Copia l'IPN URL mostrato nella pagina Configure in ogni account commerciante (live e sandbox) nel pannello commerciante di SimplePay.

6. Attiva Enable/Disable e fai clic su Save. Prova un pagamento con Sandbox mode attivo, poi disattiva Sandbox mode per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine SimplePay payment on hold. PrestaShop offre un 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 SimplePay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando la valuta predefinita del negozio non è supportata da SimplePay, o quando non ha un account commerciante nella modalità attuale. In entrambi i casi il metodo di pagamento non viene offerto per i carrelli in quella valuta. Mentre la modalità sandbox è attiva, la pagina mostra Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged.

SimplePay (OTP)

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: SimplePay (Card Payment). Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with your credit or debit card via SimplePay. I commercianti ungheresi possono inserire qui la dichiarazione di trasferimento dati di SimplePay (con il suo link).

Sandbox mode: usa il sandbox di SimplePay per i pagamenti di prova con gli account sandbox. Cambia sia l'indirizzo delle API sia gli account commerciante. Non viene addebitato denaro reale. Predefinito: attivo. Disattivalo per accettare pagamenti reali con gli account live. Mentre è attivo, i clienti vedono Sandbox mode: no real payment is taken. sotto il metodo di pagamento. Gli ordini avviati nel sandbox vengono sempre rimborsati nel sandbox.

Account commerciante live

Gli account usati quando Sandbox mode è disattivato. Compila gli account delle valute in cui vende il tuo negozio. I valori di MERCHANT e SECRET KEY si trovano nel pannello commerciante di SimplePay (admin.simplepay.hu), account > Technical data. Un account viene usato solo se entrambi i campi sono compilati.

HUF account — Merchant ID: il MERCHANT del tuo account live in HUF.

HUF account — Secret key: la SECRET KEY del tuo account live in HUF.

EUR account — Merchant ID e EUR account — Secret key: lo stesso per il tuo account live in EUR.

USD account — Merchant ID e USD account — Secret key: lo stesso per il tuo account live in USD.

Account commerciante sandbox

Gli account usati quando Sandbox mode è attivo. I campi sono gli stessi degli account live: HUF account — Merchant ID, HUF account — Secret key e le stesse coppie per EUR e USD. Prendi i valori dal pannello commerciante sandbox di SimplePay (sandbox.simplepay.hu), account > Technical data.

Le secret key salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

IPN URL

L'IPN è il messaggio che SimplePay invia al tuo negozio quando cambia lo stato del pagamento. È il modo normale in cui viene creato un ordine. La sezione mostra l'IPN URL del tuo negozio. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_simplepay_gateway/ipn, eventualmente con un codice lingua come /en/. Imposta questo URL per ogni account commerciante, live e sandbox, nel pannello commerciante di SimplePay. Copia l'URL esattamente come lo mostrano le impostazioni, perché un IPN reindirizzato va perso.

L'IPN deve essere firmato con la SECRET KEY dell'account commerciante che indica, nella modalità (sandbox o live) in cui il pagamento è stato avviato. Gli IPN senza firma valida vengono rifiutati. Il modulo conferma a SimplePay ogni IPN valido nella forma firmata richiesta da SimplePay. Vengono usati questi stati IPN:

FINISHED: il pagamento è riuscito. L'ordine viene creato dopo il controllo di importo e valuta.

NOTAUTHORIZED, FRAUD: il pagamento è stato rifiutato. Il tentativo di pagamento viene segnato come non riuscito; non viene creato alcun ordine.

TIMEOUT, CANCELLED: il tempo per il pagamento è scaduto o il cliente lo ha annullato. Il tentativo di pagamento viene segnato come scaduto o annullato; non viene creato alcun ordine.

Gli stati rifiutato, annullato e scaduto vengono registrati solo per l'ultimo tentativo di pagamento di un carrello che non ha ancora un ordine. Gli altri stati vengono registrati nel log e non cambiano nulla. Senza IPN, un ordine viene creato solo quando il cliente torna nel negozio dopo un pagamento riuscito.

Clear saved secret keys: seleziona una secret key e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Ordini

Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento riuscito.

Processing (Payment accepted): il predefinito, lo stato standard di PrestaShop per gli ordini pagati.

Completed (Delivered): ogni ordine pagato passa a Consegnato.

Un pagamento per un importo o una valuta diversi da quelli dell'ordine passa sempre a SimplePay payment on hold.

Avanzate

Logging: scrive chiamate API, IPN e ritorni in logs/simplepay_op_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Chiavi e dati dei clienti non vengono registrati. Gli errori vengono sempre registrati, anche quando l'opzione è disattivata. Predefinito: disattivato.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il log. I dati degli ordini (transazioni e rimborsi di SimplePay) vengono sempre conservati. Predefinito: disattivato.

Checkout

Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita SimplePay (Card Payment)) e vede la nota You will be redirected to the SimplePay payment page to pay by card. Dopo la conferma, il modulo avvia un pagamento con carta SimplePay per il totale del carrello nella valuta del carrello, con l'account commerciante di quella valuta nella modalità attuale, e invia il cliente alla pagina di pagamento di SimplePay. L'e-mail del cliente e, quando è completo, l'indirizzo di fatturazione vengono passati a SimplePay. La pagina di pagamento usa la lingua del negozio quando SimplePay la supporta, altrimenti l'inglese. Un pagamento avviato può essere completato entro 30 minuti. A questo punto non esiste ancora alcun ordine.

Dopo un pagamento riuscito il cliente torna nel tuo negozio. Il ritorno da solo non paga mai un ordine: il modulo chiede a SimplePay lo stato della transazione con una richiesta firmata, quindi l'ordine viene creato anche se l'IPN arriva in ritardo. L'ordine viene segnato come pagato solo dopo la conferma di SimplePay. Il cliente vede poi la normale pagina di conferma dell'ordine con Successful transaction. SimplePay transaction ID: e l'ID. Se SimplePay non ha ancora confermato il pagamento, una pagina Payment confirmation mostra Your payment is being confirmed by SimplePay. SimplePay transaction ID: con l'ID e un pulsante Check again; l'IPN crea l'ordine appena arriva.

Se il pagamento non riesce, viene annullato o scade, il cliente torna al checkout con il messaggio di SimplePay e l'ID della transazione, per esempio Cancelled payment. You cancelled the payment oppure Timeout. The time allowed to complete the payment has expired. In caso di pagamento non riuscito il cliente è invitato a controllare i dati inseriti e a contattare la banca che ha emesso la carta. Il carrello viene conservato e il cliente può riprovare. Ogni nuovo tentativo riceve un proprio riferimento SimplePay: PS, il numero del carrello e il numero del tentativo, per esempio PS123-1, PS123-2.

Se SimplePay non riesce ad avviare il pagamento, il cliente vede The SimplePay payment could not be started. Please try again or choose another payment method. Se la valuta del carrello non ha un account commerciante, il messaggio è SimplePay is not available for the currency of this order. Please choose another payment method. Il motivo tecnico viene scritto nel log.

L'IPN funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo accetta solo pagamenti con carta singoli, incassati nella pagina di SimplePay. Non prevede carte salvate o pagamenti con un clic, abbonamenti o pagamenti ricorrenti, né autorizzazione e cattura separate.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a SimplePay e non ha pagato, il pagamento non è riuscito, è stato annullato o è scaduto, oppure SimplePay 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 della transazione SimplePay, e una nota mostra l'ID della transazione e se a confermarlo sono stati l'IPN o la richiesta di stato.

SimplePay payment on hold: il totale o la valuta del carrello sono stati modificati dopo l'avvio del pagamento, quindi l'importo pagato non corrisponde all'ordine. Non viene registrato alcun pagamento. La nota mostra entrambi gli importi. Controlla l'ordine ed evadilo oppure rimborsa il pagamento nel pannello commerciante di SimplePay. Se poi un altro tentativo dello stesso carrello viene pagato con l'importo corretto, l'ordine passa allo stato pagato.

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

Un ordine pagato, rimborsato o consegnato non viene mai riaperto da un IPN tardivo. Se per un ordine già pagato riesce un secondo pagamento, l'ordine non cambia. Una nota ti chiede di verificarlo nel pannello di SimplePay e di rimborsarlo se si tratta di un duplicato.

Blocco pagamento SimplePay

La pagina dell'ordine mostra un blocco SimplePay payment con l'ID della transazione, il riferimento dell'ordine (orderRef), l'account commerciante e la modalità, lo stato SimplePay, gli importi pagati e rimborsati, un badge Sandbox per i pagamenti sandbox, i tentativi di pagamento del carrello (quando ce n'è stato più di uno), lo storico dei rimborsi e le SimplePay notes dell'ordine.

Rimborsi

Nel blocco SimplePay payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via SimplePay (OTP). Conferma la domanda Refund this amount via SimplePay? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non è necessario l'accesso alle pagine dei moduli. I rimborsi in HUF devono essere fiorini interi. Il rimborso viene inviato per la transazione SimplePay che ha pagato l'ordine, con il suo importo e la sua valuta, tramite l'account commerciante e nella modalità (sandbox o live) di quel pagamento, quindi quell'account deve restare nelle impostazioni. Se SimplePay non accetta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note, con l'ID della transazione di rimborso SimplePay e il motivo, se ne hai inserito uno. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. Un ordine in attesa dopo una discrepanza di importo non può essere rimborsato dal blocco: rimborsalo nel pannello commerciante di SimplePay.

Il modulo non crea note di credito. I pulsanti standard di rimborso di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite SimplePay. I rimborsi effettuati nel pannello commerciante di SimplePay non vengono sincronizzati con PrestaShop. Registrali manualmente.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox SimplePay Gateway è il primo blocco di Modules > Module Manager > VibeFox SimplePay Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo di che il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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-simplepay 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, 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, SimplePay 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. La vetrina di PrestaShop non sa che sei collegato al back office, quindi il metodo di pagamento è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo 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 dall'IPN e i rimborsi funzionano.

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

SimplePay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la valuta del carrello sia HUF, EUR o USD, e che quella valuta abbia Merchant ID e Secret key nella modalità attuale: gli account sandbox mentre Sandbox mode è attivo, gli account live mentre è disattivo. 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: l'IPN non ha raggiunto il negozio. Nel pannello commerciante di SimplePay controlla l'IPN URL dell'account commerciante che usi (live o sandbox, la valuta del carrello). Deve corrispondere esattamente all'URL mostrato nelle impostazioni, e il tuo server deve essere raggiungibile da internet. L'ordine viene creato anche quando il cliente torna nel negozio dopo aver pagato.

L'IPN risponde Invalid signature: l'IPN indica un account commerciante che non è nelle impostazioni, la sua Secret key è errata, oppure è firmato con l'account di una modalità diversa da quella del pagamento. Inserisci MERCHANT e SECRET KEY esattamente come li mostra il pannello commerciante di SimplePay. SimplePay ripete gli IPN non confermati.

L'IPN risponde Order not found o Unknown transaction: l'IPN riguarda un pagamento che questo negozio non ha avviato. Non viene cambiato nulla.

L'IPN risponde Busy, retry: il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). SimplePay ripete l'IPN. Il motivo viene scritto nel log.

Il cliente vede The SimplePay payment could not be started: controlla il campo Log nella pagina del modulo. Una secret key errata dà Invalid response signature from SimplePay. Check the secret key of the merchant account. Gli errori di SimplePay vengono registrati con i loro codici di errore.

Dopo il passaggio tra sandbox e live: i nuovi pagamenti usano gli account della nuova modalità. I pagamenti avviati prima mantengono l'account commerciante e la modalità con cui sono stati avviati: i loro IPN, le richieste di stato e i rimborsi usano quell'account. Mantieni gli account della vecchia modalità nelle impostazioni finché ci sono pagamenti aperti o rimborsabili.

L'ordine è in SimplePay payment on hold dopo il pagamento: leggi le note nel blocco SimplePay payment. Il totale o la valuta del carrello sono stati modificati dopo l'avvio del pagamento. Evadi l'ordine oppure rimborsa il pagamento nel pannello commerciante di SimplePay.

Il rimborso non riesce: leggi il messaggio nel blocco. SimplePay refunds in HUF must be whole amounts. significa che l'importo in HUF aveva decimali. Se il messaggio dice che l'account commerciante di questo pagamento non è configurato, inserisci di nuovo l'account (valuta e modalità) con cui è stato effettuato il pagamento. Se SimplePay ha rimborsato un importo diverso, il messaggio ti chiede di verificare il rimborso nel pannello di SimplePay.

Disinstallazione

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

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