VibeFox Windcave for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

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 plugin. I metodi di pagamento che vuoi offrire (carte, wallet e altri) devono essere attivati sul tuo account Windcave.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un dominio.

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e clicca su Install Now. Puoi anche caricare la cartella wcp_windcave_payment_gateway in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

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

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e clicca su Activate.

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

6. Scegli il tipo di transazione e i metodi di pagamento, attiva Enable/Disable e salva. Fai un pagamento di prova con Test mode attivo, poi disattiva Test mode per incassare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Windcave. Finché la modalità test è attiva, la pagina mostra Test mode is on: payments go to the Windcave UAT environment and no real money is taken. Nell'elenco dei metodi di pagamento, Windcave risulta da configurare finché la modalità attuale non ha sia un nome utente API sia una chiave API. La versione del plugin è mostrata in fondo alla pagina.

Generali

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Credit/Debit Card (Windcave).

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 della REST API rilasciate 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à test usa solo le credenziali UAT, la modalità live solo quelle di produzione.

Test mode: Use the Windcave UAT test environment (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à test).

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

Pagamento

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

Purchase (capture immediately): il denaro viene addebitato quando il cliente paga.

Auth (authorise now, capture later): il denaro viene solo riservato. L'ordine passa In attesa e incassi il denaro con Capture Windcave payment nelle azioni dell'ordine, oppure lo rilasci rimborsando l'intero importo. Le autorizzazioni non acquisite scadono dopo alcuni giorni.

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. Devono essere attivati sul tuo account Windcave. Lascia il campo vuoto per mostrare tutti i metodi attivi sull'account. Predefinito: Cards.

Avanzate

Debug log: Log API requests and payment events. Il log si trova in WooCommerce > Status > Logs, origine wcp_windcave_payment_gateway. Errori e avvisi sono sempre registrati; questa opzione aggiunge le richieste API e gli eventi di pagamento. Le chiavi API, i dati della carta e i dati personali dei clienti sono mascherati. Predefinito: disattivato.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. I dati di pagamento salvati sugli ordini (gli ID transazione Windcave necessari per i rimborsi) vengono sempre conservati. Predefinito: disattivato.

URL di notifica

Non devi configurare un URL di notifica in Windcave. Il plugin invia i propri indirizzi di ritorno e l'indirizzo di notifica con ogni sessione di pagamento. Windcave invia la notifica (Fail-Proof Result Notification) a https://your-site/wc-api/windcave_p_notification/. Né il ritorno del cliente né la notifica sono firmati da Windcave, quindi il plugin non se ne fida mai da solo: legge sempre il risultato della sessione dalla REST API di Windcave, con le tue credenziali dell'ambiente in cui è stata creata la sessione.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit/Debit Card (Windcave)) e completa l'ordine. Il plugin crea una sessione di pagamento Windcave per il totale dell'ordine nella valuta dell'ordine e invia il cliente alla Windcave Hosted Payment Page. Il numero d'ordine viene inviato come riferimento del merchant, insieme alla lingua del negozio e al nome, all'e-mail, al telefono e agli indirizzi di fatturazione e spedizione del cliente. In modalità test, il blocco Checkout mostra Test mode: payments go to the Windcave UAT environment, no real money is taken. sotto il metodo di pagamento.

Dopo il pagamento, il cliente torna alla pagina di ordine ricevuto del tuo negozio. L'ordine viene segnato come pagato solo quando Windcave lo conferma: il plugin 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 ogni ordine garantisce che il pagamento venga applicato una sola volta. Se il risultato non è ancora noto, la pagina di ordine ricevuto lo verifica una volta ancora e 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.

Se il cliente torna senza un pagamento completato, la pagina di checkout (o la pagina Pay for order, se il tentativo è iniziato lì) mostra uno di questi messaggi:

Declined: il tuo pagamento è stato rifiutato. Riprova o scegli un altro metodo di pagamento.

Cancelled or expired: il pagamento non è stato completato nella pagina Windcave. Il tuo ordine è salvato: puoi riprovare o scegliere un altro metodo di pagamento.

Not confirmed yet: non siamo ancora riusciti a confermare il tuo pagamento. Se lo hai completato, non pagare di nuovo: riceverai un'e-mail di conferma appena Windcave lo confermerà.

Return could not be processed: non siamo riusciti a elaborare il tuo ritorno dalla pagina di pagamento. Se ti è stato addebitato un importo, contattaci prima di pagare di nuovo.

Il carrello non viene svuotato e lo stock non viene ridotto prima che il cliente paghi. Un cliente può pagare di nuovo un ordine non pagato, per esempio dalla pagina Pay for order. Un nuovo tentativo verifica prima la sessione precedente: se è già pagata, non viene creato un secondo pagamento; se il cliente non ha mai usato la pagina di pagamento e l'ordine 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 vede un breve messaggio: che Windcave non ha potuto avviare il pagamento con i dati di questo ordine, oppure che il servizio di pagamento è temporaneamente non disponibile. Il motivo viene aggiunto alle note dell'ordine. Se la modalità attuale non ha credenziali, il cliente vede This payment method is not available at the moment. Please choose another payment method or contact us.

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 plugin non prevede abbonamenti o pagamenti ricorrenti, carte salvate, un modulo carta integrato nel tuo sito (il cliente paga sempre nella pagina Windcave), supporto all'API PxPay 2.0, né aggiunge sovrapprezzi. Se Windcave aggiunge un sovrapprezzo, l'ordine viene abbinato alla transazione principale.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a Windcave e non ha ancora pagato, oppure Windcave non ha ancora confermato il pagamento. Se il cliente annulla o la sessione scade, l'ordine resta In attesa di pagamento e viene aggiunta una nota.

Processing or Completed: un pagamento Purchase è stato confermato. WooCommerce imposta In lavorazione, oppure Completato per gli ordini che non richiedono spedizione, come di consueto. La nota dell'ordine mostra l'importo, l'ID transazione Windcave, il codice di autorizzazione, il tipo di carta con il numero mascherato e l'ambiente (UAT o produzione). L'ID transazione dell'ordine è l'ID transazione Windcave.

On hold (authorised): un pagamento Auth è stato approvato ma non ancora acquisito. La nota dell'ordine spiega come acquisirlo o rilasciarlo.

On hold (does not match): Windcave ha comunicato un importo, una valuta, un riferimento del merchant o un tipo di transazione diversi da quelli dell'ordine (per esempio, l'ordine è stato modificato dopo l'avvio del pagamento). La nota elenca le differenze. Controlla il pagamento in Windcave Payline prima della spedizione e, se necessario, rimborsalo.

Failed: il pagamento è stato rifiutato. La nota mostra il testo e il codice di risposta di Windcave. Il cliente può riprovare.

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

Acquisizione (modalità Auth)

Apri l'ordine, scegli Capture Windcave payment nelle azioni dell'ordine e clicca sul pulsante di aggiornamento. L'azione compare solo per un ordine In attesa con un'autorizzazione non ancora acquisita o rilasciata. Viene acquisito l'intero totale dell'ordine, l'acquisizione viene aggiunta alle note dell'ordine e l'ordine passa come ordine pagato (di solito In lavorazione). Se Windcave non accetta l'acquisizione, la schermata dell'ordine mostra Windcave capture failed: con il motivo, e il motivo viene aggiunto alle note dell'ordine.

Rimborsi

Apri l'ordine, clicca su Refund, inserisci l'importo e clicca su Refund via Windcave. Sono supportati rimborsi totali e parziali. Il rimborso viene inviato all'ambiente (UAT o produzione) e al conto in cui è stato effettuato il pagamento, quindi le credenziali di quell'ambiente devono essere salvate. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID transazione Windcave.

Per un pagamento Auth non acquisito è possibile solo un rimborso totale: rilascia (annulla) l'autorizzazione. Un importo parziale genera un errore che ti chiede di rimborsare l'importo totale o di acquisire prima il pagamento.

Se Windcave rifiuta il rimborso, WooCommerce mostra Windcave declined the refund: con il motivo, e il rimborso non viene registrato. Se Windcave sta ancora elaborando il rimborso, WooCommerce 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 tentativo ripetuto dello stesso rimborso non viene inviato due volte a Windcave. I rimborsi effettuati in Windcave Payline non vengono comunicati al negozio.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Windcave. Incolla la chiave in License key e clicca su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per verificare 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 vibefox.net.

Una chiave funziona su un dominio. Rimuovere la chiave da un sito non libera lo slot del dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Windcave 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. Gli amministratori del negozio connessi continuano a vedere il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati, e rimborsi e acquisizioni funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Windcave does not appear at checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità attuale abbia entrambe le credenziali: UAT API username e UAT API key in modalità test, Production API username e Production API key in modalità live.

The payment went through, but the order stays Pending payment: il plugin non è ancora riuscito a ottenere il risultato da Windcave. Apri le note dell'ordine: una nota indica quando la sessione non è stata verificata e perché. Controlla che le credenziali dell'ambiente del pagamento siano salvate e corrette. La verifica viene ripetuta quando Windcave invia di nuovo la notifica (il plugin risponde con un errore finché il risultato non può essere verificato, così che Windcave riprovi) e quando il cliente apre la pagina di ordine ricevuto. Il tuo server deve accettare le richieste di Windcave a https://your-site/wc-api/windcave_p_notification/.

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

The customer sees that Windcave could not start the payment with the details of this order: 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 è nelle note dell'ordine e nel log.

Order is On hold after payment: leggi la nota dell'ordine. Il pagamento è un Auth in attesa di acquisizione, oppure l'importo pagato, la valuta o il riferimento del merchant non coincidevano con l'ordine. Acquisisci, evadi o rimborsa il pagamento.

Test payments and live payments: UAT e produzione sono separati. Ogni sessione viene verificata nell'ambiente in cui è stata creata, e rimborsi e acquisizioni vanno nell'ambiente del pagamento, anche se cambi Test mode in seguito. Gli ordini creati con la versione 1.0 del plugin usano l'ambiente della vecchia impostazione API URL.

Refund fails with a message about the environment: il pagamento è stato effettuato in UAT o in produzione, e non ci sono credenziali salvate per quell'ambiente. Inseriscile e riprova.

Capture Windcave payment is missing in the order actions: l'azione viene mostrata solo per gli ordini In attesa pagati con Auth che non sono ancora stati acquisiti o rilasciati.

Where to find details: errori e avvisi vengono sempre scritti in WooCommerce > Status > Logs, origine wcp_windcave_payment_gateway. Attiva Debug log per registrare anche le richieste API e gli eventi di pagamento.

The license block shows an error: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e clicca su Check now. Se l'indirizzo del sito è cambiato, clicca 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

Disattivare il 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, le opzioni del plugin e i log (file di log, compresi quelli ruotati, e voci di log nel database) vengono rimossi solo se Clean uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID transazione Windcave.

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