VibeFox PagSeguro for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 8.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
PHP: 8.0 o successivo.
Valuta: real brasiliano (BRL). Il metodo di pagamento non viene mostrato al checkout quando la valuta del negozio (o, nella pagina Pay for order, quella dell'ordine) non è BRL.
HTTPS: il tuo sito deve essere raggiungibile da Internet tramite HTTPS, così che 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 rispettivo ambiente.
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona per 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_pagseguro_gateway in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > PagSeguro / PagBank > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.
4. Inserisci la tua chiave di licenza VibeFox nel blocco di licenza in alto nella pagina e fai clic su Activate.
5. Inserisci il token sandbox e, per accettare pagamenti reali, il token di produzione.
6. Attiva Enable / Disable e salva. Esegui pagamenti di prova con Sandbox Mode attivo, poi disattivalo per accettare pagamenti reali.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > PagSeguro / PagBank. Sotto il titolo la pagina mostra la modalità attuale: SANDBOX MODE (i pagamenti vengono creati nella sandbox di PagBank, senza addebiti reali) oppure LIVE (i pagamenti vengono creati con il token di produzione). Ti avvisa quando manca il token della modalità attuale (in quel caso il metodo di pagamento viene nascosto al checkout) e quando la valuta del negozio non è BRL. Nell'elenco dei metodi di pagamento PagBank risulta da configurare finché non viene inserito il token della modalità attuale, e mentre la modalità sandbox è attiva compare un badge di modalità test.
Generale
Enable / Disable: Enable PagSeguro/PagBank payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: PagSeguro / PagBank.
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 contiene i collegamenti al tuo account PagBank e alla pagina di PagBank sui token.
Sandbox Mode: Enable sandbox/test mode (no real charges). I nuovi pagamenti vanno alla sandbox di PagBank con il token sandbox, e al checkout compare la nota SANDBOX MODE. 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 mentre la modalità sandbox è attiva.
Production token: il token di produzione di PagBank. Viene usato quando la modalità sandbox è disattivata. Tienilo segreto.
Il token unico della versione 1.0 viene spostato automaticamente: se la modalità sandbox era attiva, diventa il token sandbox; altrimenti resta il token di produzione.
Notifiche di pagamento
Ogni pagamento comunica a PagBank dove inviare le variazioni di stato, quindi in PagBank non c'è nulla da configurare. La sezione mostra l'URL di notifica. Ha questo aspetto: https://your-site/wc-api/webhook_wc_pagseguro/. 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 dell'ordine; una firma non valida viene rifiutata. Il contenuto della notifica stessa non è mai considerato attendibile: il plugin legge sempre il checkout e l'ordine PagBank tramite l'API PagBank (stato, importo e valuta) prima di modificare l'ordine.
Avanzate
Debug log: Log API requests and notifications scrive i dettagli in WooCommerce > Status > Logs, origine wcp_pagseguro_gateway. Gli errori vengono sempre registrati. I log non contengono token né dati dei clienti. Predefinito: disattivato.
Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita PagSeguro / PagBank) e completa l'ordine. Il plugin crea un checkout PagBank per il totale esatto dell'ordine in BRL come un unico articolo, Order # con il numero dell'ordine e il nome del tuo negozio, e invia il cliente alla pagina di pagamento di PagBank. Nome e e-mail del cliente, il CPF o CNPJ dai campi del plugin Brazilian Market on WooCommerce e un numero di telefono brasiliano vengono compilati quando il negozio li ha; il cliente può completarli o correggerli nella pagina PagBank. Il cliente paga con i metodi attivati nel tuo account PagBank, per esempio carta di credito, PIX o boleto.
La pagina di pagamento scade 5 minuti prima che il timer Hold stock di WooCommerce annulli l'ordine non pagato (almeno 10 minuti), oppure dopo 120 minuti se le scorte non vengono riservate.
Dopo il pagamento, il cliente torna al negozio. Il ritorno viene verificato come una notifica: il plugin legge il pagamento tramite l'API PagBank, e un ritorno da solo non segna mai un ordine come pagato. Un ordine pagato, oppure un pagamento in attesa (boleto, PIX, analisi), porta alla pagina Ordine ricevuto; l'ordine viene confermato dalla notifica se PagBank non l'ha ancora segnalato.
Se il pagamento non è stato completato, il cliente torna alla pagina Pay for order 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. Se il pagamento è stato annullato e con esso l'ordine, il cliente va al carrello con 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 sulla pagina precedente continua a valere per l'ordine.
Se PagBank non riesce ad avviare il pagamento, il cliente vede un breve messaggio, per 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 indicato da PagBank viene aggiunto alle note dell'ordine.
Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).
Il plugin non ha un modulo per la carta sul sito, carte salvate, abbonamenti o pagamenti ricorrenti, né pagamenti frazionati o marketplace. I metodi di pagamento e le rate sono quelli configurati nel tuo account PagBank.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a PagBank e non ha ancora pagato. Una nota mostra l'ID del checkout PagBank e l'ambiente. Se la pagina di pagamento scade senza pagamento, una nota lo segnala e lo stato non cambia.
Processing: il pagamento è stato confermato. È lo stato standard di WooCommerce dopo il pagamento; gli ordini con solo prodotti scaricabili virtuali diventano Completato. La nota dell'ordine mostra l'importo, il metodo di pagamento e l'ID dell'addebito PagBank, che è anche l'ID transazione dell'ordine.
On hold: è stato generato un boleto o un PIX e si attende il pagamento; il pagamento è in analisi; un pagamento con carta è stato autorizzato ma non acquisito (acquisiscilo in PagBank); l'importo o la valuta pagati non corrispondono all'ordine; oppure un pagamento è arrivato dopo che WooCommerce ha annullato l'ordine non pagato (controlla le scorte, poi completa l'ordine o rimborsa il pagamento in PagBank). La nota dell'ordine spiega il motivo.
Failed: il pagamento è stato rifiutato. Il cliente può pagare di nuovo dalla pagina Pay for order.
Cancelled: il pagamento è stato annullato, per esempio un boleto o un PIX scaduto.
Refunded: il pagamento è stato rimborsato interamente dalla dashboard di PagBank.
Ogni stato di PagBank viene applicato una sola volta, quindi notifiche o ritorni ripetuti non aggiungono note, e-mail o riduzioni di scorte. Se per un ordine già pagato arriva un secondo pagamento, una nota ti chiede di rimborsarlo in PagBank.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via PagSeguro / PagBank (il pulsante mostra il titolo del tuo metodo di pagamento). Sono supportati rimborsi totali e parziali. 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 WooCommerce mostra l'errore, per esempio PagBank refund failed: ... oppure PagBank did not confirm the refund, e non viene registrato nulla. I rimborsi dei pagamenti boleto e i rimborsi parziali PIX seguono le regole di PagBank. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID dell'addebito.
I rimborsi effettuati nella dashboard di PagBank non vengono importati come righe di rimborso di WooCommerce. Un rimborso totale imposta l'ordine come Rimborsato; un rimborso parziale aggiunge una nota con l'importo rimborsato, e puoi registrare il rimborso nell'ordine manualmente.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco di licenza si trova in alto in WooCommerce > Settings > Payments > PagSeguro / PagBank. 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 controllare 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 per un solo dominio. Rimuovere la chiave da un sito non libera lo slot del dominio; liberalo 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. Gli amministratori del negozio connessi vedono ancora il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.
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 negozio sia BRL. La pagina delle impostazioni mostra un avviso in ogni caso.
Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: PagBank non ha ancora segnalato il pagamento e il cliente non è tornato al negozio. L'ordine viene aggiornato non appena arriva la notifica. Verifica che il tuo sito sia raggiungibile da Internet tramite HTTPS e controlla WooCommerce > Status > Logs, origine wcp_pagseguro_gateway.
La notifica risponde Invalid signature: il x-authenticity-token non corrisponde al token dell'ambiente in cui è stato pagato l'ordine. Verifica che nelle impostazioni sia inserito il token corretto.
La notifica risponde Verification failed, retry later: l'API PagBank non è raggiungibile, il token dell'ambiente dell'ordine manca, oppure l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. PagBank riprova la notifica.
La notifica risponde Order not found: l'ordine non esiste in questo negozio oppure è stato pagato con un altro metodo di pagamento. Non viene modificato nulla.
Il cliente vede This order is already being processed: una notifica o il ritorno del cliente stava aggiornando l'ordine nello stesso momento. Il cliente può riprovare tra poco.
Il cliente vede PagBank payments are temporarily unavailable: il token della modalità attuale manca oppure PagBank lo ha rifiutato.
Il cliente vede PagSeguro/PagBank only accepts payments in Brazilian Real (BRL): l'ordine è in un'altra valuta.
L'ordine è In attesa con la nota Amount/currency does not match: PagBank ha segnalato un pagamento il cui importo o la cui valuta differisce dal totale dell'ordine, per esempio perché l'ordine è stato modificato dopo la creazione della pagina di pagamento. Confronta gli importi in PagBank e completa o rimborsa l'ordine manualmente.
Il rimborso fallisce 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.
Il blocco di licenza mostra un errore: segui il messaggio nel blocco. Per 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 per il 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 nella pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, le altre opzioni del plugin e i suoi log vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano disponibili per una successiva reinstallazione. Gli ordini esistenti conservano le note di pagamento, gli ID transazione e i dati PagBank.
PagSeguro e PagBank sono marchi dei rispettivi titolari. Questo plugin non è affiliato né approvato da PagSeguro o PagBank.