VibeFox Razorpay 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.

Account Razorpay: ti servono il Key ID e il Key Secret del tuo account Razorpay per la modalità test, e per la modalità live una volta attivato il tuo account. Un webhook con un secret a tua scelta è fortemente consigliato (vedi Configurazione). I pagamenti in valute diverse dall'INR richiedono che International Payments sia attivo sul tuo account Razorpay.

Chiave di licenza VibeFox: acquistata 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 Razorpay Payment nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco della licenza in cima alla pagina Configure, e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci il tuo Test Key ID e il tuo Test Key Secret, configura il webhook nel Razorpay Dashboard e inserisci il suo secret (vedi Configurazione).

5. Attiva Enable/Disable e fai clic su Save. Effettua un pagamento di prova con Test mode attivo. Quando sei pronto, inserisci le chiavi Live e disattiva Test mode.

All'installazione il modulo crea due stati dell'ordine, Razorpay payment authorized e Razorpay 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 Razorpay Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra avvisi: mancano le chiavi della modalità corrente (Razorpay non viene quindi mostrato al checkout), il Key ID non inizia con rzp_test_ in modalità test o con rzp_live_ in modalità live, la modalità test è attiva, il webhook secret è vuoto oppure la valuta predefinita del negozio non è INR e richiede International Payments sul tuo account Razorpay. Gli spazi incollati insieme ai Key ID vengono rimossi al salvataggio.

Razorpay

Enable/Disable: Enable Razorpay Payment 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 memorizzato nell'ordine. Predefinito: UPI, Cards, NetBanking. Obbligatorio: un titolo vuoto genera l'errore Enter a title for the payment method.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay.

Chiavi API

Ottieni le chiavi nel Razorpay Dashboard, in Account & Settings > API Keys. Passa il Dashboard alla modalità test per generare le chiavi di test (rzp_test_...). Le chiavi live (rzp_live_...) sono disponibili dopo l'attivazione del tuo account.

Test mode: usa le chiavi della modalità test, quindi non viene addebitato denaro reale. Predefinito: attivo. Disattivalo per accettare pagamenti reali. Pagamenti, acquisizioni e rimborsi di un ordine usano sempre le chiavi della modalità in cui l'ordine è stato pagato, quindi cambiare modalità in seguito non influisce sugli ordini esistenti.

Test Key ID: il Key ID del Razorpay Dashboard in modalità test. Inizia con rzp_test_.

Test Key Secret: il Key Secret del Razorpay Dashboard in modalità test.

Live Key ID: il Key ID del Razorpay Dashboard in modalità live. Inizia con rzp_live_.

Live Key Secret: il Key Secret del Razorpay Dashboard in modalità live.

I secret salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi modificarlo.

Cancellare i secret salvati: spunta Test Key Secret, Live Key Secret o Webhook Secret e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Pagamento

Payment Action: quando viene prelevato il denaro. Predefinito: Authorize & Capture.

Webhook

Il webhook conferma i pagamenti anche quando il cliente chiude il browser subito dopo aver pagato, e registra i rimborsi effettuati nel Razorpay Dashboard. Nel Razorpay Dashboard vai su Account & Settings > Webhooks e aggiungi un webhook in modalità test e un altro in modalità live. Usa l'URL mostrato in Webhook URL in questa sezione. Con URL semplificati ha questo aspetto: https://your-shop/module/wcp_razorpay_payment/webhook, eventualmente con un codice lingua come /en/. Copialo esattamente come lo mostrano le impostazioni. Inserisci in Razorpay un secret a tua scelta e seleziona questi eventi (sono elencati anche in questa sezione):

Webhook Secret: il secret inserito al momento della creazione del webhook. Usa lo stesso secret per il webhook di test e quello live, perché il modulo ha un unico campo per entrambi. I webhook senza una firma valida vengono rifiutati. Senza il webhook, un pagamento viene confermato solo quando il cliente torna dalla finestra popup, oppure quando il cliente avvia di nuovo il pagamento per lo stesso carrello più tardi.

Avanzate

Enable Logging: il registro viene scritto in logs/razorpay_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati; questa opzione aggiunge i dettagli di debug. Chiavi, firme e dati di contatto dei clienti non vengono mai registrati. Predefinito: disattivato.

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

Delete Data on Uninstall: se attivo, disinstallando il modulo vengono rimosse le sue impostazioni e il registro. Gli ordini, le transazioni e i rimborsi Razorpay e gli stati dell'ordine del modulo restano sempre. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita UPI, Cards, NetBanking) e conferma. Il modulo crea un ordine Razorpay per l'importo esatto del carrello e la valuta, e apre la pagina Razorpay payment del tuo negozio. La finestra popup di Razorpay Checkout si apre lì automaticamente, con nome, email e telefono del cliente già compilati. Il pagamento compare in Razorpay come Cart e con il numero del carrello. In questa fase non esiste ancora alcun ordine PrestaShop. Se la finestra popup viene chiusa, il cliente può fare clic su Pay Now per riaprirla oppure su Choose another payment method per tornare al checkout. Il carrello viene conservato. In modalità test la pagina mostra Razorpay Test mode: no real money will be charged.

Dopo un pagamento riuscito il cliente vede Please wait while we process your payment... Il modulo verifica la firma di Razorpay, recupera il pagamento tramite l'API di Razorpay e confronta importo e valuta con il carrello. L'ordine viene contrassegnato come pagato solo dopo la conferma di Razorpay. Poi l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine. Se la firma è valida ma in quel momento il pagamento non può essere recuperato, l'ordine viene creato nello stato Razorpay payment on hold e il webhook lo conferma più tardi.

Se il cliente avvia di nuovo il pagamento per lo stesso carrello, il modulo riutilizza il suo ordine Razorpay quando importo, valuta e modalità non sono cambiati. Se quell'ordine Razorpay è già stato pagato, per esempio perché il cliente ha chiuso il browser e non c'è webhook, il modulo crea l'ordine a partire da quel pagamento invece di chiederne un secondo. Se il totale del carrello è cambiato, viene creato un nuovo ordine Razorpay.

Messaggi che il cliente può vedere:

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

Il modulo accetta solo pagamenti una tantum. Non prevede abbonamenti né pagamenti ricorrenti, carte salvate, Razorpay Magic Checkout, Payment Links o Route (pagamenti suddivisi), né widget di offerta o di accessibilità economica.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente non ha pagato, oppure Razorpay non ha ancora confermato il pagamento. Esiste solo il carrello. Un tentativo di pagamento non riuscito non crea un ordine; il cliente può pagare di nuovo.

Payment accepted: il pagamento è stato acquisito e confermato. Viene registrato con l'ID del pagamento Razorpay (pay_...) come ID della transazione, e una nota mostra l'ID del pagamento, l'importo e come è stato confermato (callback, webhook, sync o admin).

Razorpay payment authorized: il pagamento è stato solo autorizzato (Authorize Only). Acquisiscilo per completare l'ordine.

Razorpay payment on hold: viene impostato in questi casi, ognuno con una nota: l'importo o la valuta pagati non corrispondono al carrello (per esempio, il carrello è stato modificato dopo l'avvio del pagamento), il pagamento è stato acquisito per un ordine annullato, oppure il pagamento non è stato verificabile tramite l'API di Razorpay in quel momento. Un importo pagato nella valuta dell'ordine viene registrato sull'ordine. Controlla l'ordine ed evadilo oppure rimborsa il pagamento.

Cancelled: un pagamento che arriva più tardi per un ordine annullato non riapre automaticamente l'ordine: un pagamento autorizzato non viene acquisito e riceve solo una nota, mentre un pagamento acquisito porta l'ordine in Razorpay payment on hold. Una notifica ripetuta del pagamento che ha già pagato l'ordine non cambia nulla, anche se nel frattempo hai annullato l'ordine.

Refunded: il pagamento è stato rimborsato integralmente.

Se arriva un pagamento aggiuntivo per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di rimborsarlo nel Razorpay Dashboard se non era previsto. Un payment.failed tardivo per un ordine pagato aggiunge solo una nota.

Blocco del pagamento Razorpay

La pagina dell'ordine mostra un blocco Razorpay payment con l'ID del pagamento Razorpay, l'ordine Razorpay, lo stato del pagamento, Paid / refunded (l'importo addebitato da Razorpay e quello rimborsato), un badge Test mode per i pagamenti di prova, lo storico dei rimborsi e le Razorpay notes dell'ordine. Acquisizione e rimborsi richiedono il permesso di modificare gli ordini; non serve l'accesso alla configurazione del modulo.

Acquisizione (Authorize Only)

Apri l'ordine nello stato Razorpay payment authorized, fai clic su Capture Razorpay payment nel blocco Razorpay e conferma. Il pagamento viene acquisito nella modalità in cui è stato autorizzato, e l'ordine diventa Payment accepted. Se Razorpay rifiuta, il blocco e le note mostrano Razorpay capture failed: con il motivo. Un'acquisizione effettuata nel Razorpay Dashboard completa l'ordine tramite il webhook.

Rimborsi

Nel blocco Razorpay inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Razorpay. Conferma la domanda Refund this amount through Razorpay? This cannot be undone. Sono supportati rimborsi totali e parziali. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da Razorpay, quindi dopo una differenza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Un importo superiore mostra Invalid refund amount: at most seguito dall'importo. Il rimborso viene inviato con le chiavi della modalità in cui è stato effettuato il pagamento. Se Razorpay non accetta il rimborso, il blocco mostra Razorpay refund failed: con il motivo, e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note, con l'ID del rimborso Razorpay, l'importo e lo stato. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non modifica lo stato. I rimborsi sono disponibili una volta acquisito il pagamento.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Razorpay.

I rimborsi effettuati nel Razorpay Dashboard arrivano tramite il webhook e vengono registrati una sola volta nello storico dei rimborsi e nelle note. Quando l'ordine è rimborsato integralmente, il suo stato diventa Refunded. Un rimborso del Dashboard in un'altra valuta o superiore all'importo rimborsabile non viene registrato automaticamente; una nota chiede di registrarlo manualmente.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Razorpay Payment è il primo blocco nella pagina Modules > Module Manager > VibeFox Razorpay Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché 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 si trovano la riga Product: presta-payment-razorpay 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 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, Razorpay 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 hai effettuato l'accesso 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, e acquisizioni e rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Razorpay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia entrambe le chiavi: Test Key ID e Test Key Secret in modalità test, Live Key ID e Live Key Secret in modalità live. 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 webhook non funziona. Nel Razorpay Dashboard verifica che il webhook esista nella modalità che usi (Test o Live), che il suo URL sia esattamente quello mostrato in Webhook URL e che siano selezionati i cinque eventi. Verifica che Webhook Secret sia lo stesso secret di Razorpay. L'ordine viene creato anche quando il cliente torna dalla finestra popup o avvia di nuovo il pagamento per lo stesso carrello.

Il webhook risponde Webhook secret not configured: Webhook Secret è vuoto. Inserisci il secret del webhook di Razorpay. Razorpay invierà di nuovo l'evento più tardi.

Il webhook risponde Invalid signature oppure Missing signature: il secret nelle impostazioni è diverso da quello del webhook di Razorpay. Inserisci lo stesso secret in entrambi i punti, per il webhook di test e quello live.

Il webhook risponde Retry later: il modulo non è riuscito a confermare un'acquisizione con l'API di Razorpay, l'ordine non è stato creato (per esempio perché il modulo è disattivato), oppure il carrello era in aggiornamento da un'altra richiesta nello stesso momento. Razorpay invierà di nuovo l'evento automaticamente. Il motivo è nel Log.

L'URL del webhook mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste da Razorpay.

Un ordine è Razorpay payment on hold: leggi le note nel blocco Razorpay. Importo o valuta non corrispondevano al carrello, il pagamento è arrivato per un ordine annullato, oppure non è stato possibile verificarlo tramite l'API di Razorpay in quel momento e attende il webhook.

Il cliente vede un errore durante il pagamento: controlla il campo Log nella pagina del modulo. Gli errori vengono registrati anche con Enable Logging disattivato. Chiavi errate mostrano il messaggio che il metodo di pagamento non è disponibile in questo momento. Gli altri motivi di Razorpay vengono mostrati dopo Razorpay could not accept this payment:.

La finestra popup non si apre: lo script di Razorpay Checkout è stato bloccato da un blocco dei contenuti o dalla connessione. Il cliente vede un messaggio e può ricaricare la pagina.

Acquisizione o rimborso non riuscito con un messaggio sulla modalità: il pagamento è stato effettuato in modalità Test o Live, e le chiavi di quella modalità non sono impostate. Inseriscile e riprova.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Razorpay Payment 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 modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. Le transazioni e i rimborsi Razorpay e gli stati dell'ordine Razorpay payment authorized e Razorpay payment on hold restano sempre, quindi gli ordini pagati in precedenza possono essere ancora acquisiti e rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID delle transazioni.

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