VibeFox Cashfree for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

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

PHP: 8.0 o successivo.

HTTPS: Cashfree invia i webhook solo a URL https://. Senza HTTPS i pagamenti vengono comunque confermati quando il cliente torna nel negozio, ma attiva HTTPS prima di passare alla modalità live.

Account Cashfree: ti servono App ID e Secret Key del tuo account Cashfree, separatamente per l'ambiente di test (sandbox) e per quello di produzione, e un webhook nella Cashfree Merchant Dashboard (vedi Configurazione). La Secret Key serve anche a verificare i webhook, quindi non esiste un segreto webhook separato. La valuta dell'ordine deve essere abilitata per il tuo account Cashfree.

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_cashfree_payment in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

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

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

5. Inserisci Sandbox App ID e Sandbox Secret Key, aggiungi il webhook nella Cashfree Merchant Dashboard (vedi Configurazione), attiva Enable/Disable e prova un pagamento.

6. Quando sei pronto, inserisci App ID e Secret Key live e deseleziona Sandbox Mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Cashfree Payments. Quando il metodo di pagamento è attivo, la pagina ti avvisa se mancano le chiavi API della modalità selezionata (il metodo di pagamento viene allora nascosto al checkout) e mostra Sandbox mode is on: customers see a test checkout and no real money is charged. finché la modalità sandbox è attiva. Quando salvi un gateway attivo senza le chiavi della modalità selezionata, un messaggio di errore ti avvisa che il metodo di pagamento resta nascosto al checkout finché non vengono impostate.

Generali

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Cashfree Payments.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Modalità e chiavi API

Trovi App ID e Secret Key nella Cashfree Merchant Dashboard, sotto Developers > API Keys. Le chiavi Test e Production sono diverse: inserisci ciascuna nella propria sezione.

Sandbox Mode: Enable Sandbox (test) mode usa la sandbox Cashfree per i test. Non viene addebitato denaro reale e il checkout mostra SANDBOX MODE - no real payments will be processed. Predefinito: attivato. Deseleziona per i pagamenti live.

Credenziali sandbox

Sandbox App ID: l'App ID del tuo ambiente di test Cashfree.

Sandbox Secret Key: la Secret Key del tuo ambiente di test Cashfree.

Credenziali live

App ID: l'App ID del tuo ambiente di produzione Cashfree.

Secret Key: la Secret Key del tuo ambiente di produzione Cashfree.

Gli ordini mantengono l'ambiente in cui sono stati creati. I loro webhook vengono verificati e i loro rimborsi inviati con le chiavi di quell'ambiente, quindi lascia compilate le chiavi sandbox finché gli ordini sandbox non sono chiusi dopo il passaggio alla modalità live.

Webhook

Il webhook comunica al tuo negozio che un pagamento è stato effettuato, non è riuscito o è stato rimborsato. Nella Cashfree Merchant Dashboard vai su Developers > Webhooks e aggiungi l'URL mostrato in questa sezione, con gli eventi Payment e Refund. Ha una forma come https://your-site/wc-api/cashfree_p/?action=webhook. Su un sito HTTPS il plugin passa anche questo URL a Cashfree con ogni ordine. Se il tuo sito non usa HTTPS, questa sezione mostra un avviso.

Il plugin gestisce questi eventi:

Cashfree firma ogni webhook con la tua Secret Key. I webhook senza una firma valida vengono rifiutati. I webhook firmati per ordini non creati da questo negozio (per esempio da un altro negozio sullo stesso account Cashfree) vengono confermati e ignorati. Senza il webhook, un ordine viene confermato solo quando il cliente torna nel negozio dopo aver pagato. Se il cliente chiude il browser dopo aver pagato, solo il webhook può confermare l'ordine.

Avanzate

API Version: la versione dell'API Cashfree da usare.

Order ID prefix: gli ID ordine Cashfree sono formati come prefisso + ID ordine WooCommerce; un tentativo ripetuto riceve un numero alla fine. Lascialo vuoto per usare il prefisso automatico di questo sito, indicato nella descrizione del campo. Usa un prefisso diverso per ogni negozio collegato allo stesso account Cashfree. Solo lettere, cifre, "_" e "-", fino a 20 caratteri. Gli altri caratteri vengono rimossi al salvataggio con un messaggio.

Debug log: Log Cashfree API events for debugging. Gli errori vengono sempre registrati. Se attivo, le chiamate API e i webhook vengono scritti anche in WooCommerce > Status > Logs, origine wcp_cashfree_payment. Chiavi e dati del cliente non vengono mai registrati. Predefinito: disattivato.

Delete Data on Uninstall: Delete all plugin data when uninstalling. Se attivo, eliminando il plugin vengono rimosse le impostazioni Cashfree, i registri del plugin e i riferimenti Cashfree salvati negli ordini. Gli ordini stessi vengono conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Cashfree Payments) e fa l'ordine. Il plugin crea un ordine Cashfree per il totale dell'ordine nella valuta dell'ordine e apre la pagina Pay for order, che mostra Redirecting to Cashfree for payment... e carica il checkout Cashfree. Se la pagina non si apre da sola, il cliente può fare clic su Pay Now. Nel checkout Cashfree il cliente paga con qualsiasi metodo attivo nel tuo account Cashfree, per esempio carta, UPI, internet banking o wallet.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Cashfree: tramite il webhook firmato oppure con una richiesta lato server a Cashfree quando il cliente torna. Se la banca non ha ancora confermato il pagamento, la pagina Ordine ricevuto mostra Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again.

Se il pagamento non riesce o il cliente lascia la pagina Cashfree senza pagare, il cliente torna alla pagina Pay for order con The Cashfree payment was not completed. Please try again or choose another payment method. Un pagamento Cashfree aperto viene riutilizzato quando il cliente riprova. Se il totale dell'ordine è cambiato o la sessione sta per scadere, il vecchio ordine Cashfree viene chiuso e ne viene creato uno nuovo, così l'ordine non può essere pagato due volte. Se l'ordine era già stato pagato su Cashfree ma non registrato, il tentativo successivo registra il pagamento invece di addebitare di nuovo.

Se Cashfree non riesce ad avviare il pagamento, il cliente vede We could not start the Cashfree payment. Please try again or choose another payment method. Il motivo tecnico viene scritto nel registro. Un totale d'ordine inferiore al minimo Cashfree (1 unità della valuta; 0,01 per BHD, JOD, KWD, OMR e 0,1 per TND) non può essere pagato con Cashfree.

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). I testi per il cliente sono tradotti in hindi.

Il plugin accetta pagamenti una tantum solo sul checkout Cashfree. Non prevede carte salvate, abbonamenti o pagamenti ricorrenti, autorizzazione e acquisizione separate, widget delle offerte Cashfree, pagamento alla consegna (COD) o link di pagamento tramite Cashfree, né conversione di valuta: l'ordine viene addebitato nella valuta dell'ordine.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a Cashfree e non ha ancora pagato, oppure il pagamento è ancora in attesa presso la banca. Quando il cliente torna con un pagamento in attesa, una nota indica che il plugin attende il webhook Cashfree.

Processing: il pagamento è stato confermato (gli ordini con soli prodotti virtuali scaricabili diventano Completato, come da impostazione predefinita di WooCommerce). La nota dell'ordine mostra l'ID transazione Cashfree e il gruppo del metodo di pagamento. L'ID transazione dell'ordine è l'ID pagamento Cashfree. Un pagamento arrivato dopo l'annullamento dell'ordine viene comunque registrato, perché il denaro è stato incassato.

On hold: Cashfree ha segnalato un importo o una valuta pagati diversi dal totale dell'ordine. La nota dell'ordine mostra l'importo atteso e quello ricevuto e l'ID transazione. Verifica il pagamento nella dashboard Cashfree e completa o rimborsa l'ordine manualmente.

Failed: il pagamento non è riuscito o è stato annullato presso Cashfree. La nota mostra lo stato e il motivo Cashfree. Ogni ulteriore tentativo fallito aggiunge una nota.

Un ordine pagato non viene mai riportato indietro da un webhook o da un ritorno successivo.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Cashfree Payments (il pulsante mostra il titolo del metodo di pagamento). Sono supportati rimborsi totali e parziali. Il rimborso viene inviato all'ordine Cashfree pagato, nell'ambiente (sandbox o live) in cui è stato pagato, quindi devono essere impostate le chiavi di quell'ambiente. Se Cashfree non accetta il rimborso, oppure lo segnala come annullato o rifiutato, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso avviato viene aggiunto alle note dell'ordine con ID, importo e stato del rimborso. Lo stato finale arriva con il webhook di rimborso come un'altra nota dell'ordine.

I webhook di stato dei rimborsi vengono aggiunti solo come note. Non vengono registrati automaticamente come rimborsi WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Cashfree Payments. Incolla la chiave in License key e fai clic 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 solo dominio. Rimuovere la chiave da un sito non libera il posto del dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Cashfree 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. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

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

Risoluzione dei problemi

Cashfree non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia le sue chiavi: Sandbox App ID e Sandbox Secret Key in modalità sandbox, App ID e Secret Key in modalità live. Il metodo di pagamento è nascosto anche quando il totale dell'ordine è sotto il minimo Cashfree. La pagina delle impostazioni mostra un avviso quando mancano le chiavi.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: il webhook non funziona. Verifica che il tuo sito usi HTTPS, che l'URL in Developers > Webhooks sia esattamente quello mostrato nelle impostazioni e che siano selezionati gli eventi Payment. Controlla che la Secret Key nelle impostazioni appartenga all'ambiente in cui è stato pagato l'ordine. L'ordine viene confermato anche quando il cliente torna nel negozio dopo aver pagato e al tentativo di pagamento successivo.

Il webhook risponde Missing signature o Invalid signature: la chiamata non conteneva una firma Cashfree valida, oppure la Secret Key nelle impostazioni non corrisponde all'ambiente in cui è stato creato l'ordine. Cashfree ripete il webhook.

Il webhook risponde Ignored: il webhook è firmato correttamente ma riguarda un ordine non creato da questo negozio, per esempio da un altro negozio sullo stesso account Cashfree. Assegna a ogni negozio un proprio Order ID prefix.

Il webhook risponde Busy, retry later: l'ordine era in elaborazione da un'altra richiesta nello stesso momento. Cashfree ripete il webhook.

Il cliente vede The Cashfree payment page could not be loaded: lo script Cashfree non è stato caricato nel browser, per esempio a causa di un blocco. Il cliente può fare di nuovo clic su Pay Now oppure su Choose another payment method.

Il cliente vede We could not start the Cashfree payment: attiva il Debug log e controlla WooCommerce > Status > Logs, origine wcp_cashfree_payment. Le cause tipiche sono chiavi errate per la modalità selezionata oppure una valuta non abilitata per il tuo account Cashfree.

Il cliente vede The minimum amount for a Cashfree payment is …: il totale dell'ordine è sotto il minimo Cashfree per la valuta.

Il cliente vede We could not verify the payment: il link di ritorno non corrispondeva all'ordine. Se il denaro è stato addebitato, il webhook conferma comunque l'ordine. Verifica il pagamento nella dashboard Cashfree prima che il cliente paghi di nuovo.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta pagati erano diversi dall'ordine. Completa l'ordine oppure rimborsa il pagamento.

Il rimborso non riesce con un messaggio su modalità sandbox o live: l'ordine è stato pagato in quell'ambiente e le sue chiavi API non sono impostate. Inseriscile e riprova.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto 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

Disattivare il plugin mantiene 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. Impostazioni del gateway, dati Cashfree salvati negli ordini e registri vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.

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