VibeFox PayU India 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.

Valuta: rupia indiana (INR). PayU India addebita solo in rupie. Per i carrelli in altre valute il metodo di pagamento è nascosto al checkout.

Numero di telefono: PayU richiede un numero di telefono per ogni pagamento. Rendi obbligatorio, o almeno visibile, il campo telefono dell'indirizzo nel tuo checkout.

Account PayU India: ti servono la Merchant Key e il Merchant Salt (v1) da PayU Dashboard > Payment Gateway > Key Salt Details. Imposta la dashboard in Test Mode per vedere la coppia di test. Usa Salt v1, non Salt v2.

Accesso a Internet per il tuo negozio: necessario per il webhook facoltativo. Senza di esso, gli ordini vengono confermati quando il cliente torna da PayU.

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 cerca più tardi VibeFox PayU India Payment Gateway nell'elenco dei moduli e fai clic su Configure.

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

4. Inserisci il Test Merchant Key e Salt e il Live Merchant Key e Salt (vedi Configurazione).

5. Consigliato: in PayU Dashboard > Webhooks aggiungi l'URL del webhook mostrato nella pagina Configure per i pagamenti riusciti e non riusciti.

6. Scegli il Mode, attiva Enable/Disable e fai clic su Save. Prova un pagamento in modalità test, poi passa a Live.

All'installazione il modulo crea due stati dell'ordine: Awaiting PayU India payment e PayU India 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; la valuta INR deve restare consentita per il modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa se manca 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 mostra un errore se la valuta predefinita del negozio non è INR (il gateway viene allora nascosto al checkout).

Al salvataggio, spazi e interruzioni di riga vengono rimossi da chiavi e salt, perché un salt con uno spazio incollato farebbe fallire ogni risposta di PayU alla verifica.

PayU India

Enable/Disable: Enable PayU India Payment Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato. Se lo attivi senza chiave e salt della modalità corrente, la pagina ti avvisa dopo il salvataggio.

Title: il titolo del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: PayU India. Obbligatorio.

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

Credenziali API

Copia la Merchant Key e il Merchant Salt (v1) da PayU Dashboard > Payment Gateway > Key Salt Details. Imposta la dashboard in Test Mode per la coppia di test. La sezione contiene un link Open the PayU Dashboard.

Mode: l'ambiente PayU che usano i nuovi pagamenti.

I pagamenti già avviati mantengono la modalità in cui sono stati avviati: i loro risultati vengono verificati e i loro rimborsi inviati con chiave e salt di quella modalità, anche dopo il cambio di modalità.

Live Merchant Key: la tua Merchant Key PayU live.

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

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

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

I salt 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 cambiarlo.

Clear saved salts: seleziona un salt e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

URL di ritorno e webhook

Return URL: ha questo aspetto: https://your-shop/module/wcp_payu_india_payment/return, eventualmente con un codice lingua come /en/. Viene inviato automaticamente a PayU con ogni pagamento; non c'è nulla da configurare.

Webhook URL: ha questo aspetto: https://your-shop/module/wcp_payu_india_payment/webhook, eventualmente con un codice lingua. Facoltativo ma consigliato: conferma i pagamenti anche se il cliente chiude il browser prima di tornare. Aggiungilo in PayU Dashboard > Webhooks per i pagamenti riusciti e non riusciti. Copia l'URL esattamente come lo mostra la pagina Configure. Deve essere raggiungibile da Internet (senza basic auth né blocchi del firewall). La modalità manutenzione del negozio e le sue restrizioni per paese non lo bloccano.

Il webhook contiene lo stesso risultato firmato del ritorno del cliente. I webhook senza un hash PayU valido vengono rifiutati.

Avanzate

Verify Payment: ricontrolla ogni pagamento riuscito con l'API verify_payment di PayU. Consigliato. Se il controllo non può essere completato, l'ordine viene messo in attesa invece di essere contrassegnato come pagato. Predefinito: attivo.

Enable Logging: registra gli eventi del gateway per la risoluzione dei problemi in logs/payu_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 gli altri eventi, come ogni modulo di pagamento e ogni risultato PayU. Chiavi, salt e dati personali 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: elimina le impostazioni e i registri del modulo quando questo viene disinstallato. Gli ordini e i record delle transazioni PayU non vengono mai eliminati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita PayU India) e conferma. Se né l'indirizzo di fatturazione né quello di spedizione hanno un numero di telefono fisso o di cellulare, il cliente resta al checkout con PayU India requires a phone number. Please enter your phone number and try again. Altrimenti vede 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 per il totale del carrello alla pagina di checkout ospitata di PayU. Se il browser non prosegue da solo, la pagina contiene un pulsante Pay with PayU e il pulsante Back to checkout. Sulla pagina di PayU il cliente paga con carta, NetBanking, UPI o wallet. A questo punto non esiste ancora alcun ordine.

Ogni tentativo di pagamento riceve un proprio ID transazione PayU, che inizia con il numero del carrello, ed è salvato con importo e modalità. Un pagamento effettuato su una vecchia pagina di pagamento ancora aperta dello stesso carrello viene comunque accettato. Un carrello che ha già un ordine non riceve mai un nuovo modulo di pagamento, quindi il pulsante Indietro del browser non può avviare un secondo pagamento.

PayU restituisce il risultato insieme al cliente e, se configurato, tramite webhook. Un risultato viene accettato solo con un hash PayU valido generato con chiave e salt della modalità in cui è stato avviato il pagamento, e solo per un ID transazione emesso per quel carrello. Con Verify Payment attivo, un risultato riuscito viene inoltre verificato con l'API verify_payment di PayU. L'importo pagato deve corrispondere all'importo del tentativo e al totale del carrello al paisa, in INR. L'ordine viene contrassegnato come pagato solo dopo che PayU lo conferma in questo modo. Il modulo gestisce questi risultati PayU:

Dopo un pagamento riuscito o in sospeso il cliente vede la pagina standard di conferma dell'ordine. Un pagamento in sospeso aggiunge Your PayU payment is pending. The order will be updated as soon as PayU confirms the result — there is no need to pay again.; un ordine in attesa aggiunge Your payment is being reviewed. We will contact you if anything else is needed.; e un ordine in Payment error o Canceled mostra Your PayU payment was not completed. Please contact us about this order.

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. oppure, quando non è stato possibile verificare il risultato, We could not confirm the payment result. If your account was charged, please contact us before paying again. Se il risultato è ancora in elaborazione quando il cliente torna, compare una pagina con We are confirming your PayU payment. If you completed the payment, your order will be created shortly — please do not pay again. e un pulsante Check again.

Il modulo addebita esclusivamente in INR e non dispone di elaborazione multivaluta (MCP). Non supporta carte salvate o tokenizzazione, né abbonamenti, né modulo carta on-site (seamless), né gestione di EMI o offerte, né checkout rapido PayU in un clic.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato indirizzato a PayU e non ha pagato, oppure il pagamento non è riuscito o è stato annullato. Esiste solo il carrello.

Payment accepted: il pagamento è stato confermato. Il pagamento viene registrato con l'ID transazione PayU (mihpayid) come ID transazione, e una nota mostra PayU payment successful. Transaction ID: …, Mode: …, Bank: …

Awaiting PayU India payment: un pagamento UPI o NetBanking è ancora in sospeso presso PayU. L'ordine passa a Payment accepted quando PayU lo conferma.

PayU India payment on hold: l'importo o la valuta pagati differiscono dal carrello, l'API verify_payment non è stata raggiunta o non ha ancora confermato il pagamento, oppure è arrivato un pagamento per un ordine che era stato annullato. La nota indica il motivo. Controlla la transazione in PayU Dashboard, poi imposta l'ordine su Payment accepted oppure annullalo e rimborsa il pagamento. Quando è fallita solo la verifica, l'ordine viene pagato automaticamente alla successiva consegna del risultato.

Payment error: un pagamento in sospeso è stato successivamente rifiutato o annullato. Un successivo risultato riuscito paga comunque l'ordine.

Refunded: tutto ciò che era stato pagato è stato rimborsato tramite il modulo.

Se PayU segnala un altro pagamento riuscito per un ordine già pagato, l'ordine non viene modificato e una nota ti chiede di rimborsare il duplicato in PayU Dashboard. Un pagamento PayU per un carrello ordinato con un altro metodo di pagamento riceve una nota e non paga quell'ordine.

Blocco pagamento PayU India

La pagina dell'ordine mostra un blocco PayU India payment con l'ID transazione PayU (mihpayid), l'ID transazione del negozio (txnid), l'ambiente, lo stato PayU, la modalità e la banca del pagamento, l'importo pagato e l'importo dei rimborsi richiesti, un badge Test mode per i pagamenti di test, lo storico dei rimborsi e le note del modulo. Per un ordine in attesa mostra un promemoria per verificare il pagamento.

Rimborsi

Nel blocco PayU India payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via PayU. Conferma la domanda Refund this amount through PayU? This cannot be undone. Sono supportati rimborsi completi e parziali; l'importo deve essere maggiore di zero e non superiore a quanto resta di ciò che PayU ha addebitato. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine dei Moduli. Il rimborso viene inviato tramite l'API rimborsi di PayU con chiave e salt della modalità in cui è stato effettuato il pagamento, quindi quelle credenziali devono essere impostate. Se PayU rifiuta il rimborso, il blocco mostra PayU refund failed: con il messaggio di PayU e non viene registrato alcun rimborso.

PayU accoda i rimborsi e li completa in modo asincrono; il cliente di solito riceve il denaro entro 5–7 giorni lavorativi. Lo storico dei rimborsi e le note mostrano importo, ID richiesta PayU e motivo. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale non cambia lo stato. I rimborsi sono disponibili quando PayU ha comunicato l'ID transazione del pagamento. Il modulo non verifica in seguito lo stato del rimborso e non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite PayU.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox PayU India Payment Gateway è il primo blocco della pagina Modules > Module Manager > VibeFox PayU India Payment Gateway > 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 a cui 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-payu-india 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 solo dominio: il dominio 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, PayU India non viene mostrato ai clienti al checkout. Se un pagamento viene comunque avviato, il cliente vede This payment method is not available. Please choose another one. Lo storefront 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 i rimborsi funzionano.

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

PayU India non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che chiave e salt del Mode selezionato siano compilati. Verifica che la valuta del carrello sia INR e che il modulo sia consentito per quella valuta, per il paese del cliente e per il suo gruppo in Payment > Preferences. La pagina Configure mostra un avviso per le credenziali mancanti e per una valuta del negozio diversa da INR.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: il cliente non è tornato al negozio e non è arrivato alcun webhook. Aggiungi l'URL del webhook dalla pagina Configure in PayU Dashboard > Webhooks per i pagamenti riusciti e non riusciti, e assicurati che sia raggiungibile da Internet.

Il webhook risponde invalid_signature: l'hash PayU non corrisponde. Verifica che chiave e salt della modalità del pagamento siano corretti e che si usi Salt v1, non Salt v2. Viene rifiutato anche un risultato di un pagamento live firmato con il salt di test, o viceversa. Non viene modificato nulla.

Il webhook risponde not_configured: mancano chiave o salt della modalità in cui è stato avviato il pagamento. Inseriscili; PayU ripete il webhook.

Il webhook risponde verify_unavailable: l'API verify_payment non ha ancora potuto confermare il pagamento. L'ordine è in attesa e la successiva consegna esegue di nuovo la verifica.

Il webhook risponde busy o retry: il ritorno del cliente per lo stesso carrello era in elaborazione nello stesso momento, oppure non è stato possibile creare l'ordine (ad esempio perché il modulo è disattivato). PayU ripete il webhook. Il motivo viene scritto nel registro.

Il webhook risponde ignored_unknown_txnid: la transazione non è stata avviata da questo negozio, ad esempio da un altro negozio che usa lo stesso account PayU. Non viene modificato nulla.

Il cliente vede PayU India requires a phone number: rendi obbligatorio o visibile il campo telefono dell'indirizzo al checkout. Viene usato prima l'indirizzo di fatturazione, poi quello di spedizione.

L'ordine è PayU India payment on hold: leggi le note nel blocco PayU India payment. Il motivo è una differenza di importo o di valuta, una verifica fallita o in sospeso, oppure un pagamento per un ordine annullato.

Il rimborso non riesce: PayU transaction ID not found for this order. significa che l'ordine non ha ancora un pagamento PayU. This payment was made in Test mode, but the Merchant Key/Salt of that mode are not set. (o Live mode) significa che devi prima inserire le credenziali di quella modalità. Invalid refund amount: at most … INR can be refunded. significa che l'importo è superiore al residuo del pagamento.

Troppo poco nel registro: errori e avvisi vengono sempre scritti; attiva Enable Logging per vedere anche ogni modulo di pagamento e ogni risultato PayU.

Hook per sviluppatori: actionPayuPRequestFields modifica i campi della richiesta di pagamento prima che vengano firmati. Chiave, ID transazione, importo e URL di ritorno non possono essere modificati tramite esso.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox PayU India Payment Gateway 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 successiva reinstallazione. I record delle transazioni PayU e le richieste di rimborso e gli stati dell'ordine Awaiting PayU India payment e PayU India payment on hold vengono sempre conservati, così gli ordini pagati prima possono essere ancora rimborsati dopo una reinstallazione. Gli ordini esistenti mantengono le loro note di pagamento e gli ID transazione PayU.

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