VibeFox PagSeguro 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: real brasiliano (BRL). Il metodo di pagamento viene mostrato solo per i carrelli in BRL.

HTTPS: il tuo negozio deve essere raggiungibile da Internet tramite HTTPS, affinché PagBank possa inviare le notifiche di pagamento.

Account PagBank: un token di produzione per i pagamenti reali e un token sandbox per i test. Produzione: accedi al tuo account PagBank, apri Venda online > Integrações e fai clic su Gerar token; PagBank invia il token via e-mail. Sandbox: crea un account sandbox nel portale per sviluppatori di PagBank e copia il suo token. I token sandbox e di produzione funzionano solo nel loro ambiente.

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

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

4. Inserisci il token sandbox e, per accettare pagamenti reali, il token di produzione.

5. Attiva Enable / Disable e fai clic su Save. Effettua pagamenti di prova con Sandbox Mode attivo, poi disattivalo per accettare pagamenti reali.

All'installazione il modulo crea due stati dell'ordine, Awaiting PagBank payment e PagBank payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences; la valuta BRL deve restare consentita per il modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox PagSeguro Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra la modalità attuale: SANDBOX MODE (i pagamenti vengono creati nel sandbox di PagBank, senza addebiti reali) oppure LIVE (i pagamenti vengono creati con il token di produzione). Avvisa quando manca il token della modalità attuale (in tal caso il metodo di pagamento non viene mostrato al checkout) e quando la valuta predefinita del negozio non è BRL (in tal caso il metodo di pagamento non viene offerto per i carrelli in altre valute).

PagSeguro / PagBank

Enable / Disable: Enable PagSeguro/PagBank payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: PagSeguro / PagBank. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

Account PagBank

La sezione spiega dove ottenere i token e rimanda al tuo account PagBank e alla pagina di PagBank sui token.

Sandbox Mode: Enable sandbox/test mode (no real charges). I nuovi pagamenti vanno al sandbox di PagBank con il token sandbox, e i clienti vedono SANDBOX MODE — Using test environment. No real charges. sotto il metodo di pagamento. Le verifiche di stato e i rimborsi di un ordine usano sempre l'ambiente e il token con cui è stato creato il suo pagamento. Predefinito: attivo.

Sandbox token: il token sandbox di PagBank. Viene usato finché la modalità sandbox è attiva.

Production token: il token di produzione di PagBank (Bearer). Viene usato quando la modalità sandbox è disattivata. Tienilo segreto.

I token salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarlo.

Clear saved tokens: spunta un token e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Notifiche di pagamento

Notification URL: ogni pagamento indica a PagBank dove segnalare i cambi di stato, quindi non c'è nulla da configurare in PagBank. La sezione mostra l'URL. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_pagseguro_gateway/webhook. L'indirizzo deve essere raggiungibile da Internet tramite HTTPS.

Le notifiche che contengono un header x-authenticity-token vengono verificate con il token dell'ambiente in cui è stato creato il pagamento; una firma non valida viene rifiutata. Il corpo della notifica in sé non è mai considerato attendibile: il modulo legge sempre dall'API di PagBank il checkout e l'ordine PagBank (stato, importo, valuta) prima di creare o modificare un ordine. Senza notifiche, l'ordine viene creato quando il cliente torna nel negozio dopo aver pagato.

Avanzate

Debug log: Log API requests and notifications scrive i dettagli in logs/wc_psg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. I log non contengono token né dati dei clienti. Gli errori vengono sempre registrati. Predefinito: disattivato.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il log. Gli ordini, i loro riferimenti PagBank (necessari per i rimborsi) e gli stati degli ordini vengono sempre conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita PagSeguro / PagBank) e conferma. Il modulo crea un checkout PagBank per il totale del carrello in BRL come un unico articolo, Order # con il numero del carrello e il nome del tuo negozio, e invia il cliente alla pagina di pagamento di PagBank. Nome ed e-mail del cliente, il CPF o CNPJ dal campo Identification number o VAT number dell'indirizzo e un numero di telefono brasiliano vengono compilati quando il negozio li ha; il cliente può completarli o correggerli nella pagina di PagBank. Il cliente paga con i metodi attivati nel tuo account PagBank, ad esempio carta di credito, PIX o boleto. La pagina di pagamento scade dopo 120 minuti. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di PagBank: il modulo legge il pagamento dall'API di PagBank quando arriva la notifica o quando il cliente torna, e un semplice ritorno non segna mai un ordine come pagato. L'ordine viene poi creato e il cliente vede la pagina di conferma dell'ordine con Your payment with PagBank has been received. Per un boleto o un PIX generato, o per un pagamento in analisi, la pagina mostra Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. Se tale pagamento viene rifiutato o annullato in seguito, la pagina mostra Your PagBank payment was not completed. Please contact us about this order. Se PagBank non ha ancora confermato il pagamento quando il cliente torna, compare una pagina Payment confirmation con We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. e un pulsante Check again.

Se il pagamento non è stato completato, il cliente torna al checkout con The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. oppure The payment was declined by PagBank. Please try again with another card or payment method. Il carrello viene conservato. Se un ordine in attesa di un boleto o di un PIX è stato annullato, il cliente vede The PagBank payment was cancelled, so the order was cancelled.

Quando il cliente paga di nuovo, il checkout PagBank aperto viene riutilizzato se importo e ambiente sono gli stessi e non scade entro 10 minuti. Altrimenti il checkout precedente viene disattivato e non può più essere pagato. Un pagamento effettuato in precedenza nella pagina precedente vale ancora per il carrello, e viene creato l'ordine invece di un nuovo pagamento.

Se PagBank non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, ad esempio PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. oppure Could not connect to PagBank. Please try again in a moment. Il motivo tecnico viene scritto nel log.

Le notifiche funzionano anche quando il negozio è in modalità manutenzione e non vengono bloccate dalla restrizione per paese del negozio.

Il modulo non ha un modulo carta nel negozio, né carte salvate, abbonamenti o pagamenti ricorrenti, né pagamenti divisi o marketplace. I metodi di pagamento e le rate sono quelli configurati nel tuo account PagBank.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a PagBank e non ha pagato, la carta è stata rifiutata o la pagina di pagamento è scaduta. Esiste solo il carrello, e il cliente può pagare di nuovo.

Payment accepted: il pagamento è stato confermato con l'importo e la valuta previsti. Il pagamento viene registrato con il charge ID di PagBank come ID transazione, e una nota mostra importo, metodo di pagamento e charge ID.

Awaiting PagBank payment: è stato generato un boleto o un PIX in attesa di pagamento, oppure il pagamento è in analisi. L'ordine passa a Payment accepted quando PagBank lo segnala come pagato.

PagBank payment on hold: PagBank ha segnalato un importo o una valuta diversi da quelli del carrello (per esempio il carrello è stato modificato dopo la creazione della pagina di pagamento), un pagamento è arrivato dopo che l'ordine era stato annullato (verifica le scorte, poi completa l'ordine o rimborsa il pagamento in PagBank), oppure un pagamento con carta è stato autorizzato ma non catturato (catturalo in PagBank). La nota lo spiega. Il denaro effettivamente ricevuto viene registrato nell'ordine.

Payment error: un pagamento in attesa o in analisi è stato rifiutato.

Canceled: un pagamento in attesa, per esempio un boleto o un PIX scaduto, è stato annullato.

Refunded: il pagamento è stato rimborsato interamente, tramite il modulo o nella dashboard di PagBank.

Ogni stato di PagBank viene applicato una sola volta, quindi notifiche o ritorni ripetuti non aggiungono note né cambiano lo stato. Se arriva un secondo pagamento per un ordine già pagato, l'ordine non viene modificato e una nota ti chiede di rimborsare il duplicato in PagBank.

Blocco «PagBank payment»

La pagina dell'ordine mostra un blocco PagBank payment con il checkout PagBank, gli ID dell'ordine e del charge PagBank, il metodo di pagamento, lo stato, l'importo pagato e rimborsato, un badge Sandbox per i pagamenti sandbox, lo storico dei rimborsi e le PagBank notes dell'ordine.

Rimborsi

Nel blocco PagBank payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via PagBank. Conferma la domanda Refund this amount through PagBank? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine dei moduli. Il limite è l'importo addebitato da PagBank, quindi dopo una discrepanza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non il totale dell'ordine. Il rimborso viene inviato nell'ambiente e con il token con cui è stato effettuato il pagamento. Un rimborso viene registrato solo quando PagBank lo conferma; altrimenti il blocco mostra l'errore, per esempio PagBank refund failed: ... o PagBank did not confirm the refund, e non viene registrato nulla. I rimborsi dei pagamenti boleto e i rimborsi parziali dei PIX seguono le regole di PagBank. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con il charge ID. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale non cambia lo stato. I rimborsi sono disponibili dopo che PagBank ha segnalato il pagamento come pagato.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite PagBank.

I rimborsi effettuati nella dashboard di PagBank vengono rilevati con la notifica successiva: un rimborso totale imposta l'ordine su Refunded, un rimborso parziale aggiunge una nota con l'importo rimborsato, e puoi registrare il rimborso nell'ordine manualmente.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco di licenza License — VibeFox PagSeguro Gateway è il primo blocco della pagina Modules > Module Manager > VibeFox PagSeguro Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Poi 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-pagseguro 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 dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera lo slot del dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, PagBank 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. La vetrina di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento è 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, e i rimborsi funzionano.

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

PagBank non compare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo, che il token della modalità attuale sia impostato (Sandbox token in modalità sandbox, Production token in modalità live) e che la valuta del carrello sia BRL. La pagina delle impostazioni mostra un avviso quando il token manca o la valuta del negozio non è BRL. In Payment > Preferences verifica che il modulo sia consentito per BRL, per il paese del cliente e per il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: PagBank non ha ancora segnalato il pagamento e il cliente non è tornato nel negozio. L'ordine viene creato appena arriva la notifica. Verifica che il tuo negozio sia raggiungibile da Internet tramite HTTPS all'indirizzo della Notification URL, e attiva il Debug log per vedere le notifiche.

La notifica risponde Invalid signature: il x-authenticity-token non corrisponde al token dell'ambiente in cui è stato effettuato il pagamento, oppure quel token non è salvato. Verifica che nelle impostazioni ci sia il token giusto.

La notifica risponde Verification failed, retry later: non è stato possibile raggiungere l'API di PagBank, manca il token dell'ambiente del pagamento, oppure il carrello era in elaborazione da un'altra richiesta nello stesso momento. PagBank ripete la notifica.

La notifica risponde Order not found: la notifica riguarda un carrello che non è stato pagato con questo modulo in questo negozio. Non viene modificato nulla.

Il cliente vede PagBank payments are temporarily unavailable. Please choose another payment method.: il token della modalità attuale manca oppure PagBank lo ha rifiutato.

Il cliente vede PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).: il carrello è in un'altra valuta.

L'ordine è PagBank payment on hold: leggi le note nel blocco PagBank payment (vedi Stati dell'ordine), confronta gli importi in PagBank, poi completa l'ordine o rimborsa il pagamento.

Il rimborso non riesce con un messaggio sul token: il pagamento è stato effettuato in sandbox o in produzione, e il token di quell'ambiente manca o è stato rifiutato. Inserisci il token corretto e riprova.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox PagSeguro 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 gateway e il log. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I pagamenti e i rimborsi PagBank degli ordini e gli stati degli ordini Awaiting PagBank payment e PagBank payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono ancora essere rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID transazione.

PagSeguro e PagBank sono marchi dei rispettivi titolari. Questo modulo non è affiliato né approvato da PagSeguro o PagBank.