VibeFox Pagar.me for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo rifiuta di installarsi su versioni di PHP più vecchie.

Valuta: real brasiliano (BRL). Il metodo di pagamento è nascosto per i carrelli in qualsiasi altra valuta.

Account Pagar.me: ti servono le chiavi segrete del tuo account Pagar.me: la chiave di test (sk_test_...) e, per andare in produzione, la chiave live (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: si acquista su vibefox.net. Una chiave funziona su un 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 Pagar.me Gateway nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in alto nella pagina Configure, e clicca su Activate (vedi Chiave di licenza).

4. Inserisci la chiave segreta di test e, quando vai in produzione, la chiave segreta live.

5. Crea il webhook nella dashboard di Pagar.me con l'URL mostrato nelle impostazioni (vedi Configurazione).

6. Attiva Enable / Disable e clicca su Save. Effettua pagamenti di prova con Test mode attivo, poi disattivalo per accettare pagamenti reali.

All'installazione il modulo crea due stati dell'ordine: Awaiting Pagar.me payment e Pagar.me payment on hold. PrestaShop aggiunge un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Pagar.me Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi 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 nel checkout), quando la chiave di test non inizia con sk_test_, quando la chiave live non inizia con sk_ o è una chiave di test, e quando la valuta predefinita del negozio non è BRL.

Pagar.me

Enable / Disable: Enable Pagar.me payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede nel checkout. È anche il nome del metodo di pagamento memorizzato nell'ordine. Predefinito: Pagar.me. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento nel 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 quelli reali; la chiave stabilisce se un pagamento è di test o reale.

Test mode: usa la chiave segreta di test, senza addebiti reali. Finché è attivo, i clienti vedono sotto il metodo di pagamento TEST MODE — Use test credentials. No real charges.. 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 finché la modalità test è attiva.

Live secret key: la chiave segreta live di Pagar.me (sk_...). Viene usata quando la modalità test è disattivata. Tienila riservata.

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

Clear saved secret keys: seleziona una chiave e clicca su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Pagina di pagamento

Payment methods: i metodi offerti nella pagina di pagamento di Pagar.me. Scegli solo metodi abilitati nel tuo account Pagar.me. Se nessuno è selezionato, vengono usati i metodi predefiniti. Predefinito: Credit card, PIX and Boleto.

Boleto due in (days): il numero di giorni alla scadenza del boleto, da 1 a 30. L'ordine resta in Awaiting Pagar.me payment finché Pagar.me non conferma il pagamento. Predefinito: 3. Un altro valore viene rifiutato al salvataggio con Boleto due in (days): enter a number from 1 to 30.

Notifiche di pagamento (webhook)

Nella dashboard di Pagar.me apri Settings > Webhooks e crea un webhook con l'URL mostrato in Webhook URL in questa sezione. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_pagarme_gateway/webhook, eventualmente con un codice lingua come /en/. Copialo esattamente come lo mostrano le impostazioni.

Seleziona questi eventi (sono elencati anche in questa sezione):

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 agli ordini di altri negozi sullo stesso account Pagar.me vengono ignorate. Senza webhook, i pagamenti PIX e boleto effettuati più tardi vengono confermati solo quando il cliente torna al negozio.

Avanzate

Debug log: registra le richieste API e le notifiche in logs/wc_pgm_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati. Chiavi e dati dei clienti non vengono registrati. Predefinito: disattivato.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il registro. Gli ordini, i loro dati di pagamento Pagar.me (necessari per i rimborsi) e gli stati dell'ordine vengono conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Pagar.me) e conferma. È richiesto un indirizzo e-mail valido. Il modulo crea un ordine Pagar.me per il totale del carrello in BRL, con le righe del carrello, la spedizione e la confezione regalo (oppure una sola riga Order # con il numero del carrello, quando il carrello ha sconti), e invia il cliente alla pagina di pagamento di Pagar.me. A questo punto nel tuo negozio non esiste ancora alcun ordine.

Nome e e-mail del cliente vengono passati a Pagar.me. Il CPF o il CNPJ viene preso dal campo Identification number dell'indirizzo, oppure da VAT number; viene passato anche un numero di cellulare brasiliano. L'indirizzo di fatturazione viene passato solo per un indirizzo brasiliano con CEP di 8 cifre e uno stato. PrestaShop non ha di default gli stati brasiliani, quindi il cliente di solito inserisce l'indirizzo nella pagina di Pagar.me. Senza CPF o CNPJ il cliente lo inserisce anche lì.

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 pagato e la valuta devono corrispondere al carrello. Un pagamento con carta, PIX o boleto andato a buon fine crea l'ordine in Payment accepted, e il cliente vede la pagina standard di conferma dell'ordine con Your payment with Pagar.me has been received. Un PIX o un boleto emesso ma non ancora pagato crea l'ordine in Awaiting Pagar.me payment, e la pagina mostra Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. Ogni ritorno successivo rilegge l'ordine Pagar.me, quindi un PIX o un boleto pagato nel frattempo viene applicato anche se il webhook non è arrivato. Se il pagamento di un ordine del genere è fallito o è scaduto, la pagina mostra Your Pagar.me payment was not completed. Please contact us about this order.

Se il cliente torna senza aver pagato, si ritrova nel checkout con il messaggio The Pagar.me payment was not completed. You can pay the order below. Se il pagamento è stato rifiutato o annullato, il messaggio è The Pagar.me payment was declined or canceled. You can try again below. Il carrello viene conservato. Se l'ordine esiste già e il suo pagamento è fallito o è scaduto, il messaggio è The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. Se Pagar.me non è raggiungibile, una pagina Payment confirmation chiede al cliente di non pagare di nuovo e offre Check again e Back to checkout.

Quando il cliente paga di nuovo, la pagina di pagamento Pagar.me aperta viene riutilizzata se importo e modalità sono gli stessi; altrimenti viene chiusa su Pagar.me prima che ne venga creata una nuova. Se il tentativo precedente è stato pagato nel frattempo, oppure il suo PIX o boleto è ancora in attesa, l'ordine viene creato senza un nuovo pagamento. Se la pagina precedente non può essere chiusa, resta associata al carrello, quindi un pagamento effettuato lì viene comunque registrato.

Se Pagar.me non riesce ad avviare il pagamento, il cliente resta nel checkout con un breve messaggio, ad esempio Could not connect to Pagar.me. Please try again in a moment., oppure con il messaggio di Pagar.me sui dati di fatturazione non validi. Il motivo tecnico viene scritto nel registro.

Il webhook funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo 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

No order yet: il cliente è stato inviato a Pagar.me e non ha ancora pagato né emesso un PIX o un boleto. Esiste solo il carrello.

Payment accepted: il pagamento è stato confermato. Il pagamento viene registrato con l'ID dell'ordine Pagar.me (or_...) come ID della transazione, e una nota mostra l'ordine Pagar.me e il metodo di pagamento.

Awaiting Pagar.me payment: è stato emesso un PIX o un boleto (oppure un pagamento con carta è in analisi) e attende il pagamento. L'ordine passa a Payment accepted quando Pagar.me conferma il pagamento.

Pagar.me payment on hold: il boleto è stato pagato solo in parte; oppure l'importo pagato o la valuta non corrispondono all'ordine (ad esempio, il carrello è stato modificato dopo l'avvio del pagamento); oppure il pagamento è arrivato dopo che l'ordine era stato annullato; oppure è stata aperta una contestazione su un ordine pagato. La nota lo spiega. Controlla l'ordine ed evadilo oppure rimborsa il pagamento.

Payment error: il pagamento di un ordine in attesa o sospeso è fallito, oppure il suo ordine Pagar.me è stato annullato o è scaduto (ad esempio un boleto non pagato). Se Pagar.me segnala un pagamento più tardi, l'ordine passa comunque a Payment accepted.

Refunded: il pagamento è stato rimborsato interamente tramite il modulo, oppure rimborsato o annullato su Pagar.me.

Ogni stato Pagar.me viene applicato una sola volta, quindi webhook o ritorni ripetuti non aggiungono note né pagamenti. Se viene pagato un secondo ordine Pagar.me dello stesso carrello, una nota ti chiede di rimborsare il duplicato nella dashboard di Pagar.me.

Blocco di pagamento Pagar.me

La pagina dell'ordine mostra un blocco Pagar.me payment con l'ID dell'ordine Pagar.me e gli ID degli addebiti, il metodo di pagamento, lo stato, l'importo pagato e rimborsato, un badge Test mode per i pagamenti di test, lo storico dei rimborsi e le Pagar.me notes dell'ordine.

Rimborsi

Nel blocco Pagar.me payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Pagar.me. Conferma la domanda Refund this amount through Pagar.me? This cannot be undone. Sono supportati rimborsi totali e parziali di pagamenti con carta e PIX. Devi avere il permesso di modificare gli ordini. Puoi rimborsare fino all'importo effettivamente incassato da Pagar.me, quindi dopo una differenza di importo il limite è quanto ha pagato il cliente, non il totale dell'ordine. Il rimborso viene inviato con la chiave della modalità in cui è stato effettuato il pagamento, quindi la chiave segreta di quella modalità deve essere impostata. Un rimborso viene registrato solo quando Pagar.me lo conferma; altrimenti il blocco mostra l'errore, ad esempio Pagar.me refused the refund: ... oppure Pagar.me did not confirm the refund, e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con l'ID dell'addebito. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili dopo che Pagar.me ha segnalato il pagamento.

I pagamenti con boleto possono essere rimborsati solo sul conto bancario del cliente. Rimborsali nella dashboard di Pagar.me, poi registra manualmente il rimborso in PrestaShop.

Il modulo non crea note di credito (credit slip). I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Pagar.me.

Un rimborso totale o un annullamento effettuato nella dashboard di Pagar.me arriva tramite webhook, imposta l'ordine su Refunded e aggiunge una nota. Una contestazione aggiunge una nota e mette un ordine pagato in Pagar.me payment on hold.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Pagar.me Gateway è il primo blocco della pagina Modules > Module Manager > VibeFox Pagar.me Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca 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-pagarme 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, 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 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, Pagar.me non viene mostrato ai clienti nel 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 nel 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

Pagar.me non compare nel 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 carrello sia BRL. La pagina delle impostazioni mostra un avviso quando la chiave manca. 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 oppure l'ordine resta in Awaiting Pagar.me payment: il webhook non funziona. Nella dashboard di Pagar.me verifica che il webhook esista per l'account e la modalità che usi, che il suo URL sia esattamente quello mostrato in Webhook URL e che gli eventi elencati sopra siano selezionati. L'ordine viene controllato anche ogni volta che il cliente torna al negozio.

Il webhook risponde verification failed, retry later: il negozio non è riuscito a leggere l'ordine Pagar.me dalla API, ad esempio perché manca la chiave di quella modalità o la API non ha risposto. Pagar.me riprova il webhook.

Il webhook risponde busy: il carrello era in aggiornamento da un'altra richiesta nello stesso momento, oppure l'ordine non è stato creato (ad esempio il modulo è disattivato). Pagar.me riprova il webhook. Attiva Debug log per vedere il motivo.

Il webhook risponde unknown order: l'ordine Pagar.me non è stato creato da questo negozio, ad esempio un ordine di un altro negozio sullo stesso account. Non viene modificato nulla.

Il cliente vede Pagar.me payments are not available right now: la chiave segreta è sbagliata o manca. Verifica la chiave della modalità attuale.

Il cliente vede Pagar.me could not start the payment: Pagar.me ha rifiutato i dati di fatturazione, ad esempio il CPF nel campo Identification number dell'indirizzo. Il messaggio indica il problema; il motivo completo è nel registro.

Il cliente vede Pagar.me only supports payments in Brazilian Real (BRL): il carrello è in un'altra valuta.

Il cliente vede This order already has a Pagar.me payment that the store has to review: un pagamento precedente del carrello richiede la tua verifica. Controlla la dashboard di Pagar.me e il registro.

L'ordine è in Pagar.me payment on hold dopo il pagamento: leggi le note nel blocco Pagar.me payment (vedi Stati dell'ordine), poi evadi l'ordine oppure rimborsa il pagamento.

Il rimborso fallisce per un boleto: i pagamenti con boleto non possono essere rimborsati tramite API. Rimborsa nella dashboard di Pagar.me e registra il rimborso manualmente.

Il rimborso fallisce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità test o live, e la chiave segreta di quella modalità non è impostata. Inseriscila e riprova.

Gli sviluppatori possono modificare i dati dell'ordine Pagar.me prima dell'invio con l'hook actionWcpPagarmeOrderData.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Pagar.me 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 registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I dati di pagamento Pagar.me degli ordini e gli stati dell'ordine Awaiting Pagar.me payment e Pagar.me payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID delle transazioni.

Pagar.me è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Pagar.me né approvato da Pagar.me.