VibeFox PayU for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva 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.

Valuta del negozio: una tra PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH. La valuta deve essere abilitata anche per il tuo punto vendita in PayU. Per le altre valute, il metodo di pagamento è nascosto al checkout.

Accesso Internet al tuo sito: PayU invia notifiche di pagamento al tuo negozio, pertanto il sito deve essere raggiungibile da Internet (non protetto da autenticazione HTTP o pagina di manutenzione). Senza notifiche, gli ordini vengono comunque verificati quando il cliente torna da PayU.

Account PayU: sono necessarie quattro chiavi del tuo punto vendita (POS): POS ID, Second key (MD5), client_id OAuth e client_secret OAuth. Si trovano nel pannello commerciante di PayU in Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Le chiavi sandbox provengono da un account sandbox PayU separato.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un 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_payment in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

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

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

5. Inserisci le quattro chiavi Sandbox e le quattro chiavi Live (vedi Configurazione). In PayU non occorre configurare alcun URL di notifica.

6. Attiva Enable/Disable. Lascia Test Mode attivo finché non hai effettuato un pagamento di prova, poi deselezionalo per accettare pagamenti reali con le chiavi Live.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > PayU. Sopra i campi la pagina ti avvisa quando la modalità sandbox è attiva, quando manca una delle quattro chiavi della modalità corrente e quando PayU non accetta la valuta del negozio. Negli ultimi due casi PayU non viene mostrato al checkout.

Al salvataggio, spazi e interruzioni di riga vengono rimossi da tutte le chiavi, poiché copiarle dal pannello di PayU ne aggiunge spesso di indesiderati.

Generali

Enable/Disable: Enable PayU payment gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il titolo del metodo di pagamento mostrato al cliente. Predefinito: PayU.

Description: la descrizione del metodo di pagamento mostrata al cliente. Predefinito: Pay securely via PayU.

Credenziali API

Trova le chiavi nel pannello commerciante di PayU: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Le chiavi sandbox provengono da un account sandbox PayU separato. Tutte e quattro le chiavi di una modalità devono essere compilate.

Test Mode: Enable sandbox (test) mode. Utilizza la sandbox di PayU e le chiavi Sandbox sottostanti. Non viene addebitato denaro reale. Nel checkout classico e nel blocco Checkout il cliente vede Sandbox mode — no real money is charged. Disattivalo per accettare pagamenti reali con le chiavi Live. Predefinito: attivato.

Live POS ID: il POS ID (merchantPosId) del tuo punto vendita di produzione.

Live Second Key (MD5): utilizzata per verificare la firma delle notifiche di PayU.

Live OAuth Client ID: il client_id OAuth del punto vendita.

Live OAuth Client Secret: il client_secret OAuth del punto vendita.

Sandbox POS ID: il POS ID del tuo punto vendita sandbox di PayU.

Sandbox Second Key (MD5): utilizzata per verificare la firma delle notifiche sandbox di PayU.

Sandbox OAuth Client ID: il client_id OAuth del punto vendita sandbox.

Sandbox OAuth Client Secret: il client_secret OAuth del punto vendita sandbox.

Ogni pagamento memorizza il proprio ambiente. Notifiche, verifiche di stato e rimborsi di un pagamento utilizzano sempre le chiavi di quell'ambiente, pertanto i pagamenti precedenti continuano a funzionare dopo un cambio. Una notifica firmata con la chiave sandbox non viene mai accettata per un pagamento live.

Notifiche di pagamento

Questa sezione mostra l'URL di notifica, simile a https://your-site/wc-api/wc_pu_payment/. Il plugin lo invia a PayU con ogni pagamento, quindi non occorre configurare nulla nel pannello PayU. Assicurati che sia raggiungibile da Internet (non bloccato da firewall, modalità manutenzione o autenticazione HTTP).

Avanzate

Receive payments automatically: Automatically receive payments waiting for confirmation. Rilevante solo se la ricezione automatica è disattivata per il tuo POS nel pannello PayU: i pagamenti rimangono in attesa di conferma (WAITING_FOR_CONFIRMATION). Quando questa opzione è attiva, il plugin riceve tali pagamenti immediatamente. Quando è disattivata, tali ordini vengono messi in sospeso e tu ricevi o annulli il pagamento con le azioni dell'ordine Receive PayU payment e Cancel PayU payment. Predefinito: attivato.

Logging: Enable logging registra gli eventi tecnici (numeri d'ordine, ID ordine PayU, stati, errori, senza chiavi o dati personali) in WooCommerce > Status > Logs, origine wcp_payu_payment. Predefinito: disattivato.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Gli ordini e i rispettivi dati di pagamento non vengono mai eliminati. La disattivazione del plugin conserva tutto. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita PayU) ed effettua l'ordine. Il plugin crea un ordine PayU per l'importo totale dell'ordine nella valuta dell'ordine, con la descrizione Order #, il numero dell'ordine e il nome del tuo negozio, nonché gli articoli ordinati, la spedizione e le commissioni da mostrare nella pagina PayU. La lingua della pagina PayU segue quella del negozio quando PayU la supporta, altrimenti inglese. Il cliente viene indirizzato alla pagina di pagamento di PayU, sceglie un metodo ed esegue il pagamento.

Ogni tentativo di pagamento riceve un proprio ordine PayU. Quando il cliente prova a pagare nuovamente (dopo un pagamento non riuscito o annullato, o dalla pagina Pay for order), il precedente pagamento PayU non completato dell'ordine viene annullato in PayU, evitando che un vecchio link di pagamento venga pagato due volte.

Il semplice ritorno al tuo negozio non segna mai un ordine come pagato. L'ordine viene contrassegnato come pagato solo dopo la conferma di PayU: tramite una notifica firmata con la Second Key dell'ambiente di pagamento, o tramite una verifica dello stato dell'ordine PayU sul server al rientro del cliente (utile se una notifica subisce ritardi). L'ordine PayU deve essere quello creato per questo ordine e l'importo e la valuta devono corrispondere. Il plugin gestisce questi stati di PayU:

Nella pagina di ordine ricevuto, finché l'ordine è ancora in In attesa di pagamento, il cliente vede We have not received the payment confirmation from PayU yet. If the payment was interrupted, you can try again: o, dopo un pagamento non riuscito, The payment was not completed. You can try again:, ciascuno con un pulsante Pay again. Per un ordine in attesa il messaggio è Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

Se PayU non riesce ad avviare il pagamento, il cliente vede Payment error. Please try again or choose another payment method. Il motivo tecnico (codice HTTP e stato PayU) viene registrato nel registro e in una nota dell'ordine PayU payment could not be started:. Se mancano le chiavi della modalità corrente, il messaggio è Payment gateway is not configured properly. Please contact the administrator.

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

Il cliente sceglie il metodo di pagamento sulla pagina PayU, non nel tuo checkout. Il plugin non ha moduli di carta nel tuo negozio, niente carte salvate o pagamenti con un clic, niente abbonamenti e nessun widget per rate o credito PayU. Utilizza un punto vendita per ambiente (nessun punto vendita per valuta).

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato indirizzato a PayU e non ha ancora pagato. La nota dell'ordine mostra l'ID ordine PayU e l'ambiente (sandbox o live).

Processing: il pagamento è stato confermato. La nota dell'ordine mostra l'ID ordine PayU, l'importo e l'ambiente. L'ID transazione è l'ID ordine PayU che è stato pagato. Gli ordini con soli prodotti virtuali scaricabili diventano Completato, come fa WooCommerce per impostazione predefinita.

On hold: l'importo o la valuta pagati non corrispondevano all'ordine, un pagamento è stato completato per un ordine che era stato annullato, oppure un pagamento attende la tua conferma (ricezione automatica disattivata o ricezione non riuscita). La nota dell'ordine indica la motivazione e cosa fare.

Failed: l'ultimo pagamento PayU è stato annullato o rifiutato. Il cliente può riprovare a pagare.

Ogni notifica viene elaborata una sola volta, sotto un blocco per ordine: notifiche ripetute non aggiungono note, non riducono la giacenza né inviano e-mail due volte. Se viene completato un altro pagamento per un ordine già pagato o rimborsato, una nota ti invita a rimborsarlo nel pannello PayU. Un pagamento in attesa di conferma su un ordine già pagato o chiuso viene annullato automaticamente, evitando che il denaro venga prelevato due volte.

Pagamenti in attesa di conferma

Per un ordine non pagato con un pagamento in attesa di conferma, la schermata dell'ordine offre due azioni dell'ordine: Receive PayU payment (waiting for confirmation) e Cancel PayU payment (release the funds). Scegline una e fai clic sul pulsante di aggiornamento. L'azione viene aggiunta alle note dell'ordine con il tuo nome utente e il nuovo stato di PayU viene applicato immediatamente.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via PayU (il pulsante mostra il tuo Title). Sono supportati rimborsi completi e parziali. Il rimborso viene inviato per l'ordine PayU effettivamente pagato, con le chiavi dell'ambiente del pagamento, pertanto tali chiavi devono essere configurate. La motivazione del rimborso viene inviata come descrizione del rimborso. Se PayU rifiuta il rimborso, WooCommerce mostra l'errore di PayU e non viene registrato alcun rimborso.

I rimborsi sono asincroni in PayU. Il plugin aggiunge subito una nota con l'ID rimborso PayU e lo stato; lo stato finale arriva in seguito come notifica di PayU e viene aggiunto come nota. Se PayU annulla un rimborso, la nota segnala che il denaro non è stato restituito al cliente.

Gli ordini messi in attesa per mancata corrispondenza di importo o valuta mantengono l'ID ordine PayU come ID transazione, consentendo di rimborsare il pagamento sia da WooCommerce sia nel pannello PayU.

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. 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 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, PayU 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 autenticati continuano a vedere il metodo di pagamento contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non subiscono conseguenze: i pagamenti già avviati continuano a essere confermati e i rimborsi funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma gli aggiornamenti e l'assistenza richiedono un rinnovo. Lo stato viene verificato nuovamente in modo automatico in background.

Risoluzione dei problemi

PayU non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che tutte e quattro le chiavi della modalità corrente siano compilate: le chiavi Sandbox in modalità sandbox, le chiavi Live in modalità live. Controlla che la valuta del negozio (o la valuta dell'ordine nella pagina Pay for order) sia tra quelle supportate. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi.

Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: PayU non ha ancora consegnato la notifica e il controllo di stato nella pagina di ritorno non ha rilevato un pagamento completato. Verifica che l'URL di notifica mostrato nelle impostazioni sia raggiungibile da Internet. Attiva Logging per vedere cosa arriva.

La notifica risponde Invalid signature: la notifica non è stata firmata con la Second Key di nessuno dei due ambienti. Controlla Live Second Key (MD5) e Sandbox Second Key (MD5). La risposta Invalid signature for this payment indica che la notifica è stata firmata con la chiave dell'altro ambiente rispetto a quello del pagamento.

La notifica risponde Ignored: l'ordine PayU non appartiene a nessun ordine di questo negozio pagato con PayU, ad esempio appartiene a un altro negozio sullo stesso POS. PayU interrompe i tentativi.

Il pagamento non viene creato: attiva Logging e controlla in WooCommerce > Status > Logs, origine wcp_payu_payment. Il registro mostra il codice HTTP e lo stato PayU. Could not authenticate with PayU (check the OAuth client ID / secret). indica chiavi OAuth errate per la modalità corrente.

L'ordine è In sospeso: leggi la nota dell'ordine. Il motivo è una discrepanza di importo o valuta, un pagamento successivo all'annullamento oppure un pagamento in attesa di conferma. In quest'ultimo caso, usa le azioni dell'ordine Receive PayU payment o Cancel PayU payment.

Il rimborso non riesce: This order has no completed PayU payment. Cannot process refund. significa che l'ordine non ha un ordine PayU pagato. Un messaggio che segnala la mancanza delle chiavi Sandbox o Live indica che il pagamento è stato eseguito in quell'ambiente e le relative chiavi non sono configurate. Inseriscile e riprova.

Altre valute: gli sviluppatori possono modificare l'elenco delle valute con il filtro wc_pu_supported_currencies e l'icona del checkout con il filtro wc_pu_icon.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Ad 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 sul nuovo dominio. Se il server di licenza non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin mantiene tutte le impostazioni; vengono eliminati solo i token di accesso PayU memorizzati nella cache. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi insieme ai token nella cache. Le impostazioni del gateway e il registro di questo plugin vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti mantengono le note di pagamento, gli ID ordine PayU e gli ID transazione.

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