VibeFox PayU LATAM 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.
Currency: l'ordine deve essere in ARS, BRL, CLP, COP, MXN, PEN o USD, le valute elaborate da PayU Latam in Argentina, Brasile, Cile, Colombia, Messico, Panama e Perù. Per altre valute il metodo di pagamento è nascosto al checkout.
PayU Latam account: servono tre valori del tuo commercio PayU: l'ID commerciante, l'ID account del paese in cui vendi e la chiave API. Si trovano nel modulo PayU (il pannello commerciante PayU), in Settings > Technical configuration (ID commerciante, chiave API) e Accounts (ID account). Per i test, PayU pubblica credenziali sandbox pubbliche e carte di prova nella pagina "Test your solution" della documentazione per sviluppatori. API Login e altre credenziali API non sono necessari, perché il pagamento avviene sulla pagina ospitata da PayU.
Internet access to your site: PayU invia il risultato del pagamento al negozio dai propri server, quindi il sito deve essere raggiungibile da Internet (non un sito locale, né protetto da password o da una pagina di manutenzione).
VibeFox license key: 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_latam_payment in /wp-content/plugins/ tramite FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > PayU LATAM > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina dei plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco della licenza in cima alla pagina e fai clic su Activate.
5. Inserisci le credenziali sandbox e quelle live (vedi Configurazione). Non devi configurare alcun URL di conferma in PayU.
6. Attiva Enable/Disable e salva. Mantieni Sandbox attivo finché non hai effettuato un pagamento di prova, poi deselezionalo per accettare pagamenti reali con le credenziali live.
Configurazione
Tutte le impostazioni sono su una pagina: WooCommerce > Settings > Payments > PayU LATAM. Sopra i campi, la pagina ti avvisa quando la modalità sandbox è attiva (Sandbox mode. I pagamenti vanno alla sandbox PayU e non viene addebitato denaro reale.), quando manca l'ID commerciante, l'ID account o la chiave API dell'ambiente corrente e quando PayU LATAM non elabora la valuta del negozio. Negli ultimi due casi PayU LATAM non viene mostrato al checkout. Nell'elenco dei metodi di pagamento, PayU LATAM è indicato come da configurare finché non vengono compilate le tre credenziali dell'ambiente corrente. Gli spazi all'inizio o alla fine di una credenziale vengono ignorati.
Generale
Enable/Disable: Enable PayU LATAM attiva o disattiva il metodo di pagamento. Predefinito: off.
Title: il titolo del metodo di pagamento mostrato al cliente durante il checkout. Predefinito: PayU LATAM.
Description: la descrizione del metodo di pagamento mostrata al cliente durante il checkout. Predefinito: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.
Ambiente
Sandbox: Enable the PayU sandbox (test mode). I pagamenti vanno alla sandbox PayU con le credenziali sandbox riportate sotto e non viene addebitato denaro reale. Se disattivato, vengono usati le credenziali live e il checkout live di PayU. Predefinito: on.
Credenziali live
Le trovi nel modulo PayU: Settings > Technical configuration (ID commerciante, chiave API) e Accounts (ID account del paese in cui vendi). La sezione rimanda al pannello commerciante PayU.
Merchant ID: l'identificatore numerico del tuo commercio PayU.
Account ID: l'identificatore dell'account PayU. Esiste un account per paese.
API Key: la chiave segreta usata per firmare i pagamenti e verificare le notifiche PayU.
Credenziali sandbox
PayU pubblica credenziali di test pubbliche e carte di prova per la propria sandbox. La sezione rimanda alla pagina "Test your solution" della documentazione PayU.
Sandbox merchant ID: l'ID commerciante per la sandbox PayU.
Sandbox account ID: l'ID account per la sandbox PayU.
Sandbox API key: la chiave API per la sandbox PayU.
Ogni tentativo di pagamento memorizza il proprio ambiente. La conferma di un pagamento sandbox viene verificata con la chiave API e l'ID commerciante sandbox, quella di un pagamento live con i valori live, così i pagamenti in attesa continuano a funzionare dopo il passaggio. Aggiornando dalla versione 1.0, che aveva un solo insieme di credenziali, i vecchi valori vengono copiati nei campi sandbox se la sandbox era attiva. Controlla le impostazioni dopo l'aggiornamento.
URL di conferma
Questa sezione mostra l'URL a cui PayU comunica ogni risultato di pagamento. Ha un aspetto come https://your-site/wc-api/payu_lp/. Il plugin lo invia a PayU con ogni pagamento, quindi non c'è nulla da configurare in PayU. La pagina deve essere raggiungibile da Internet. PayU firma la conferma con la tua chiave API. Le conferme senza firma valida, con un altro ID commerciante o con un riferimento di pagamento che questo negozio non ha emesso per l'ordine vengono rifiutate. Il plugin gestisce questi stati delle transazioni PayU:
Gli altri stati vengono solo aggiunti come nota dell'ordine. Senza conferma, un ordine non viene mai segnato come pagato: rimane In attesa di pagamento.
Avanzate
Debug log: Log payment requests and PayU notifications scrive i dettagli in WooCommerce > Status > Logs, origine wcp_payu_latam_payment, senza chiavi o dati personali. Gli errori e le notifiche rifiutate vengono sempre registrati. Predefinito: off.
Delete data: Delete the settings and logs when the plugin is deleted. Disattivare il plugin non elimina mai nulla. I dati PayU salvati negli ordini vengono conservati. Predefinito: off.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita PayU LATAM) ed effettua l'ordine. Nel blocco Checkout in modalità sandbox vede Sandbox mode: no real payment is made. L'ordine rimane In attesa di pagamento e il cliente passa a una pagina di pagamento del tuo negozio con il testo Thank you for your order. You are being redirected to PayU LATAM to complete the payment… La pagina invia automaticamente un modulo firmato alla pagina PayU WebCheckout. Se ciò non avviene, il cliente fa clic su Pay with PayU LATAM o su Cancel order per annullare l'ordine.
Il modulo contiene totale e valuta dell'ordine, imposta e base imponibile dell'ordine (entrambe 0 per ordini senza imposte, affinché PayU non aggiunga un'IVA predefinita), la descrizione Order # con numero d'ordine e nome del negozio, e-mail, nome, telefono e indirizzo di fatturazione del cliente. La pagina PayU si apre in spagnolo, portoghese o inglese secondo la lingua del negozio. Sulla pagina PayU il cliente paga con qualsiasi metodo abilitato nel tuo account PayU.
Ogni visita alla pagina di pagamento avvia un nuovo tentativo con un proprio riferimento (numero d'ordine e marca temporale). Vengono memorizzati gli ultimi 30 tentativi dell'ordine: se il cliente paga in una vecchia scheda PayU, il pagamento viene comunque accettato.
L'ordine viene segnato come pagato solo dopo che PayU lo conferma con la conferma firmata. Il ritorno del cliente da PayU non segna mai un ordine come pagato. Quando il cliente torna:
Se mancano le credenziali dell'ambiente corrente, il cliente vede PayU LATAM is not available right now. Please choose another payment method. Per una valuta dell'ordine non supportata il messaggio è PayU LATAM does not accept payments in seguito dalla valuta. Un ordine già pagato non viene pagato di nuovo: la pagina di pagamento mostra This order has already been paid.
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 non prevede un modulo di pagamento nel negozio, rimborsi da WooCommerce, carte salvate, abbonamenti o impostazioni delle rate (PayU mostra le rate nella propria pagina). Non interroga l'API PayU sullo stato del pagamento: solo la conferma firmata aggiorna l'ordine.
Ordini
Stati dell'ordine
Pending payment: il cliente è stato inviato a PayU e non ha ancora pagato, oppure PayU non ha ancora inviato la conferma.
Processing: PayU ha confermato il pagamento e importo e valuta corrispondono. La nota dell'ordine mostra la transazione PayU, l'importo, il metodo di pagamento e [sandbox] per i pagamenti sandbox. L'ID transazione dell'ordine è l'ID transazione PayU. Gli ordini con soli prodotti virtuali scaricabili diventano Completato, come previsto da WooCommerce per impostazione predefinita.
On hold: PayU segnala il pagamento come in attesa (contanti o pagamento bancario), l'importo pagato o la valuta non corrisponde al totale dell'ordine, oppure è stato approvato un pagamento per un ordine annullato. La nota dell'ordine indica il motivo: controlla il pagamento nel modulo PayU, poi elabora l'ordine, ripristinalo o rimborsa il pagamento.
Failed: l'ultimo tentativo di pagamento è stato rifiutato, è scaduto o è terminato con un errore. La nota mostra il messaggio PayU. Il cliente può pagare di nuovo. Il rifiuto di un tentativo precedente o di un ordine che ha già un pagamento approvato viene solo aggiunto come nota.
Ogni notifica viene elaborata una volta, con un blocco per ordine: le notifiche PayU ripetute non duplicano note, riduzioni delle scorte o e-mail. Se un'altra richiesta impiega troppo tempo ad aggiornare l'ordine, alla conferma viene risposto con un errore e PayU la invia di nuovo più tardi. Un ordine pagato, completato o rimborsato non viene mai riaperto. Se arriva un altro pagamento approvato per un ordine già pagato, una nota lo segnala: se il cliente ha pagato due volte, rimborsa il duplicato nel modulo PayU.
Rimborsi
I rimborsi non si effettuano da WooCommerce. Rimborsa la transazione nel modulo PayU e, se necessario, registra manualmente il rimborso in WooCommerce.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza è in cima a WooCommerce > Settings > Payments > PayU LATAM. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino a cui la licenza è attiva e il tuo dominio. Usa Check now per ricontrollare lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il collegamento 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 il suo posto per il dominio. Libera il posto nel tuo account vibefox.net.
Senza una chiave attiva, PayU LATAM non viene mostrato ai clienti al checkout. Se viene comunque avviato un pagamento, 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 (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria appare nella pagina dei plugin e nelle pagine WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono ancora confermati.
Quando la licenza scade, il plugin continua a funzionare, ma aggiornamenti e assistenza richiedono un rinnovo. Lo stato viene ricontrollato automaticamente in background.
Risoluzione dei problemi
PayU LATAM non appare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo e che ID commerciante, ID account e chiave API dell'ambiente corrente siano compilati: le credenziali sandbox quando Sandbox è attivo, quelle live quando è disattivato. Verifica che la valuta del negozio (o dell'ordine nella pagina di pagamento dell'ordine) sia ARS, BRL, CLP, COP, MXN, PEN o USD. La pagina delle impostazioni mostra un avviso per ciascun problema.
Il pagamento è riuscito, ma l'ordine rimane Pending payment: la conferma PayU non ha raggiunto il tuo negozio o è stata rifiutata. Controlla che l'URL di conferma nelle impostazioni sia raggiungibile da Internet (nessun sito locale, modalità manutenzione, firewall o protezione con password). Cerca le conferme rifiutate in WooCommerce > Status > Logs, origine wcp_payu_latam_payment. PayU invia di nuovo la conferma dopo qualsiasi risposta di errore.
La conferma riceve Invalid signature: non è stata firmata con la chiave API dell'ambiente del pagamento. Controlla API Key per i pagamenti live e Sandbox API key per quelli sandbox.
La conferma riceve Merchant mismatch: il suo ID commerciante differisce da Merchant ID o Sandbox merchant ID dell'ambiente del pagamento. Inserisci l'ID commerciante dell'account PayU che elabora i pagamenti.
La conferma riceve Gateway not configured: manca la chiave API o l'ID commerciante dell'ambiente del pagamento, per esempio perché sono state rimosse le credenziali sandbox mentre un pagamento sandbox era in attesa. Inseriscili di nuovo; PayU riprova la conferma.
La conferma riceve Busy, retry later: un'altra richiesta stava aggiornando l'ordine contemporaneamente. Non è stato modificato nulla e PayU invia di nuovo la conferma.
La conferma riceve Unknown reference: il riferimento di pagamento non appartiene a un ordine PayU LATAM di questo negozio, per esempio perché l'ordine è stato eliminato o spostato a un altro metodo di pagamento.
L'ordine è On hold: leggi la nota dell'ordine. Il pagamento è ancora in attesa in PayU (contanti o pagamento bancario), l'importo pagato o la valuta differiva dall'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Controlla la transazione nel modulo PayU.
Altre valute o campi del modulo: gli sviluppatori possono modificare l'elenco delle valute con il filtro payu_lp_supported_currencies, l'icona del checkout con il filtro payu_lp_icon e i campi del modulo WebCheckout con il filtro payu_lp_payment_fields.
Il blocco della licenza mostra un errore: 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 sul nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.
Disinstallazione
Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave e lo stato della licenza del plugin vengono sempre rimossi. Le impostazioni del gateway e i registri del plugin vengono rimossi solo se Delete data era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano note di pagamento, riferimenti PayU e ID transazione.
PayU è un marchio del rispettivo proprietario. Questo plugin non è affiliato a PayU né approvato da PayU.