VibeFox PayU LATAM for PrestaShop — Guida

Requisiti

PrestaShop: 8.0–9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Valuta: il carrello 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ù. Con altre valute il metodo di pagamento non viene mostrato al checkout.

Account PayU Latam: 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 di PayU) in Settings > Technical configuration (merchant ID, API key) e Accounts (account ID). Per i test, PayU pubblica credenziali sandbox pubbliche e carte di prova nella pagina "Test your solution" della propria documentazione per sviluppatori. Le credenziali API Login e le altre credenziali API non sono necessarie, perché il pagamento avviene sulla pagina ospitata da PayU e il modulo non chiama mai l'API di PayU.

Raggiungibilità del negozio da Internet: PayU invia il risultato del pagamento al tuo negozio dai propri server, quindi il negozio deve essere raggiungibile da Internet (non un sito locale e non protetto da password).

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure trova più tardi VibeFox PayU LATAM Payment nell'elenco dei moduli e clicca su Configure.

3. Inserisci la chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure, poi clicca su Activate (vedi Chiave di licenza).

4. Inserisci le credenziali sandbox e le tue credenziali live (vedi Configurazione). Non è necessario configurare alcun URL di conferma in PayU.

5. Attiva Enable/Disable e clicca su Save. Lascia attivo Sandbox finché non hai effettuato un pagamento di prova, poi disattivalo per accettare pagamenti reali con le credenziali live.

All'installazione il modulo crea due stati dell'ordine, Awaiting PayU LATAM payment e PayU LATAM payment on hold. PrestaShop offre un nuovo metodo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences. Un paese abilitato in seguito deve essere selezionato anche lì per il modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox PayU LATAM Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Sandbox mode. Payments go to the PayU sandbox and no real money is charged. mentre il sandbox è attivo, un errore quando mancano l'ID commerciante, l'ID account o la chiave API dell'ambiente attuale, e un avviso quando PayU LATAM non elabora la valuta predefinita del negozio. Finché mancano le credenziali, PayU LATAM non viene mostrato al checkout. Gli spazi all'inizio o alla fine di una credenziale vengono ignorati. La pagina non salva un Title vuoto e mostra Enter a title for the payment method.

PayU LATAM

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

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

Description: la descrizione del metodo di pagamento mostrata al cliente al 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: i pagamenti vanno al sandbox di PayU con le credenziali sandbox sottostanti, e non viene addebitato denaro reale. Quando è disattivato, vengono usate le credenziali live e la pagina di pagamento live di PayU. Predefinito: attivo. Mentre è attivo, i clienti vedono Sandbox mode: no real money is charged. sotto il metodo di pagamento.

Credenziali live

Si trovano nel modulo PayU: Settings > Technical configuration (merchant ID, API key) e Accounts (account ID del paese in cui vendi). La sezione rimanda al pannello commerciante di PayU.

Merchant ID: l'identificativo numerico del tuo commercio PayU.

Account ID: l'identificativo dell'account PayU. C'è 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 il proprio sandbox. La sezione rimanda alla pagina "Test your solution" della documentazione PayU.

Sandbox merchant ID: l'ID commerciante per il sandbox PayU.

Sandbox account ID: l'ID account per il sandbox PayU.

Sandbox API key: la chiave API per il sandbox PayU.

Le chiavi API salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved secrets: seleziona API Key o Sandbox API key e clicca su Save per rimuovere la chiave salvata. Un campo vuoto mantiene il valore salvato.

Ogni tentativo di pagamento memorizza il proprio ambiente. La conferma di un pagamento sandbox viene verificata con la chiave API e l'ID commerciante del sandbox, quella di un pagamento reale con quelli live, quindi i pagamenti in attesa continuano a funzionare dopo il passaggio. Un pagamento sandbox confermato dopo il passaggio viene contrassegnato come [sandbox] nelle note dell'ordine.

URL di conferma

Questa sezione mostra l'URL a cui PayU comunica ogni esito di pagamento. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_payu_latam_payment/confirmation, eventualmente con un codice lingua come /en/. Il modulo lo invia a PayU con ogni pagamento, quindi non c'è nulla da configurare in PayU. L'URL deve essere raggiungibile da Internet. Funziona anche mentre il negozio è in manutenzione e non è bloccato dalla restrizione per paese del negozio. La conferma è firmata da PayU con la tua chiave API. Le conferme senza firma valida, con un altro ID commerciante o con un riferimento di pagamento non emesso da questo negozio vengono rifiutate. Il modulo gestisce questi stati di transazione PayU:

Gli altri stati vengono aggiunti solo come nota. Senza la conferma, non viene creato alcun ordine.

Avanzate

Debug log: registra le richieste di pagamento e le notifiche PayU in logs/payu_lp_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi e dati personali non vengono registrati. Errori e notifiche rifiutate vengono sempre registrati, anche quando questo interruttore è disattivato. Predefinito: disattivato.

Log: mostra la dimensione e le ultime voci del registro. Clicca su Clear log per svuotarlo.

Delete data: elimina le impostazioni e i registri quando il modulo viene disinstallato. I dati PayU degli ordini (tentativi di pagamento) e gli stati dell'ordine vengono conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita PayU LATAM) e conferma. Una pagina del tuo negozio mostra You are being redirected to PayU LATAM to complete the payment... e invia automaticamente un form firmato alla pagina WebCheckout di PayU. Se non succede, il cliente clicca su Pay with PayU LATAM, oppure su Back to checkout per tornare indietro. In questa fase non esiste ancora alcun ordine.

Il form contiene il totale e la valuta del carrello, l'imposta e la base imponibile del carrello (entrambe 0 per i carrelli senza imposte, così PayU non aggiunge un'IVA predefinita), la descrizione Cart # con il numero del carrello e il nome del negozio, l'e-mail, il nome, il telefono e l'indirizzo di fatturazione del cliente. La pagina PayU si apre in spagnolo, portoghese o inglese, in base alla lingua del carrello. Sulla pagina PayU il cliente paga con qualsiasi metodo abilitato nel tuo account PayU.

Ogni visita alla pagina di pagamento avvia un nuovo tentativo di pagamento con un proprio riferimento (PS, il numero del carrello e un timestamp). I tentativi precedenti vengono memorizzati: se il cliente paga da una scheda PayU aperta in precedenza, il pagamento viene comunque accettato.

L'ordine viene segnato come pagato solo dopo la conferma firmata di PayU. Il cliente che torna da PayU non segna mai un ordine come pagato. Quando il cliente torna:

Se mancano le credenziali dell'ambiente attuale, il cliente vede PayU LATAM is not available right now. Please choose another payment method. Per una valuta del carrello non supportata il messaggio è PayU LATAM does not accept payments in seguito dalla valuta. Un carrello che ha già un ordine non viene pagato di nuovo: il cliente va alla pagina di conferma del suo ordine.

Il modulo non offre un form di pagamento nel negozio, né rimborsi da PrestaShop, carte salvate, abbonamenti o impostazioni delle rate (PayU mostra le rate nella propria pagina). Non interroga l'API PayU per lo stato del pagamento: solo la conferma firmata aggiorna l'ordine.

Ordini

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a PayU e non ha pagato, il pagamento è stato rifiutato o PayU non ha ancora inviato la conferma. Esiste solo il carrello.

Payment accepted: PayU ha confermato il pagamento e importo e valuta corrispondono. Il pagamento viene registrato con l'ID transazione PayU, e una nota mostra la transazione, l'importo, il metodo di pagamento e [sandbox] per i pagamenti sandbox.

Awaiting PayU LATAM payment: PayU segnala il pagamento come in attesa (pagamento in contanti o bancario). L'ordine passa a Payment accepted quando PayU conferma il pagamento.

PayU LATAM payment on hold: l'importo o la valuta pagati non corrispondono al totale del carrello, oppure un pagamento è stato approvato per un ordine annullato. Il pagamento viene registrato se è nella valuta dell'ordine. La nota indica il caso: controlla il pagamento nel modulo PayU, poi elabora l'ordine, ripristinalo o rimborsa il pagamento.

Payment error: un pagamento in attesa dell'ultimo tentativo è stato in seguito rifiutato, è scaduto o si è concluso con un errore. La nota mostra il messaggio di PayU. Questo carrello non può essere pagato di nuovo: il cliente effettua un nuovo ordine. Un rifiuto di un tentativo precedente, o di un ordine che ha già un pagamento approvato, viene aggiunto solo come nota.

Ogni notifica viene elaborata una sola volta, con un blocco per carrello: le notifiche PayU ripetute non creano un secondo ordine e non aggiungono note due volte. Un ordine pagato non viene mai riaperto o retrocesso. Se per un ordine già pagato arriva un altro pagamento approvato, una nota lo segnala: se il cliente ha pagato due volte, rimborsa il duplicato nel modulo PayU.

Blocco pagamento PayU LATAM

La pagina dell'ordine mostra un blocco PayU LATAM payment con riferimento, ID transazione, riferimento PayU, stato e stato PayU, importo richiesto, importo comunicato da PayU, metodo di pagamento, messaggio PayU, un badge SANDBOX per i pagamenti sandbox, l'elenco di tutti i tentativi di pagamento del carrello e le PayU LATAM notes dell'ordine.

Rimborsi

I rimborsi non si effettuano da PrestaShop. Rimborsa la transazione nel modulo PayU, poi registra manualmente il rimborso in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox PayU LATAM Payment è il primo blocco di Modules > Module Manager > VibeFox PayU LATAM Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, il blocco mostra la chiave mascherata, lo stato (per esempio la data fino alla quale 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 compaiono la riga Product: presta-payment-payu-latam 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 cambiare la chiave. I testi del blocco seguono la lingua del back office (sono incluse le lingue 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 un posto dominio nel tuo account, clicca 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, PayU LATAM non viene mostrato ai clienti al checkout. Se comunque viene avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. Il negozio online di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo 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 dalla conferma PayU e dal ritorno del cliente.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un 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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

PayU LATAM non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che ID commerciante, ID account e chiave API dell'ambiente attuale siano compilati: le credenziali sandbox quando Sandbox è attivo, quelle live quando è disattivo. Verifica che la valuta del carrello sia ARS, BRL, CLP, COP, MXN, PEN o USD. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: la conferma di PayU non ha raggiunto il negozio o è stata rifiutata. Verifica che l'URL di conferma mostrato nelle impostazioni sia raggiungibile da Internet (niente sito locale, firewall o protezione con password). Controlla il campo Log nella pagina del modulo per le conferme rifiutate. PayU invia di nuovo la conferma dopo ogni risposta di errore.

La conferma risponde Invalid signature: la conferma non è stata firmata con la chiave API dell'ambiente del pagamento. Controlla API Key per i pagamenti live e Sandbox API key per i pagamenti sandbox.

La conferma risponde Merchant mismatch: l'ID commerciante della conferma non corrisponde a Merchant ID o Sandbox merchant ID dell'ambiente del pagamento. Inserisci l'ID commerciante dell'account PayU che elabora i pagamenti.

La conferma risponde Gateway not configured: manca la chiave API o l'ID commerciante dell'ambiente del pagamento, ad esempio perché le credenziali sandbox sono state rimosse mentre un pagamento sandbox era in attesa. Inseriscile di nuovo; PayU ripeterà la conferma.

La conferma risponde Retry: il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (ad esempio perché il modulo è disattivato). Non è stato modificato nulla e PayU invierà di nuovo la conferma. Controlla il Log per il motivo.

La conferma risponde Unknown reference: il riferimento di pagamento non è stato emesso da questo negozio.

L'URL di conferma mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste da PayU.

Il cliente vede This payment method is not available: il modulo non è consentito per il paese, la valuta o il gruppo del cliente in Payment > Preferences, oppure Enable/Disable è disattivato.

L'ordine è in PayU LATAM payment on hold: leggi le note nel blocco PayU LATAM payment. L'importo o la valuta pagati erano diversi dal carrello, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Controlla la transazione nel modulo PayU.

Disinstallazione

Vai in Modules > Module Manager, apri il menu accanto a VibeFox PayU LATAM Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data è attivo, le impostazioni e il registro vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. I tentativi di pagamento e gli stati dell'ordine Awaiting PayU LATAM payment e PayU LATAM payment on hold vengono sempre conservati, così una conferma tardiva di PayU per un vecchio tentativo viene comunque riconosciuta dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento, i riferimenti PayU e gli ID transazione.

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