VibeFox Pagar.me for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato con la versione 3.0.5.0) o 4.0.2 e successive (testato con la versione 4.1.0.3).

PHP: 8.0 o successiva.

Currency: real brasiliano (BRL). Il negozio deve avere la valuta BRL (System > Localisation > Currencies), e il metodo di pagamento viene mostrato solo quando il cliente effettua il checkout in BRL e il totale dell'ordine è maggiore di zero.

Pagar.me account: 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, sotto Development > Keys. Vengono usate solo le chiavi segrete; la chiave pubblica (pk_...) non è necessaria. Si possono offrire solo i metodi di pagamento attivati nel tuo account Pagar.me.

VibeFox license key: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 wcp_pagarme_gateway-oc3-(versione).ocmod.zip e il pacchetto per OpenCart 4 wcp_pagarme_gateway.ocmod.zip. Installa solo il pacchetto per la tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nel pannello di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file wcp_pagarme_gateway-oc3-(versione).ocmod.zip. L'estensione non contiene modifiche OCMOD, quindi non è necessario aggiornare Extensions > Modifications. In alternativa all'installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo Payments. Trova VibeFox Pagar.me Gateway e fai clic su Install (il pulsante verde +). Il tuo utente amministratore deve avere il permesso di modificare l'elenco delle estensioni di pagamento.

3. Fai clic su Edit (il pulsante con la matita) per aprire la pagina delle impostazioni. Incolla la tua chiave di licenza VibeFox in License key, nel blocco della licenza in cima alla pagina, e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci la chiave segreta di test e, quando andrai 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 fai clic su Save. Effettua pagamenti di prova con Test mode attivo, poi disattivalo per accettare pagamenti reali.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file wcp_pagarme_gateway.ocmod.zip. Non rinominare il file: OpenCart 4 ricava il codice dell'estensione dal nome del file, e un pacchetto rinominato non funziona.

2. Il pacchetto compare nell'elenco delle estensioni installate, nella stessa pagina. Fai clic su Install (il pulsante verde +) accanto ad esso.

3. Vai su Extensions > Extensions e scegli il tipo Payments. Trova VibeFox Pagar.me Gateway, fai clic su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

4. Inserisci la chiave di licenza, le chiavi segrete e il webhook come nei passaggi da 3 a 6 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni. Cambia solo l'URL del webhook (vedi Notifiche di pagamento (webhook)).

Una nuova installazione parte con il metodo di pagamento disattivato e la modalità di test attiva.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Payments > VibeFox Pagar.me Gateway > Edit. Le sezioni sono elencate a sinistra; il pulsante Save sotto l'elenco salva l'intera pagina. Sopra le impostazioni la pagina mostra la modalità corrente: TEST MODE (i pagamenti vengono creati con la chiave segreta di test, senza addebiti reali) oppure LIVE. Ti avvisa quando manca la chiave segreta della modalità corrente (in tal caso il metodo di pagamento non compare al 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. Senza il permesso di modificare l'estensione, la pagina mostra le impostazioni ma non può salvarle.

Al salvataggio, Title non può essere vuoto (fino a 128 caratteri), Boleto due in (days) deve essere un numero intero da 1 a 30, Sort Order deve essere un numero intero (sono ammessi numeri negativi), Total deve essere un numero pari o maggiore di 0, e la zona geografica e gli stati dell'ordine devono esistere. Se un valore è errato, un messaggio lo indica e non viene salvato nulla.

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 i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Pagar.me. Obbligatorio, fino a 128 caratteri.

Description: il testo mostrato al cliente nel passaggio Confirm Order, sopra il pulsante di conferma. Predefinito: Paga in modo sicuro tramite Pagar.me (carta di credito, PIX o boleto). Verrai reindirizzato per completare il pagamento.

Sort Order: la posizione di Pagar.me tra i metodi di pagamento al checkout. Lascia il campo vuoto oppure inserisci un numero intero.

Geo Zone: offri Pagar.me solo per gli indirizzi di pagamento nella zona geografica selezionata. Predefinito: All zones. Le zone geografiche si configurano in System > Localisation > Geo Zones. In OpenCart 4, se il negozio non chiede alcun indirizzo di pagamento, viene usato l'indirizzo di spedizione.

Total: il totale del checkout, nella valuta predefinita del negozio, che un ordine deve raggiungere prima che venga offerto Pagar.me. Lascia il campo vuoto per offrire Pagar.me per qualsiasi totale.

Chiavi API

Copia le chiavi segrete dalla dashboard di Pagar.me (la sezione contiene un collegamento): Development > Keys. Pagar.me usa un unico indirizzo API per i pagamenti di test e live; è la chiave a stabilire se un pagamento è di test o reale.

Test mode: usa la chiave segreta di test, senza addebiti reali. Quando è attiva, i clienti vedono TEST MODE — Use test credentials. No real charges. nel passaggio Confirm Order. Le verifiche di stato e i rimborsi di un ordine usano sempre la chiave della modalità in cui è stato creato il suo pagamento. Predefinito: attiva.

Test secret key: la chiave segreta di test di Pagar.me (sk_test_...). Viene usata quando la modalità di test è attiva.

Live secret key: la chiave segreta live di Pagar.me (sk_...). Viene usata quando la modalità di 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 cambiarlo. Per rimuovere una chiave salvata, spunta Clear the saved key on save sotto il campo e fai clic su Save.

Pagina di pagamento

I metodi offerti nella pagina di pagamento di Pagar.me, ognuno con il proprio interruttore. Scegli solo metodi attivati nel tuo account Pagar.me. Se non ne è selezionato nessuno, vengono offerti carta di credito, PIX e boleto. Predefinito: carta di credito, PIX e boleto.

Boleto due in (days): il numero di giorni alla scadenza del boleto, da 1 a 30. 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. In OpenCart 3 ha la forma https://your-store/index.php?route=extension/payment/wcp_pagarme_gateway/webhook, in OpenCart 4 la forma https://your-store/index.php?route=extension/wcp_pagarme_gateway/payment/wcp_pagarme_gateway.webhook. È costruito a partire dall'indirizzo della vetrina della tua installazione di OpenCart. Copialo esattamente come viene mostrato nelle impostazioni. L'URL deve essere raggiungibile da Internet.

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 preleva solo l'ID dell'ordine Pagar.me e legge quell'ordine dall'API di Pagar.me con la chiave della modalità in cui è stato creato. Le notifiche relative a ordini Pagar.me non creati da questo negozio vengono ignorate. Senza il webhook, i pagamenti PIX e boleto effettuati in seguito vengono confermati solo quando il cliente torna nel negozio.

Ordini

OpenCart crea l'ordine nel passaggio Confirm Order senza stato (un ordine mancante, missing order). L'ordine riceve uno stato solo dopo che Pagar.me ha segnalato il pagamento tramite webhook o al ritorno del cliente; l'ordine Pagar.me viene sempre riletto dall'API. Ogni campo qui sotto elenca gli stati ordine del tuo OpenCart.

Order Status After Payment: lo stato impostato dopo un pagamento Pagar.me verificato. Predefinito: In lavorazione.

Awaiting Pagar.me Payment Status: è stato emesso un codice PIX o un boleto, oppure un pagamento con carta è in analisi; Pagar.me conferma poi il denaro. Predefinito: In attesa.

Pagar.me Payment On Hold Status: il pagamento richiede una tua verifica (vedi Stati dell'ordine). Predefinito: In attesa, perché OpenCart non ha uno stato In sospeso. Puoi creare un tuo stato in System > Localisation > Order Statuses e selezionarlo qui.

Payment Failed Status: il pagamento di un ordine in attesa non è riuscito, è stato annullato o è scaduto. Se Pagar.me lo segnala poi come pagato, l'ordine riceve lo stato dopo il pagamento. Predefinito: Non riuscito.

Cancelled Order Status: lo stato che il tuo negozio usa per gli ordini annullati. L'estensione non lo imposta: un pagamento Pagar.me che arriva dopo porta l'ordine nello stato di verifica. Predefinito: Annullato.

Refunded Status: impostato dopo il rimborso totale del pagamento dalla pagina dell'ordine o nella dashboard di Pagar.me. Predefinito: Rimborsato.

Avanzate

Debug log: scrive richieste API e notifiche nel file wc_pgm_debug.log.php, nella cartella dei log di OpenCart (storage/logs). Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati. Chiavi e dati dei clienti (e-mail, telefono, CPF) non vengono 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 dell'estensione rimuove le impostazioni del gateway e il log. Gli ordini e i loro dati di pagamento Pagar.me (necessari per i rimborsi) vengono sempre conservati. Predefinito: disattivato.

Importa / Esporta

Export: Download JSON salva le impostazioni in un file JSON. Le chiavi segrete non vengono esportate.

Import: incolla un JSON esportato in precedenza e fai clic su Import per ripristinare le impostazioni. Le chiavi segrete salvate vengono mantenute.

Checkout

Nel passaggio Payment Method il cliente sceglie il metodo di pagamento (per impostazione predefinita Pagar.me). Nel passaggio Confirm Order il cliente vede la tua descrizione e la nota You will be redirected to the Pagar.me payment page to pay by credit card, PIX, boleto or debit card. OpenCart crea l'ordine in questo passaggio, ancora senza stato. Su OpenCart 4 il cliente sceglie il metodo di pagamento con il pulsante Choose del blocco del metodo di pagamento, nella finestra Payment method options, e fa clic su Confirm Order in fondo alla pagina di checkout. Quando il cliente fa clic su Confirm Order, l'estensione crea un ordine Pagar.me per il totale dell'ordine in BRL e invia il cliente alla pagina di pagamento di Pagar.me. Le righe dell'ordine con tasse, spedizione e altri supplementi vengono inviate come articoli; quando l'ordine ha uno sconto (coupon, buono, punti premio) o le righe non corrispondono al totale, per l'intero importo viene inviata una riga Order # con il numero dell'ordine. È richiesto un indirizzo e-mail valido.

Il nome e l'e-mail del cliente vengono passati a Pagar.me. Il CPF o il CNPJ (11 o 14 cifre) viene preso da un campo personalizzato del cliente o dell'indirizzo di pagamento il cui nome contiene CPF o CNPJ; OpenCart non ha un campo del genere per impostazione predefinita, quindi aggiungilo in Customers > Custom Fields se vuoi passarlo. Su OpenCart 4, se il negozio non chiede alcun indirizzo di pagamento, vengono usati l'indirizzo di spedizione e i suoi campi personalizzati. Viene passato anche un numero di cellulare brasiliano. L'indirizzo di fatturazione viene passato solo per un indirizzo brasiliano con un CEP di 8 cifre e uno stato. Senza CPF o CNPJ il cliente lo inserisce nella pagina di Pagar.me.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Pagar.me: il negozio legge l'ordine Pagar.me dall'API, e l'importo pagato e la valuta devono corrispondere all'ordine. L'ordine riceve quindi il suo stato nel modo standard di OpenCart, con le consuete e-mail d'ordine e l'aggiornamento del magazzino, e il cliente vede la pagina di successo dell'ordine di OpenCart. Un PIX o un boleto emesso ma non ancora pagato porta l'ordine nello stato di attesa, e la pagina mostra anche Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. Per un ordine nello stato di verifica mostra We are confirming your payment with Pagar.me. The order will be updated automatically — please do not pay again. 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 cliente torna senza aver pagato, si ritrova al checkout con The Pagar.me payment was not completed. You can try again or choose another payment method. Se il pagamento è stato rifiutato o annullato, il messaggio è The Pagar.me payment was declined or canceled. You can try again or choose another payment method. Il carrello viene mantenuto. Su OpenCart 4 questi messaggi vengono mostrati sopra la pagina di checkout. Se l'ordine ha già uno stato e il suo pagamento non è riuscito 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 il carrello è già vuoto (per esempio, l'ordine aveva raggiunto la pagina di successo prima che scadesse il suo PIX o boleto), al checkout non c'è nulla da pagare: una pagina Payment confirmation dice The Pagar.me payment of order #N was not completed (declined, canceled or expired), so the order will not be shipped. To buy these items, please place a new order. con un pulsante Continue. 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.

OpenCart 3 crea un nuovo ordine ogni volta che viene mostrato il passaggio Confirm Order. OpenCart 4 mantiene un solo ordine per il checkout e lo aggiorna, quindi dopo un pagamento non completato o rifiutato il cliente paga di nuovo lo stesso ordine.Prima di un nuovo pagamento, l'estensione controlla i tentativi precedenti dello stesso carrello: se uno è pagato, o se il suo PIX o boleto è in attesa, il cliente va alla pagina di successo senza un nuovo pagamento. Una pagina di pagamento Pagar.me ancora aperta dello stesso ordine viene riutilizzata se importo e modalità coincidono; le altre pagine aperte vengono prima chiuse su Pagar.me. Se un secondo ordine Pagar.me del carrello viene comunque pagato, non viene applicato, e una nota sull'ordine pagato ti chiede di rimborsare il duplicato.

Su OpenCart 4 l'ordine resta nel checkout fino alla visualizzazione della pagina di successo. Se nel frattempo quell'ordine è stato chiuso (per esempio perché il suo PIX o boleto è scaduto, il pagamento non è riuscito o l'hai annullato o rimborsato), Confirm Order rimanda il cliente al checkout con Your previous order was cancelled or its payment failed. Please confirm the order again., oppure, se l'ordine era stato pagato prima che tu lo chiudessi, con This order was closed by the store, so it will not be shipped. Your cart is kept: confirm the order again to pay. Il successivo Confirm Order paga un nuovo ordine. Quando il cliente torna da Pagar.me a un ordine che era stato pagato e poi chiuso da te, vede lo stesso messaggio nel checkout oppure, se il carrello è già vuoto, una pagina con Order #(numero) was closed by the store, so it will not be shipped. To buy these items, please place a new order. Se l'ordine del checkout ha già uno stato e il carrello ora contiene altri prodotti o quantità, il cliente torna al checkout e il nuovo carrello riceve un nuovo ordine.

Se Pagar.me non riesce ad avviare il pagamento, il cliente resta nel passaggio Confirm Order con un breve messaggio, per 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 log.

Il webhook funziona anche quando il negozio è in modalità manutenzione: OpenCart 3 lascia passare le richieste delle estensioni di pagamento, e su OpenCart 4 l'estensione aggiunge un'azione di avvio che lascia passare il webhook e il ritorno del cliente da Pagar.me.

L'estensione non ha un modulo carta nel tuo checkout, né carte salvate, abbonamenti o pagamenti ricorrenti, né regole di rateizzazione, né pagamenti divisi (marketplace) né pagamenti con carta solo autorizzazione.

Ordini e rimborsi

Stati dell'ordine

No status (missing order): il cliente è stato inviato a Pagar.me e non ha ancora pagato né emesso un PIX o un boleto, oppure il pagamento è stato rifiutato. In Sales > Orders questi ordini vengono mostrati solo con il filtro Order Status impostato su Missing Orders.

Su OpenCart 4 un ordine non pagato del checkout può ricevere lo stato Voided, che OpenCart 4 imposta quando il cliente torna al passaggio Confirm Order. L'estensione considera un ordine del genere un ordine senza stato, e un pagamento successivo lo conferma comunque.

Order Status After Payment (default Processing): il pagamento è stato confermato. Una nota mostra l'ID dell'ordine Pagar.me (or_...) e il metodo di pagamento.

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

Pagar.me Payment On Hold Status (default Pending): il boleto è stato pagato solo in parte; oppure l'importo o la valuta pagati non corrispondono all'ordine; oppure il pagamento è arrivato dopo che l'ordine era stato annullato o rimborsato; oppure è stata aperta una contestazione (chargeback) su un ordine pagato. La nota lo spiega. Controlla l'ordine e completalo oppure rimborsa il pagamento.

Payment Failed Status (default Failed): il pagamento di un ordine in attesa o sospeso non è riuscito, oppure il suo ordine Pagar.me è stato annullato o è scaduto (per esempio un boleto non pagato). Se Pagar.me segnala poi un pagamento, l'ordine passa comunque a Order Status After Payment.

Refunded Status (default Refunded): il pagamento è stato rimborsato interamente tramite l'estensione, oppure rimborsato o annullato in Pagar.me.

Ogni stato Pagar.me viene applicato una sola volta, quindi webhook ripetuti o ritorni non aggiungono note né pagamenti. Le note sono voci della History dell'ordine che il cliente non vede.

Scheda VibeFox Pagar.me Gateway

In Sales > Orders apri un ordine pagato con Pagar.me. In fondo alla pagina dell'ordine, accanto a History e Additional, la scheda VibeFox Pagar.me Gateway mostra l'ID del Pagar.me order con l'etichetta Test mode per i pagamenti di test, il Payment method, lo Status, gli importi Paid / refunded, il modulo di rimborso, lo storico dei rimborsi e le Pagar.me notes dell'ordine. La scheda viene mostrata agli utenti che hanno accesso all'estensione.

Rimborsi

Nella scheda VibeFox Pagar.me Gateway inserisci l'Amount (viene compilato l'importo non ancora rimborsato), facoltativamente un Reason (optional), e fai clic 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. Ti serve il permesso di modificare l'estensione (impostato in System > Users > User Groups). Puoi rimborsare fino all'importo che Pagar.me ha effettivamente incassato, quindi dopo una discrepanza 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; in caso contrario la scheda 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 allo storico dei rimborsi e alle note con l'ID dell'addebito. Un rimborso totale porta l'ordine allo stato Refunded Status senza avvisare il cliente e senza riportare i prodotti in magazzino, come una modifica manuale dello stato. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili una volta 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 OpenCart. I resi di prodotti in Sales > Returns non restituiscono denaro tramite Pagar.me.

Un rimborso totale o un annullamento effettuato nella dashboard di Pagar.me arriva tramite webhook, porta l'ordine allo stato Refunded Status e aggiunge una nota. Una contestazione aggiunge una nota e porta un ordine pagato nello stato di verifica.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco di licenza License — VibeFox Pagar.me Gateway è il primo blocco di Extensions > Extensions > Payments > VibeFox Pagar.me Gateway > Edit, sopra le impostazioni. Incolla la chiave in License key e fai clic su Activate. Dopodiché 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 verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto si trovano la riga Product: opencart-payment-pagarme e il collegamento Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso di modifica dell'estensione possono cambiare la chiave. I testi del blocco seguono la lingua del pannello di amministrazione (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 risponde, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio 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 avviato comunque, il cliente vede This payment method is not available. Please choose another one. Un utente amministratore connesso al pannello di amministrazione nello stesso browser vede ancora il metodo di pagamento nel negozio, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e testare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso al pannello di amministrazione, quindi senza una chiave attiva il metodo di pagamento è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard del pannello di amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente quando apri la Dashboard o la pagina Edit del pannello di amministrazione: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Pagar.me does not appear at checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo, che la chiave segreta della modalità corrente sia impostata (Test secret key in modalità di test, Live secret key in modalità live) e che il cliente effettui il checkout in BRL. La pagina delle impostazioni mostra un avviso quando la chiave manca. Verifica anche che l'indirizzo di pagamento sia nella Geo Zone selezionata e che l'ordine raggiunga il Total impostato nelle impostazioni.

The payment went through, but the order stays without a status or in the awaiting status: 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 nel negozio.

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

The webhook answers busy: il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure non è stato possibile impostare lo stato dell'ordine. Pagar.me riprova il webhook. Attiva Debug log per vedere il motivo.

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

The webhook answers invalid payload or invalid order id: la richiesta non è una notifica di Pagar.me. Non viene modificato nulla.

The customer sees Pagar.me payments are not available right now: la chiave segreta è errata o manca. Verifica la chiave della modalità corrente.

The customer sees Pagar.me could not start the payment: Pagar.me ha rifiutato i dati di fatturazione, per esempio il CPF nel campo personalizzato. Il messaggio indica il problema; il motivo completo è nel log.

The customer sees A valid billing email is required for Pagar.me.: l'e-mail dell'ordine non è valida.

The customer sees Pagar.me only supports payments in Brazilian Real (BRL).: il checkout è in un'altra valuta.

The customer sees 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 log.

Order is in the review status after payment: leggi le note nella scheda VibeFox Pagar.me Gateway (vedi Stati dell'ordine), poi completa l'ordine o rimborsa il pagamento.

No refund form in the tab: la scheda indica il motivo: il pagamento non è ancora segnalato, è rimborsato interamente, il tuo gruppo utenti non ha il permesso di modificare l'estensione, oppure la chiave segreta della modalità del pagamento non è impostata.

Refund fails for a boleto: i pagamenti con boleto non possono essere rimborsati tramite API. Rimborsa nella dashboard di Pagar.me e registra il rimborso manualmente.

Per gli sviluppatori: prima dell'invio dell'ordine Pagar.me, l'estensione attiva l'evento OpenCart wc_pgm_order_data con il corpo della richiesta e l'ordine. L'importo del pagamento deve restare uguale al totale dell'ordine.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Payments e fai clic su Uninstall (il pulsante rosso −) accanto a VibeFox Pagar.me Gateway. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart rimuove sempre le proprie impostazioni dell'estensione: Enable / Disable, Sort Order, Geo Zone, Total e gli stati degli ordini della sezione Orders, che tornano ai valori predefiniti in una reinstallazione. Viene rimosso anche l'evento OpenCart dell'estensione (su OpenCart 4 i suoi eventi e la sua azione di avvio, che lascia passare il webhook e il ritorno del cliente in modalità manutenzione). Se Delete data on uninstall è attivo, vengono rimosse le altre impostazioni del gateway (titolo, descrizione, modalità di test, chiavi segrete, metodi di pagamento, giorni del boleto, registrazione) e il log. Se è disattivo, vengono conservate per una reinstallazione successiva. I registri dei pagamenti e dei rimborsi Pagar.me vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento.

Su OpenCart 4, per rimuovere anche i file dell'estensione, dopo la disinstallazione vai su Extensions > Installer e fai clic su Uninstall (il pulsante arancione −) accanto a VibeFox Pagar.me Gateway nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

Pagar.me è un marchio del rispettivo titolare. Questa estensione non è affiliata né approvata da Pagar.me.