IT
EUR
Indietro

VibeFox Razorpay for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

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

PHP: 8.0 o successivo.

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 segreto 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: si acquista 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. In alternativa puoi caricare la cartella wcp_razorpay_payment in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

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

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

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

6. Attiva Enable/Disable ed effettua un pagamento di prova con Test mode attivo. Quando sei pronto, inserisci le chiavi Live e deseleziona Test mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Razorpay. Sopra i campi la pagina mostra degli avvisi: mancano le chiavi della modalità attuale (in tal caso il metodo di pagamento viene nascosto 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 segreto del webhook è vuoto, oppure la valuta del negozio non è INR e richiede che International Payments sia attivo sul tuo account Razorpay. Nell'elenco dei metodi di pagamento, Razorpay è contrassegnato come da configurare finché la modalità attuale non ha le sue chiavi, e mentre la modalità test è attiva compare il badge Test mode. Gli spazi incollati insieme alle chiavi vengono rimossi al salvataggio.

Generali

Enable/Disable: Enable Razorpay Payment Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: UPI, Cards, NetBanking.

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: Use the Test mode keys (no real money is charged). Predefinito: attivo. Deselezionalo 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.

Pagamento

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

Authorize & Capture: il cliente viene addebitato subito. Se Razorpay segnala un pagamento autorizzato, il plugin lo acquisisce.
Authorize Only: il denaro viene riservato. L'ordine viene messo in «In sospeso» e acquisisci il pagamento più tardi con l'azione d'ordine Capture Razorpay payment oppure nel Razorpay Dashboard. Razorpay effettua automaticamente il rimborso dei pagamenti autorizzati che non vengono acquisiti in tempo.

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 questa sezione delle impostazioni. Ha questo aspetto: https://your-site/wc-api/razorpay_p_webhook/. Copialo esattamente come lo mostrano le impostazioni. Inserisci in Razorpay un segreto a tua scelta e seleziona questi eventi:

payment.authorized: un pagamento è stato autorizzato.
payment.captured: un pagamento è stato acquisito, anche quando lo acquisisci nel Razorpay Dashboard.
payment.failed: un tentativo di pagamento non è riuscito.
order.paid: l'ordine Razorpay del pagamento è stato pagato.
refund.created: un pagamento è stato rimborsato, per esempio nel Razorpay Dashboard.

Webhook Secret: il segreto che hai inserito quando hai creato il webhook. Usa lo stesso segreto per il webhook di test e per quello live, perché il plugin ha un solo 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 o riapre in seguito la pagina di pagamento dell'ordine.

Avanzate

Enable Logging: Save debug logs. Il registro si trova in WooCommerce > Status > Logs, origine wcp_razorpay_payment. 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.

Delete Data on Uninstall: Remove the plugin settings and logs when the plugin is deleted (orders are never touched). Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita UPI, Cards, NetBanking) e fa l'ordine. Il plugin crea un ordine Razorpay per l'importo totale esatto e la valuta dell'ordine e apre la pagina di pagamento dell'ordine. La finestra popup di Razorpay Checkout si apre automaticamente lì, con nome, email e telefono del cliente già compilati. Se la finestra viene chiusa, il cliente può fare clic su Pay Now per riaprirla oppure su Cancel order. In modalità test la pagina mostra Razorpay Test mode: no real money will be charged.

Dopo un pagamento riuscito il plugin verifica la firma di Razorpay, recupera il pagamento tramite l'API di Razorpay e confronta importo e valuta con quelli dell'ordine. L'ordine viene segnato come pagato solo dopo la conferma di Razorpay. Il cliente vede quindi la pagina di ricezione dell'ordine. Se la firma è valida ma il pagamento non può essere recuperato in quel momento, l'ordine viene messo in «In sospeso» e il webhook lo confermerà più tardi.

Se il cliente torna su un ordine non pagato, il plugin riutilizza il suo ordine Razorpay. Se quell'ordine Razorpay era già pagato, per esempio perché il cliente ha chiuso il browser e non c'è un webhook, il plugin applica il pagamento invece di chiederne un secondo.

Messaggi visibili al cliente:

Payment was cancelled. Please click "Pay Now" to try again.
Your session has expired. Please click "Pay Now" to try again.
We could not verify your payment. Il messaggio aggiunge che l'ordine verrà aggiornato automaticamente non appena Razorpay confermerà l'addebito, se il denaro è stato addebitato.
Razorpay is temporarily unavailable. Please try again in a few minutes.
Razorpay could not accept this payment: seguito dal motivo indicato da Razorpay.
The order amount is too small to be paid with Razorpay.
Razorpay Checkout could not be loaded. Lo script della finestra è bloccato; il messaggio chiede di verificare la connessione, disattivare i blocchi dei contenuti e ricaricare la pagina.

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 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

Order statuses

Pending payment: l'ordine Razorpay è stato creato e il cliente non ha ancora pagato. Ogni ordine Razorpay viene aggiunto alle note dell'ordine con importo e modalità.

Processing or Completed: il pagamento è stato acquisito e confermato, lo stato predefinito di WooCommerce dopo il pagamento. La nota dell'ordine riporta l'ID del pagamento Razorpay, l'importo e il modo in cui è stato confermato (callback, webhook o verifica al ritorno). L'ID della transazione è l'ID del pagamento Razorpay (pay_...).

On hold: impostato in questi casi, ognuno con una nota dell'ordine: il pagamento è stato solo autorizzato (Authorize Only), l'importo o la valuta pagati non corrispondono all'ordine, il pagamento è stato acquisito per un ordine annullato, oppure il pagamento non è stato verificabile tramite l'API di Razorpay in quel momento. Un ordine già in «In sospeso» riceve comunque la nota.

Failed: il webhook payment.failed è arrivato per un ordine in attesa. La nota mostra l'errore di Razorpay. Il cliente può ancora pagare di nuovo; un ordine che ha già un pagamento autorizzato o acquisito non viene modificato.

Cancelled: il cliente ha fatto clic su Cancel order, oppure l'ordine è stato annullato da te o dal timeout di riserva delle scorte di WooCommerce. Un pagamento che arriva più tardi non lo riapre automaticamente: un pagamento autorizzato non viene acquisito, e un pagamento acquisito mette l'ordine in «In sospeso» per la tua verifica.

Se arriva un pagamento aggiuntivo per un ordine già pagato, l'ordine non cambia. Una nota ti chiede di rimborsarlo nel Razorpay Dashboard se non era previsto.

Acquisizione (Authorize Only)

Apri l'ordine in «In sospeso», scegli Capture Razorpay payment in Order actions e fai clic sul pulsante di aggiornamento. Il pagamento viene acquisito nella modalità in cui è stato autorizzato, e l'ordine diventa pagato. Se Razorpay rifiuta, la nota dell'ordine mostra Razorpay capture failed: con il motivo. Un'acquisizione effettuata nel Razorpay Dashboard completa l'ordine tramite il webhook.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via seguito dal titolo del metodo di pagamento. Sono supportati rimborsi totali e parziali. Il rimborso viene inviato con le chiavi della modalità in cui è stato effettuato il pagamento. Se Razorpay non accetta il rimborso, WooCommerce mostra Razorpay refund failed: con il motivo, e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID del rimborso Razorpay, l'importo e lo stato.

I rimborsi effettuati nel Razorpay Dashboard arrivano tramite il webhook e vengono registrati sull'ordine come rimborsi di WooCommerce, una sola volta e senza reintegrare gli articoli in magazzino. Un rimborso del Dashboard in un'altra valuta o superiore all'importo rimborsabile non viene registrato automaticamente; una nota ti chiede di registrarlo manualmente.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > Razorpay. 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 controllare 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 lo slot del dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Razorpay 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 che hanno effettuato l'accesso continuano a vedere il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins 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 assistenza richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Razorpay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità attuale 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.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: 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 nelle impostazioni e che siano selezionati i cinque eventi. Verifica che Webhook Secret sia lo stesso segreto presente in Razorpay. L'ordine viene confermato anche quando il cliente riapre la pagina di pagamento dell'ordine.

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

Il webhook risponde Invalid signature o Missing signature: il segreto nelle impostazioni è diverso da quello del webhook di Razorpay. Inserisci lo stesso segreto in entrambi i punti.

Il webhook risponde Retry later: il plugin non è riuscito a confermare un'acquisizione tramite l'API di Razorpay, oppure l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. Razorpay invierà di nuovo l'evento automaticamente.

Un ordine è On hold: leggi la nota dell'ordine. Il pagamento è stato solo autorizzato (usa Capture Razorpay payment), l'importo o la valuta non corrispondevano all'ordine, il pagamento è arrivato per un ordine annullato, oppure non è stato verificabile tramite l'API di Razorpay in quel momento e attende il webhook.

Il cliente vede un errore durante il pagamento: apri le note dell'ordine oppure controlla WooCommerce > Status > Logs, origine wcp_razorpay_payment. Gli errori vengono registrati anche con Enable Logging disattivato. Chiavi errate mostrano il messaggio che il metodo di pagamento non è disponibile al 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.

Il rimborso non riesce: il rimborso usa le chiavi della modalità in cui è stato effettuato il pagamento. Verifica che le chiavi di quella modalità siano impostate e leggi il motivo nel messaggio di errore.

Il blocco della licenza mostra un errore: 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 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. Le impostazioni del gateway e i registri (file di log, compresi quelli ruotati, e voci di log nel database) vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini e i loro dati Razorpay non vengono mai eliminati. Gli ordini esistenti conservano le note di pagamento e gli ID di transazione.

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