VibeFox Windcave for PrestaShop — Guida

Requisiti

PrestaShop: 8.0–9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP precedenti.

Account Windcave: ti serve un account merchant Windcave con credenziali REST API: un nome utente API e una chiave API. Windcave le rilascia separatamente per l'ambiente di test UAT (uat.windcave.com) e per la produzione (sec.windcave.com). Chiedile al supporto Windcave o al tuo account manager. Le chiavi PxPay non funzionano con questo modulo. I metodi di pagamento che vuoi offrire (carte, wallet e altri) devono essere attivati sul tuo account Windcave.

Notifica: il tuo negozio deve essere raggiungibile da internet, in modo che Windcave possa inviare la sua notifica di pagamento. Non c'è nulla da configurare su Windcave.

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

2. Al termine del caricamento, clicca su Configure, oppure trova in seguito VibeFox Windcave Payment Gateway nell'elenco dei moduli e clicca su Configure.

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

4. Inserisci il tuo nome utente e la chiave della REST API: le credenziali UAT per la modalità di test, le credenziali di produzione per i pagamenti reali (vedi Configurazione).

5. Scegli il tipo di transazione e i metodi di pagamento, attiva Enable/Disable e clicca su Save. Effettua un pagamento di prova con Test mode attivo, poi disattiva Test mode per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine Windcave payment on hold. PrestaShop propone 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 Windcave Payment Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Mentre la modalità di test è attiva, la pagina mostra Test mode attivo: i pagamenti vanno all'ambiente UAT di Windcave e non viene addebitato denaro reale. Se il modulo è attivo ma la modalità corrente non ha un nome utente o una chiave API, la pagina avvisa che il metodo di pagamento è nascosto al checkout, per esempio Windcave è attivo ma il nome utente o la chiave API UAT sono vuoti: il metodo di pagamento è nascosto al checkout. Il campo Title non può essere vuoto: in tal caso la pagina mostra Inserisci un titolo per il metodo di pagamento. e non viene salvato nulla.

Windcave

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

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

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: You will be redirected to the secure Windcave payment page to complete your payment.

Windcave REST API

Inserisci le credenziali REST API emesse da Windcave (nome utente e chiave API, non le chiavi PxPay). Le credenziali di produzione e quelle UAT possono essere salvate una accanto all'altra. La modalità di test usa solo le credenziali UAT, la modalità reale solo quelle di produzione. La sezione rimanda alla documentazione della REST API di Windcave.

Test mode: usa l'ambiente di test UAT di Windcave (uat.windcave.com). Non viene addebitato denaro reale. I nuovi pagamenti usano le credenziali UAT. Rimborsi e acquisizioni vanno sempre nell'ambiente in cui l'ordine è stato pagato. Predefinito: disattivato.

Production API username: il nome utente della REST API per sec.windcave.com.

Production API key: la chiave della REST API per sec.windcave.com.

UAT API username: il nome utente della REST API per uat.windcave.com (modalità di test).

UAT API key: la chiave della REST API per uat.windcave.com (modalità di test).

Le chiavi API 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.

Clear saved keys: spunta Production API key o UAT API key e clicca su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Notification URL: mostra l'indirizzo a cui Windcave invia la sua notifica di pagamento (Fail-Proof Result Notification). Con URL parlanti ha questo aspetto: https://tuo-negozio/module/wcp_windcave_payment_gateway/notification. Su Windcave non c'è nulla da configurare: il modulo invia i propri indirizzi di ritorno e questo indirizzo di notifica con ogni sessione di pagamento. L'indirizzo deve essere raggiungibile da internet, altrimenti gli ordini vengono confermati solo quando il cliente torna da Windcave. Né il ritorno del cliente né la notifica sono firmati da Windcave, quindi il modulo non si fida mai di loro da solo: legge sempre il risultato della sessione dalla REST API di Windcave, con le credenziali dell'ambiente in cui la sessione è stata creata.

Payment

Transaction type: come viene preso il pagamento. Predefinito: Purchase.

Payment methods: i metodi mostrati nella pagina di pagamento Windcave: Cards, Account2Account (bonifico bancario neozelandese), Apple Pay, Google Pay, PayPal, Alipay, WeChat Pay, UnionPay, Interac, humm. Usa Ctrl o Cmd e clic per selezionarne più di uno. I metodi devono essere attivati sul tuo account Windcave. Lascia il campo vuoto per mostrare tutti i metodi attivi sull'account. Predefinito: Cards.

Advanced

Debug log: registra le richieste API e gli eventi di pagamento in logs/windcave_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Finché questa opzione è disattivata, vengono registrati solo errori e avvisi. Chiavi API, dati della carta e dati personali dei clienti non vengono mai registrati. Predefinito: disattivato.

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

Clean uninstall: elimina le impostazioni e i log del modulo quando il modulo viene disinstallato. I dati di pagamento salvati con gli ordini (gli ID transazione Windcave necessari per i rimborsi) vengono sempre conservati. Predefinito: disattivato.

La versione del modulo è mostrata in fondo alla pagina.

Checkout

Al momento del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit/Debit Card (Windcave)) con la sua descrizione. In modalità di test il cliente vede anche Test mode: i pagamenti vanno all'ambiente UAT di Windcave, non viene addebitato denaro reale. Dopo la conferma, il modulo crea una sessione di pagamento Windcave per il totale del carrello nella valuta del carrello e invia il cliente alla Windcave Hosted Payment Page. Il numero del carrello viene inviato come riferimento del merchant, insieme alla lingua del negozio e al nome, all'e-mail, al telefono e all'indirizzo di fatturazione del cliente (e all'indirizzo di spedizione quando il carrello richiede una spedizione). A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Windcave: il modulo chiede alla REST API di Windcave il risultato della sessione, sia quando il cliente torna sia quando arriva la notifica di Windcave. Un blocco per carrello garantisce che il pagamento venga applicato una sola volta. Poi l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine con Your Windcave payment has been received. Per un ordine in attesa (un'autorizzazione o un pagamento che non corrisponde al carrello), la pagina mostra Your payment was received by Windcave. The shop will check it before processing your order — please do not pay again.

Se il cliente torna da un pagamento approvato ma il risultato non è ancora noto, una pagina Payment confirmation mostra We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again. e un pulsante Check again. La notifica crea l'ordine appena Windcave conferma il pagamento.

Se il cliente torna senza un pagamento completato, la pagina del checkout mostra uno di questi messaggi. Il carrello viene conservato.

Il cliente può riprovare con lo stesso carrello. Un nuovo tentativo controlla prima la sessione precedente: se è già pagata, l'ordine viene creato e non viene avviato un secondo pagamento; se il cliente non ha mai usato la pagina di pagamento e il carrello non è cambiato, viene rimandato alla stessa pagina. Se il pagamento precedente è in fase di conferma in quel momento, il cliente vede Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.

Se Windcave non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio: che Windcave non è riuscito ad avviare il pagamento con i dati di questo ordine, oppure che il servizio di pagamento è temporaneamente non disponibile. Il motivo viene scritto nel log. Se la modalità corrente non ha credenziali, il cliente vede This payment method is not available at the moment. Please choose another payment method or contact us.

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

Il modulo non prevede abbonamenti o pagamenti ricorrenti, carte salvate, modulo carta integrato nel tuo sito (il cliente paga sempre sulla pagina di Windcave), supporto all'API PxPay 2.0, e non aggiunge sovrapprezzi. Se Windcave aggiunge un sovrapprezzo, l'ordine viene confrontato con la transazione principale.

Ordini e rimborsi

Order statuses

No order yet: il cliente è stato inviato a Windcave e non ha pagato, Windcave non ha ancora confermato il pagamento, oppure il pagamento è stato rifiutato, annullato o è scaduto. Esiste solo il carrello.

Payment accepted: un pagamento Purchase è stato confermato e corrisponde al carrello. Il pagamento viene registrato con l'ID transazione Windcave, e una nota mostra l'importo, l'ID transazione, il codice di autorizzazione, il tipo di carta con il numero mascherato e l'ambiente (UAT o produzione).

Windcave payment on hold (authorised): un pagamento Auth è stato approvato ma non ancora acquisito. Nessun pagamento viene registrato sull'ordine finché non viene acquisito. La nota spiega come acquisirlo o rilasciarlo.

Windcave payment on hold (does not match): Windcave ha comunicato un importo, una valuta, un riferimento del merchant o un tipo di transazione diversi da quelli del carrello (per esempio, il carrello è stato modificato in un'altra scheda dopo l'avvio del pagamento). La nota elenca le differenze. Per un Purchase nella valuta del carrello, il pagamento viene registrato con l'importo che Windcave ha effettivamente addebitato. Controlla il pagamento in Windcave Payline prima della spedizione e rimborsalo se necessario.

Refunded: il pagamento è stato rimborsato interamente oppure l'autorizzazione è stata rilasciata tramite il modulo.

Se arriva un pagamento approvato per un ordine annullato, oppure un secondo pagamento approvato per un ordine già esistente, l'ordine non viene modificato. Una nota con l'ID transazione ti chiede di rimborsarlo in Windcave Payline (o di ripristinare manualmente l'ordine annullato).

Windcave payment block

La pagina dell'ordine mostra un blocco Windcave payment con l'ID transazione, l'ID sessione, il tipo di transazione e lo stato con l'ambiente, l'importo pagato, il codice di autorizzazione e la carta, la transazione di acquisizione o annullamento, il totale del pagamento e l'importo rimborsato, un badge Test mode (UAT) per i pagamenti di prova, lo storico dei rimborsi, tutte le sessioni Windcave del carrello e le Windcave notes dell'ordine.

Capture (Auth mode)

Per un ordine in Windcave payment on hold con un'autorizzazione non ancora acquisita o rilasciata, il blocco mostra Capture Windcave payment con l'importo. Clicca e conferma Capture the authorised amount through Windcave now? Viene acquisito l'importo autorizzato (il totale dell'ordine, a meno che il pagamento non corrisponda all'ordine), l'ordine passa a Payment accepted e il pagamento viene registrato con l'ID della transazione di acquisizione. Se Windcave non accetta l'acquisizione, il blocco mostra Windcave capture failed: con il motivo, il motivo viene aggiunto alle note e l'ordine resta in attesa.

Refunds

Nel blocco Windcave payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Windcave. Conferma la domanda Refund this amount through Windcave? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il diritto di modificare gli ordini; non è necessario l'accesso alle pagine dei Moduli. I rimborsi sono calcolati sull'importo e sulla valuta approvati da Windcave, quindi dopo una discrepanza puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Un rimborso dopo un'acquisizione va sulla transazione di acquisizione. Il rimborso viene inviato all'ambiente (UAT o produzione) e all'account in cui è stato effettuato il pagamento, quindi le credenziali di quell'ambiente devono essere salvate. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note, con l'ID transazione Windcave. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.

Per un pagamento Auth non acquisito, il pulsante è Release authorisation (void) e può essere rilasciato solo l'intero importo. Un importo parziale genera un errore che ti chiede di rimborsare l'intero importo o di acquisire prima il pagamento.

Se Windcave rifiuta il rimborso, il blocco mostra Windcave declined the refund: con il motivo, e nessun rimborso viene registrato. Se Windcave sta ancora elaborando il rimborso, il blocco mostra Windcave has not confirmed the refund yet. See the order notes. e il rimborso non viene registrato. Controlla la transazione in Windcave Payline: se è stata approvata, registra manualmente il rimborso; altrimenti riprova. Un nuovo tentativo dello stesso rimborso non viene inviato due volte a Windcave.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Windcave. I rimborsi effettuati in Windcave Payline non vengono comunicati al negozio.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Windcave Payment Gateway è il primo blocco di Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo, 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 compaiono la riga Product: presta-payment-windcave 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 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 relativo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Windcave non viene mostrato ai clienti al checkout. Se comunque viene avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. La vetrina di 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 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 o dal ritorno del cliente, e rimborsi e acquisizioni funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il 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 a 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

Windcave non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia entrambe le credenziali: UAT API username e UAT API key in modalità di test, Production API username e Production API key in modalità reale. La pagina delle impostazioni mostra un avviso quando mancano. 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: il modulo non è ancora riuscito a ottenere il risultato da Windcave. Guarda il campo Log nella pagina del modulo: gli errori vengono sempre registrati, per esempio quando non è stato possibile verificare la sessione. Verifica che le credenziali dell'ambiente del pagamento siano salvate e corrette. La verifica viene ripetuta quando Windcave reinvia la notifica (il modulo risponde payment could not be verified yet, retry later con un codice di errore, così Windcave riprova), quando il cliente clicca su Check again e quando il cliente avvia un nuovo pagamento per lo stesso carrello. Il tuo server deve accettare le richieste di Windcave alla Notification URL mostrata nelle impostazioni.

La notifica risponde order not found: la sessione non è stata creata da questo negozio, per esempio una sessione di un altro negozio che usa lo stesso account Windcave. Viene ignorata.

Authentication failed nel log: il nome utente o la chiave della REST API sono errati, oppure appartengono all'altro ambiente. Le credenziali UAT funzionano solo in modalità di test, quelle di produzione solo in modalità reale. Le chiavi PxPay non funzionano.

Il cliente vede che Windcave non è riuscito ad avviare il pagamento con i dati di questo ordine: Windcave ha rifiutato la richiesta di sessione, per esempio per la valuta o per un metodo di pagamento non attivo sul tuo account. Il motivo esatto è nel log.

L'ordine è in Windcave payment on hold dopo il pagamento: leggi le note nel blocco Windcave payment. Il pagamento è un Auth in attesa di acquisizione, oppure l'importo pagato, la valuta o il riferimento del merchant non corrispondevano al carrello. Acquisisci, evadi o rimborsa il pagamento.

Pagamenti di prova e pagamenti reali: UAT e produzione sono separati. Ogni sessione viene verificata nell'ambiente in cui è stata creata, e rimborsi e acquisizioni vanno all'ambiente del pagamento, anche se cambi Test mode più tardi.

Un rimborso fallisce con un messaggio sull'ambiente: il pagamento è stato fatto in UAT o in produzione, e per quell'ambiente non sono salvate credenziali. Inseriscile e riprova.

Capture Windcave payment manca nel blocco dell'ordine: il pulsante compare solo per gli ordini in Windcave payment on hold pagati con Auth e non ancora acquisiti o rilasciati, e solo per i dipendenti autorizzati a modificare gli ordini.

Dove trovare i dettagli: errori e avvisi vengono sempre scritti nel log; attiva Debug log per registrare anche le richieste API e gli eventi di pagamento.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Windcave Payment Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Clean uninstall è attivo, vengono rimosse le impostazioni del modulo e il log. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. Le sessioni, le transazioni e i rimborsi Windcave e lo stato ordine Windcave payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono ancora essere rimborsati e acquisiti dopo una reinstallazione. Gli ordini esistenti mantengono le loro note di pagamento e gli ID transazione.

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