VibeFox PayU India for WooCommerce — Guida

Requisitos

WordPress: 5.8 o successivo.

WooCommerce: 6.0 o successivo, installato e attivo. Il plugin rifiuta di attivarsi senza di esso; se WooCommerce viene disattivato in seguito, il plugin non esegue alcuna operazione e mostra un avviso nell'area di amministrazione.

PHP: 8.0 o successivo.

Store currency: rupia indiana (INR). PayU India addebita esclusivamente in rupie. Per le altre valute, il metodo di pagamento viene nascosto al checkout.

Phone number: PayU richiede un numero di telefono per ogni pagamento. Rendi il campo del telefono obbligatorio, o quantomeno visibile, nel tuo checkout.

PayU India account: sono necessari Merchant Key e Merchant Salt (v1) da PayU Dashboard > Payment Gateway > Key Salt Details. Passa la dashboard in Test Mode per visualizzare la coppia di test. Usa Salt v1, non Salt v2.

Internet access to your site: necessario per il webhook opzionale. Senza di esso, gli ordini vengono confermati quando il cliente torna da PayU.

VibeFox license key: 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_payu_india_payment in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > PayU India > 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 Merchant Key e Salt di test, nonché Merchant Key e Salt di produzione (vedi Configurazione).

6. Consigliato: in PayU Dashboard > Webhooks, aggiungi l'URL del webhook mostrato nella pagina delle impostazioni per i pagamenti riusciti e falliti.

7. Scegli Mode e abilita Enable/Disable. Esegui un pagamento di prova in modalità Test, poi passa a Live.

Configurazione

Tutte le impostazioni si trovano in una pagina: WooCommerce > Settings > Payments > PayU India. Sopra i campi la pagina segnala se mancano la chiave o il salt della modalità corrente, mostra Test mode is active: payments go to test.payu.in and no real money is charged. in modalità Test e ti avvisa quando la valuta del negozio non è INR (in tal caso il gateway viene nascosto al checkout).

Al momento del salvataggio, spazi e interruzioni di riga vengono rimossi da chiavi e salt, poiché un salt con uno spazio incollato per errore farebbe fallire la verifica di ogni risposta di PayU.

Generali

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

Title: il nome del metodo di pagamento che il cliente vede durante il checkout. Predefinito: PayU India.

Description: la descrizione del metodo di pagamento che il cliente vede durante il checkout. Predefinito: Pay securely via Credit/Debit Card, NetBanking, UPI, or Wallets through PayU.

Credenziali API

Copia Merchant Key e Merchant Salt (v1) da PayU Dashboard > Payment Gateway > Key Salt Details. Passa la dashboard in Test Mode per ottenere la coppia di test.

Mode: quale ambiente PayU viene utilizzato per i nuovi pagamenti.

I rimborsi vengono sempre inviati alla modalità in cui è stato effettuato il pagamento.

Live Merchant Key: la tua Merchant Key PayU di produzione.

Live Merchant Salt (v1): il tuo Merchant Salt (v1) PayU di produzione. Firma le richieste e verifica le risposte di PayU. Mantienilo segreto.

Test Merchant Key: la tua Merchant Key PayU di test, utilizzata solo in modalità Test.

Test Merchant Salt (v1): il tuo Merchant Salt (v1) PayU di test, utilizzato solo in modalità Test.

Return and webhook URLs

Return URL: ha una struttura simile a https://your-site/wc-api/payu_p_callback/. Viene inviato automaticamente a PayU a ogni pagamento; non è necessaria alcuna configurazione.

Webhook URL: ha una struttura simile a https://your-site/wc-api/payu_p_webhook/. Opzionale ma consigliato: conferma i pagamenti anche se il cliente chiude il browser prima di tornare al negozio. Aggiungilo in PayU Dashboard > Webhooks per i pagamenti riusciti e falliti. Copia l'URL esattamente come mostrato nella pagina delle impostazioni.

Avanzate

Verify Payment: Double-check every successful payment with the PayU verify_payment API. Consigliato. Se il controllo non può essere completato, l'ordine viene messo in sospeso anziché essere contrassegnato come pagato. Predefinito: attivato.

Enable Logging: Log gateway events for troubleshooting. Registrato in WooCommerce > Status > Logs, origine wcp_payu_india_payment. Errori e avvisi vengono sempre registrati; questa opzione aggiunge gli altri eventi. Chiavi, salt e dati personali dei clienti non vengono mai registrati. Predefinito: disattivato.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted (orders are never deleted). Predefinito: disattivato.

Checkout

Il cliente seleziona il metodo di pagamento (per impostazione predefinita PayU India) e invia l'ordine. Se l'ordine non contiene un numero di telefono di fatturazione (o di spedizione), il cliente vede PayU India requires a phone number. Please enter your phone number and try again. In caso contrario, il cliente passa a una breve pagina Thank you for your order. You will be redirected to PayU to complete your payment., che invia una richiesta di pagamento firmata al checkout ospitato di PayU. Lì il cliente effettua il pagamento tramite carta, NetBanking, UPI o wallet.

Ogni pagina di pagamento riceve il proprio ID transazione PayU, salvato nell'ordine con relativo importo e modalità. Un pagamento eseguito su una pagina di pagamento aperta in precedenza per lo stesso ordine viene comunque accettato. Un ordine pagato, in sospeso o annullato non riceve mai un nuovo modulo di pagamento, evitando così che il pulsante Indietro del browser possa avviare un secondo pagamento.

PayU restituisce il risultato tramite il cliente e, se configurato, via webhook. Un risultato viene accettato solo in presenza di un hash PayU valido generato con la chiave e il salt della modalità in cui è stato avviato il pagamento, e solo per un ID transazione emesso per quell'ordine. Con Verify Payment attivato, un risultato positivo viene verificato anche tramite l'API verify_payment di PayU. L'importo pagato deve corrispondere al totale dell'ordine al centesimo di rupia (paisa), in INR. L'ordine viene contrassegnato come pagato solo dopo la conferma da parte di PayU in questo modo. Il plugin gestisce questi risultati di PayU:

Dopo un pagamento riuscito o in sospeso, il cliente visualizza la pagina Ordine ricevuto. Dopo un pagamento non riuscito, il cliente torna al checkout con un messaggio: Payment was not completed. Please try again or choose a different payment method., Payment was cancelled. You may try again. o, qualora non sia stato possibile verificare il risultato, We could not confirm the payment result. If your account was charged, please contact us before paying again. I messaggi funzionano sia nel checkout classico sia nel blocco Checkout.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con la funzionalità High-Performance Order Storage (HPOS) di WooCommerce.

Il plugin addebita esclusivamente in INR e non dispone di elaborazione multivaluta (MCP). Non supporta carte salvate o tokenizzazione, né WooCommerce Subscriptions, né moduli carta integrati sul sito (seamless), né gestione di rateizzazioni (EMI) o promozioni, né checkout in un clic PayU.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato reindirizzato a PayU e non ha ancora completato il pagamento.

Processing: il pagamento è stato confermato. La nota dell'ordine mostra l'ID transazione PayU (mihpayid), la modalità di pagamento e il codice banca. L'ID transazione dell'ordine corrisponde al mihpayid di PayU. Gli ordini contenenti esclusivamente prodotti virtuali scaricabili diventano Completato, come da comportamento predefinito di WooCommerce.

On hold: il pagamento è ancora in sospeso su PayU (UPI o NetBanking), l'importo pagato o la valuta differiscono dall'ordine, l'API verify_payment non è stata raggiungibile o non ha ancora confermato il pagamento, oppure è arrivato un pagamento per un ordine che era stato annullato. La nota dell'ordine specifica il motivo. Verifica la transazione nella PayU Dashboard e completala oppure rimborsala. In caso di verifica non riuscita, l'ordine viene confermato automaticamente alla successiva ricezione del risultato.

Failed: il pagamento è stato rifiutato o annullato. Il cliente può riprovare a pagare.

Se PayU notifica un altro pagamento andato a buon fine per un ordine già pagato, una nota richiede di rimborsare il duplicato nella PayU Dashboard.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via PayU India (il pulsante riporta il tuo Title). Sono supportati rimborsi totali e parziali; l'importo deve essere superiore a zero. Il rimborso viene inviato tramite l'API di rimborso PayU con la chiave e il salt della modalità in cui è stato eseguito il pagamento, pertanto tali credenziali devono essere impostate. Se PayU rifiuta il rimborso, WooCommerce mostra il messaggio di PayU e non viene registrato alcun rimborso.

PayU accoda i rimborsi e li gestisce in modo asincrono; di solito il cliente riceve il denaro entro 5–7 giorni lavorativi. La nota dell'ordine mostra l'importo, l'ID richiesta PayU e la causale. Il plugin non verifica lo stato del rimborso in seguito.

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 > PayU India. 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, PayU India 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 continuano a essere 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

PayU India does not appear at checkout: verifica che la licenza sia attiva, che Enable/Disable sia abilitato e che la chiave e il salt del Mode selezionato siano compilati. Verifica che la valuta del negozio (o la valuta dell'ordine nella pagina Pay for order) sia INR. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi.

The payment went through, but the order stays Pending payment: il cliente non è tornato al negozio e non è giunto alcun webhook. Aggiungi l'URL del webhook indicato nelle impostazioni in PayU Dashboard > Webhooks per i pagamenti riusciti e falliti, e assicurati che sia raggiungibile da Internet.

Webhook answers invalid_signature: l'hash di PayU non coincide. Verifica che chiave e salt della modalità di pagamento siano corretti e che sia utilizzato Salt v1, non Salt v2. L'ordine non viene modificato.

Webhook answers not_configured: mancano la chiave o il salt della modalità in cui è stato avviato il pagamento. Inseriscili; PayU riproverà a inviare il webhook.

Webhook answers verify_unavailable: l'API verify_payment non è ancora riuscita a confermare il pagamento. L'ordine è in sospeso e la consegna successiva ripeterà la verifica.

The customer sees PayU India requires a phone number: rendi il campo del telefono obbligatorio o visibile nel checkout. Viene utilizzato il telefono di fatturazione, oppure quello di spedizione quando è compilato soltanto quest'ultimo.

The order is On hold: consulta la nota dell'ordine. Il motivo è un pagamento UPI o NetBanking in sospeso, una mancata corrispondenza di importo o valuta, una verifica fallita o in sospeso, oppure un pagamento per un ordine annullato.

Refund fails: PayU transaction ID not found for this order. indica che l'ordine non presenta alcun pagamento PayU. Un messaggio che segnala che Merchant Key o Salt della modalità di pagamento non sono impostati indica che devi prima inserire le credenziali di tale modalità.

Too little in the log: errori e avvisi vengono sempre registrati; attiva Enable Logging per visualizzare anche ogni richiesta e risultato di PayU.

Developer hooks: il filtro payu_p_request_fields modifica i campi della richiesta di pagamento prima che vengano firmati; il filtro payu_p_icon modifica l'icona al checkout.

The license block shows an error: 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

La disattivazione del 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 di questo plugin (file di registro e righe del registro nel database di WooCommerce) vengono eliminati solo se Delete data on uninstall era attivo. In caso contrario, restano salvati per una successiva reinstallazione. Gli ordini esistenti mantengono le relative note di pagamento, gli ID transazione PayU e gli ID richiesta di rimborso.

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