VibeFox Cashfree for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP più vecchie.

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 andare in produzione.

Account Cashfree: ti servono App ID e Secret Key del tuo account Cashfree, separatamente per l'ambiente di test (sandbox) e per la produzione, e un webhook nel Cashfree Merchant Dashboard (vedi Configurazione). La Secret Key viene usata anche per verificare i webhook, quindi non esiste una chiave webhook separata. La valuta del carrello deve essere abilitata per il tuo account Cashfree.

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 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 Cashfree Payments 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 Sandbox App ID e Sandbox Secret Key, aggiungi il webhook nel Cashfree Merchant Dashboard (vedi Configurazione), attiva Enable/Disable, fai clic su Save e prova un pagamento.

5. Quando sei pronto, inserisci l'App ID e la Secret Key live, disattiva Sandbox Mode e fai clic su Save.

All'installazione il modulo crea lo stato dell'ordine Cashfree 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 Cashfree Payments > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina spiega che l'ordine viene creato solo dopo la conferma del pagamento da parte di Cashfree. Quando il metodo di pagamento è attivo, la pagina ti avvisa se mancano le chiavi API della modalità selezionata (in tal caso il metodo di pagamento viene 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. Se salvi un metodo di pagamento attivo senza le chiavi della modalità selezionata, un avviso ti informa che resterà nascosto al checkout finché le chiavi non saranno impostate.

Cashfree Payments

Enable/Disable: Enable Cashfree Payments 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 salvato nell'ordine. Predefinito: Cashfree Payments. Obbligatorio.

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

Mode and API keys

Trova App ID e Secret Key nel Cashfree Merchant Dashboard, in Developers > API Keys. Le chiavi di test e quelle di produzione sono diverse.

Sandbox Mode: usa la sandbox di Cashfree per i test. Non viene addebitato denaro reale e il checkout mostra SANDBOX MODE - no real payments will be processed. sotto il metodo di pagamento. Predefinito: on. Disattivalo per i pagamenti live.

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

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

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

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

Le Secret Key salvate non vengono mai più mostrate. Il campo resta vuoto e riporta Saved — leave empty to keep it. Inserisci un valore nuovo solo se vuoi cambiarlo.

Clear saved secrets: spunta una Secret Key e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

I pagamenti mantengono l'ambiente in cui sono stati creati. I loro webhook vengono verificati, il loro stato viene controllato e i loro rimborsi vengono inviati con le chiavi di quell'ambiente; mantieni quindi compilate le chiavi sandbox finché i pagamenti sandbox non sono stati saldati dopo il passaggio alla produzione.

Webhook

Il webhook informa il tuo negozio che un pagamento è stato effettuato, non è riuscito o è stato rimborsato. Nel Cashfree Merchant Dashboard vai su Developers > Webhooks e aggiungi l'URL mostrato in Webhook URL in questa sezione, con gli eventi Payment e Refund. Con URL leggibili ha questo aspetto: https://your-shop/module/wcp_cashfree_payment/webhook. Copia l'URL esattamente come lo mostrano le impostazioni. Su un negozio HTTPS il modulo passa questo URL a Cashfree con ogni pagamento. Se il tuo negozio non usa HTTPS, questa sezione mostra un avviso.

Il modulo gestisce questi eventi (sono elencati anche in questa sezione):

Cashfree firma ogni webhook con la tua Secret Key. I webhook senza una firma valida vengono rifiutati. Un webhook deve essere firmato con la Secret Key dell'ambiente in cui è stato effettuato il pagamento, quindi una chiave sandbox non conferma mai un pagamento live. I webhook firmati relativi a pagamenti non avviati da questo negozio (ad esempio un altro negozio sullo stesso account Cashfree) vengono confermati e ignorati. Senza webhook, un ordine viene creato solo quando il cliente torna nel negozio dopo il pagamento. Se il cliente chiude il browser dopo aver pagato, solo il webhook (o il tentativo di pagamento successivo per lo stesso carrello) può creare l'ordine.

Advanced

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

Order ID prefix: gli ID ordine Cashfree sono composti da prefisso + ID carrello di PrestaShop; un nuovo tentativo per lo stesso carrello riceve un numero alla fine (ad esempio 123-2). Lascialo vuoto per usare il prefisso automatico di questo negozio, mostrato 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 avviso.

Debug log: gli errori vengono sempre registrati. Quando è attivo, le chiamate API Cashfree e i webhook vengono scritti anche in logs/cashfree_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi e dati dei clienti non vengono mai registrati. Predefinito: off.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni Cashfree e il registro del modulo. Ordini, relative transazioni e rimborsi Cashfree e lo stato ordine Cashfree payment on hold restano sempre, così gli ordini esistenti continuano a funzionare. Predefinito: off.

Checkout

Al passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Cashfree Payments) e conferma. Il modulo crea un ordine Cashfree per il totale del carrello nella valuta del carrello e apre una pagina di pagamento che mostra Redirecting to Cashfree for payment... e carica il checkout Cashfree. Se 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, ad esempio carta, UPI, internet banking o wallet. L'e-mail e il telefono di fatturazione del cliente vengono passati a Cashfree. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando Cashfree lo conferma: tramite il webhook firmato oppure tramite una richiesta lato server a Cashfree quando il cliente torna. A quel punto l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine. Il ritorno funziona anche in un altro browser, ad esempio quando il cliente torna da un'app UPI. Se la banca non ha ancora confermato il pagamento, una pagina Payment confirmation 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. e un pulsante Check again; il webhook crea l'ordine non appena la banca conferma il pagamento.

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

Se Cashfree non riesce ad avviare il pagamento, il cliente resta al checkout e 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 del carrello 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, e per quel carrello il metodo di pagamento non viene mostrato.

Il webhook funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo accetta solo pagamenti una tantum nel checkout Cashfree. Non prevede carte salvate, abbonamenti o pagamenti ricorrenti, autorizzazione e acquisizione separate, widget delle offerte Cashfree, COD tramite Cashfree o link di pagamento, né conversione di valuta: il carrello viene addebitato nella valuta del carrello.

Ordini e rimborsi

Order statuses

No order yet: il cliente è stato inviato a Cashfree e non ha pagato, il pagamento non è riuscito o il pagamento è ancora in attesa presso la banca. Esiste solo il carrello.

Payment accepted: il pagamento è stato confermato. Il pagamento viene registrato con l'ID pagamento Cashfree come ID transazione, e una nota mostra l'ID transazione e il gruppo del metodo di pagamento (ad esempio upi o credit_card).

Cashfree payment on hold: Cashfree ha segnalato un importo o una valuta pagati diversi dal totale del carrello (ad esempio il carrello è stato modificato in un'altra scheda dopo l'avvio del pagamento). La nota mostra l'importo atteso e quello ricevuto e l'ID transazione. Verifica il pagamento nel Cashfree Dashboard, poi evadi l'ordine oppure rimborsa il pagamento.

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

Un pagamento che arriva dopo l'annullamento dell'ordine viene comunque registrato e l'ordine torna pagato, perché il denaro è stato addebitato. Un ordine pagato non viene mai riportato indietro da un pagamento fallito successivo.

Cashfree payment block

La pagina dell'ordine mostra un blocco Cashfree payment con l'ID transazione, l'ordine Cashfree, lo stato del pagamento, l'importo pagato e rimborsato, un badge Sandbox per i pagamenti sandbox, lo storico dei rimborsi e le Cashfree notes dell'ordine.

Refunds

Nel blocco Cashfree payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Cashfree. Conferma la domanda Refund this amount through Cashfree? 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 nell'importo e nella valuta addebitati da Cashfree, quindi dopo una differenza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato all'ordine Cashfree che è stato pagato, nell'ambiente (sandbox o live) in cui è stato pagato, quindi le chiavi di quell'ambiente devono essere impostate. Se Cashfree non accetta il rimborso, o lo segnala come annullato o rifiutato, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso avviato viene aggiunto allo storico dei rimborsi e alle note con il suo ID, importo e stato. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale non cambia lo stato. I rimborsi sono disponibili una volta che Cashfree ha confermato il pagamento.

Lo stato finale del rimborso arriva tramite il webhook dei rimborsi e viene aggiunto alle note. Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Cashfree.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox Cashfree Payments è il primo blocco di Modules > Module Manager > VibeFox Cashfree Payments > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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 di essi ci sono la riga Product: presta-payment-cashfree e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con l'autorizzazione 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 spiega il motivo, ad esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on seguito da una data. Dopo una modifica 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: quello 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, 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. 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 e i rimborsi funzionano.

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

Cashfree non compare 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. La pagina delle impostazioni mostra un avviso quando mancano le chiavi. Il metodo di pagamento viene nascosto anche quando il totale del carrello è sotto il minimo Cashfree. 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 webhook non funziona. Verifica che il tuo negozio usi HTTPS, che l'URL in Developers > Webhooks sia esattamente quello mostrato in Webhook URL e che siano selezionati gli eventi Payment. Verifica che la Secret Key nelle impostazioni appartenga all'ambiente in cui è stato effettuato il pagamento. Il Cashfree Dashboard mostra la risposta del tuo negozio per ogni webhook. L'ordine viene creato anche quando il cliente torna nel negozio dopo il pagamento, e al tentativo di pagamento successivo per lo stesso carrello.

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 effettuato il pagamento. Verifica che le chiavi sandbox e live non siano scambiate.

Il webhook risponde Ignored: il webhook è firmato correttamente ma riguarda un pagamento non avviato da questo negozio, ad esempio un altro negozio sullo stesso account Cashfree. Assegna a ciascun negozio il proprio Order ID prefix.

Il webhook risponde Busy, retry later: l'ordine era in fase di creazione da un'altra richiesta nello stesso momento, oppure l'ordine non ha potuto essere creato (ad esempio perché il modulo è disattivato). Cashfree ritenta il webhook. Attiva Debug log per vedere il motivo.

Il cliente vede The Cashfree payment page could not be loaded: lo script di Cashfree non è stato caricato nel browser, ad 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: controlla il campo Log nella pagina del modulo. Le cause tipiche sono chiavi errate per la modalità selezionata o una valuta non abilitata per il tuo account Cashfree.

Il cliente vede We could not verify the payment: il link di ritorno non corrispondeva al carrello. Se il denaro è stato addebitato, il webhook crea comunque l'ordine. Verifica il pagamento nel Cashfree Dashboard prima che il cliente paghi di nuovo.

L'ordine è in Cashfree payment on hold dopo il pagamento: leggi le note nel blocco Cashfree payment (vedi Order statuses), poi evadi l'ordine oppure rimborsa il pagamento.

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

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Cashfree Payments 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 Cashfree e il registro vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. Le transazioni e i rimborsi Cashfree e lo stato ordine Cashfree payment on hold restano sempre, 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 transazione.

Cashfree è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Cashfree né approvato da Cashfree.