VibeFox Pagar.me 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 viene nascosto quando la valuta del negozio (o, nella pagina Pay for order, quella dell'ordine) non è BRL.
Account Pagar.me: ti servono le chiavi segrete del tuo account Pagar.me: la chiave di test (sk_test_...) e, per passare in produzione, la chiave di produzione (sk_...). Si trovano nella dashboard di Pagar.me, in Development > Keys. Vengono usate solo le chiavi segrete; la chiave pubblica (pk_...) non serve. Si possono offrire solo i metodi di pagamento abilitati nel tuo account Pagar.me.
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_pagarme_gateway in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Pagar.me > 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 la chiave segreta di test e, quando passi in produzione, la chiave segreta di produzione.
6. Crea il webhook nella dashboard di Pagar.me con l'URL mostrato nelle impostazioni (vedi Configurazione).
7. Attiva Enable / Disable e salva. Effettua pagamenti di prova con Test mode attivo, poi disattivalo per accettare pagamenti reali.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Pagar.me. Sotto il titolo la pagina mostra la modalità attuale: TEST MODE (i pagamenti vengono creati con la chiave segreta di test, senza addebiti reali) oppure LIVE. Avvisa quando manca la chiave segreta della modalità attuale (il metodo di pagamento viene allora nascosto al checkout), quando la chiave di test non inizia con sk_test_, quando la chiave di produzione non inizia con sk_ o è una chiave di test, e quando la valuta del negozio non è BRL. Nell'elenco dei metodi di pagamento, Pagar.me risulta da configurare finché non viene inserita la chiave della modalità attuale, e mentre la modalità test è attiva compare un badge dedicato.
Generali
Enable / Disable: Enable Pagar.me payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Pagar.me.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.
Chiavi API
Copia le chiavi segrete dalla dashboard di Pagar.me: Development > Keys. Pagar.me usa un unico indirizzo API per i pagamenti di test e di produzione; è la chiave a determinare se un pagamento è di test o reale.
Test mode: Use the test secret key (no real charges). Mentre la modalità test è attiva, al checkout viene mostrata la nota TEST MODE. Le verifiche di stato e i rimborsi di un ordine usano sempre la chiave della modalità in cui è stato creato il suo pagamento. Predefinito: attivo.
Test secret key: la chiave segreta di test di Pagar.me (sk_test_...). Viene usata mentre la modalità test è attiva.
Live secret key: la chiave segreta di produzione di Pagar.me (sk_...). Viene usata quando la modalità test è disattivata. Tienila riservata.
L'unica chiave segreta della versione 1.0 viene spostata automaticamente: una chiave di test passa in Test secret key e la modalità test viene attivata; altrimenti resta come chiave di produzione e la modalità test viene disattivata.
Pagina di pagamento
Payment methods: i metodi offerti nella pagina di pagamento di Pagar.me. Scegli solo metodi abilitati nel tuo account Pagar.me. Predefinito: Credit card, PIX e Boleto.
Boleto due in (days): numero di giorni alla scadenza del boleto, da 1 a 30. L'ordine resta On hold finché Pagar.me non conferma il pagamento. Predefinito: 3.
Notifiche di pagamento (webhook)
Nella dashboard di Pagar.me apri Settings > Webhooks e crea un webhook con l'URL mostrato in questa sezione. Ha questo aspetto: https://your-site/wc-api/webhook_wc_pagarme/. Copialo esattamente come lo mostrano le impostazioni.
Seleziona questi eventi:
Il webhook non richiede password né firma. Il suo contenuto non viene mai considerato attendibile: il negozio ne ricava solo l'ID dell'ordine Pagar.me e legge quell'ordine dalla API di Pagar.me con la chiave della modalità in cui è stato creato. Le notifiche relative a ordini di altri negozi dello stesso account Pagar.me vengono ignorate. Senza il webhook, i pagamenti PIX e boleto effettuati in seguito vengono confermati solo quando il cliente torna al negozio.
Avanzate
Debug log: Log API requests and notifications scrive i dettagli in WooCommerce > Status > Logs, origine wcp_pagarme_gateway. Gli errori vengono sempre registrati. I log non contengono chiavi 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 Pagar.me) e conferma l'ordine. È richiesto un indirizzo e-mail di fatturazione valido. Il plugin crea un ordine Pagar.me per il totale in BRL, con le righe dell'ordine, la spedizione e le commissioni (oppure un'unica riga Order # con il numero d'ordine, quando le righe non possono sommarsi esattamente), e invia il cliente alla pagina di pagamento di Pagar.me. Nome, e-mail e, per il Brasile, telefono e indirizzo di fatturazione del cliente vengono passati a Pagar.me. Il CPF o il CNPJ vengono presi dai campi di Brazilian Market on WooCommerce, quando presenti; altrimenti il cliente lo inserisce nella pagina di Pagar.me.
Dopo il pagamento, il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Pagar.me: il negozio legge l'ordine Pagar.me dalla API, e l'importo e la valuta pagati devono corrispondere all'ordine. Un pagamento con carta, PIX o boleto effettuato segna l'ordine come pagato. Un PIX o un boleto emesso ma non ancora pagato mette l'ordine On hold finché Pagar.me non conferma il pagamento tramite webhook.
Se il cliente torna senza pagare, oppure il pagamento è stato rifiutato o annullato, arriva alla pagina Pay for order con The Pagar.me payment was not completed. You can pay the order below. oppure The Pagar.me payment was declined or canceled. You can try again below.
Quando il cliente paga di nuovo, la pagina di pagamento Pagar.me ancora aperta viene riutilizzata se importo e modalità sono gli stessi; altrimenti viene chiusa su Pagar.me prima che ne venga creata una nuova. Se nel frattempo il tentativo precedente è stato pagato, oppure il suo PIX o boleto è ancora in attesa, l'ordine viene aggiornato senza un nuovo pagamento. Se la pagina precedente non può essere chiusa, resta associata all'ordine, quindi un pagamento effettuato lì viene comunque registrato.
Se Pagar.me non riesce ad avviare il pagamento, il cliente vede un breve messaggio, per esempio Could not connect to Pagar.me. Please try again in a moment., oppure il messaggio di Pagar.me sui dati di fatturazione non validi. Il motivo tecnico viene aggiunto alle note dell'ordine.
Il metodo di pagamento funziona al checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin non include un modulo carta nel checkout, né carte salvate, abbonamenti o pagamenti ricorrenti, né regole di rate, né pagamenti divisi (marketplace), né pagamenti con carta solo autorizzazione, né integrazione con Pagar.me Hub.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a Pagar.me e non ha ancora pagato né emesso un PIX o un boleto. Una nota mostra l'ID dell'ordine Pagar.me e la modalità.
Processing: il pagamento è stato confermato. È lo stato standard di WooCommerce dopo il pagamento; gli ordini con soli prodotti virtuali scaricabili passano a Completed. La nota dell'ordine mostra l'ID dell'ordine Pagar.me e il metodo di pagamento. L'ID di transazione è l'ID dell'ordine Pagar.me (or_...).
On hold: è stato emesso un PIX o un boleto (oppure un pagamento con carta è in analisi) e attende il pagamento; oppure il boleto è stato pagato solo in parte; oppure l'importo o la valuta pagati non corrispondono all'ordine; oppure un pagamento è arrivato dopo l'annullamento dell'ordine; oppure l'ordine è stato pagato su Pagar.me dopo che il cliente aveva cambiato metodo di pagamento; oppure è stata aperta una contestazione (chargeback) su un ordine pagato. La nota dell'ordine lo spiega. Controlla l'ordine e impostalo su Processing, oppure rimborsa il pagamento su Pagar.me.
Failed: il pagamento non è riuscito, oppure l'ordine Pagar.me è stato annullato o è scaduto (per esempio un boleto non pagato). Solo l'ultimo tentativo di un ordine non pagato può farlo passare a Failed. Il cliente può pagare di nuovo.
Refunded: il pagamento è stato rimborsato o annullato in Pagar.me.
Ogni stato di Pagar.me viene applicato una sola volta, quindi webhook o ritorni ripetuti non aggiungono note, e-mail o riduzioni di scorta. Un ordine pagato non torna mai in attesa o fallito, e un ordine annullato o rimborsato non viene mai riaperto. Se viene pagato un secondo ordine Pagar.me dello stesso ordine WooCommerce, una nota ti chiede di rimborsare il duplicato dalla dashboard di Pagar.me.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Pagar.me (il pulsante riporta il titolo del tuo metodo di pagamento). Sono supportati rimborsi totali e parziali di pagamenti con carta e PIX, fino all'importo ancora rimborsabile su Pagar.me. Il rimborso viene inviato con la chiave della modalità in cui è stato effettuato il pagamento. Un rimborso viene registrato solo quando Pagar.me lo conferma; altrimenti WooCommerce mostra l'errore, per esempio Pagar.me refused the refund: ... oppure Pagar.me did not confirm the refund, e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID dell'addebito.
I pagamenti con boleto possono essere rimborsati solo sul conto bancario del cliente. Rimborsali nella dashboard di Pagar.me, poi registra il rimborso manualmente in WooCommerce, senza usare Refund via Pagar.me.
Un rimborso totale o un annullamento effettuato nella dashboard di Pagar.me arriva tramite webhook e imposta l'ordine su Refunded. Una contestazione aggiunge una nota e mette in sospeso un ordine Processing o Completed (On hold).
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Pagar.me. 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 il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, Pagar.me non viene mostrato ai clienti al checkout. Se un pagamento viene comunque avviato, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio con accesso 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 sono interessati: i pagamenti già avviati continuano a essere 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
Pagar.me non compare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo, che la chiave segreta della modalità attuale sia impostata (Test secret key in modalità test, Live secret key in modalità live) e che la valuta del negozio sia BRL. La pagina delle impostazioni mostra un avviso in ciascuno di questi casi.
Il pagamento è andato a buon fine, ma l'ordine resta Pending payment o On hold: il webhook non funziona. Nella dashboard di Pagar.me controlla che il webhook esista per l'account e la modalità che usi, che il suo URL sia esattamente quello mostrato nelle impostazioni e che siano selezionati gli eventi elencati sopra. L'ordine viene controllato anche quando il cliente torna al negozio.
Il webhook risponde verification failed, retry later: il negozio non è riuscito a leggere l'ordine Pagar.me dalla API, per esempio perché manca la chiave di quella modalità o la API non ha risposto. Pagar.me riprova il webhook.
Il webhook risponde busy, retry later: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. Pagar.me riprova il webhook.
Il webhook risponde unknown order: l'ordine Pagar.me non è stato creato da questo negozio, per esempio un ordine di un altro negozio dello stesso account. Non viene modificato nulla.
Il cliente vede This order is already being processed: un webhook o il ritorno del cliente stava aggiornando l'ordine nello stesso momento. Il cliente può riprovare dopo un momento.
Il cliente vede Pagar.me payments are not available right now: la chiave segreta è errata o mancante. Controlla la chiave della modalità attuale.
Il cliente vede Pagar.me could not start the payment: Pagar.me ha rifiutato i dati di fatturazione. Il messaggio indica il problema; il motivo completo è nelle note dell'ordine.
Il cliente vede Pagar.me only supports payments in Brazilian Real (BRL): l'ordine è in un'altra valuta, per esempio a causa di un plugin di cambio valuta.
Ordine On hold dopo il pagamento: leggi la nota dell'ordine. Un PIX o un boleto attende il pagamento, l'importo o la valuta pagati erano diversi, oppure il pagamento è arrivato dopo l'annullamento dell'ordine.
Il rimborso di un boleto non riesce: i pagamenti con boleto non possono essere rimborsati tramite API. Rimborsa nella dashboard di Pagar.me e registra il rimborso manualmente.
Il blocco 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 dalla pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i log del plugin vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le loro note di pagamento, gli ID di transazione e i dati di Pagar.me.
Pagar.me è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Pagar.me né approvato da Pagar.me.