VibeFox MercadoPago for PrestaShop — Guida
Requisiti
PrestaShop: 8.0–9.x.
PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.
Valuta del negozio: la valuta del paese del tuo account MercadoPago: ARS (Argentina), BRL (Brasile), CLP (Cile), COP (Colombia), MXN (Messico), PEN (Perù) o UYU (Uruguay). MercadoPago addebita nella valuta dell'account e non converte, quindi il metodo di pagamento viene nascosto per un carrello in un'altra valuta.
Account MercadoPago: ti serve un'applicazione nel pannello sviluppatori di MercadoPago (Your integrations > your application > Credentials) con le sue credenziali di test (iniziano con TEST-) e di produzione (iniziano con APP_USR-): una Public Key e un Access Token per ciascuna. Per la verifica facoltativa della firma delle notifiche ti serve anche la firma segreta da your application > Webhooks.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo 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 MercadoPago 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 alto nella pagina Configure, e fai clic su Activate (vedi Chiave di licenza).
4. Scegli l'Account country, inserisci le credenziali di test e di produzione e, se vuoi, configura le notifiche nella tua applicazione MercadoPago (vedi Configurazione).
5. Attiva Enable / Disable e fai clic su Save. Prova un pagamento in modalità test con le carte di test di MercadoPago, poi disattiva Test mode.
All'installazione il modulo crea due stati dell'ordine: Awaiting MercadoPago payment e MercadoPago payment on hold. PrestaShop assegna un nuovo modulo di pagamento ai paesi attivi al momento dell'installazione. Controlla valute, paesi e gruppi di clienti del modulo in Payment > Preferences.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox MercadoPago Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Test mode is on: the TEST- credentials are used and no real money is charged. finché la modalità test è attiva. Avvisa anche quando manca la Public Key o l'Access Token della modalità attuale, quando la valuta del negozio non è quella dell'account MercadoPago (in tal caso il metodo di pagamento è nascosto al checkout) e quando le credenziali appartengono a un account di un paese diverso da Account country.
Al salvataggio, una credenziale che non inizia con il prefisso previsto (TEST- per i campi di test, APP_USR- per quelli di produzione) non viene salvata e compare l'errore must start with … — the previous value was kept.. Il modulo chiede inoltre a MercadoPago a quale paese appartiene ogni Access Token. Se il token della modalità attuale non può essere verificato, se l'account non si trova in un paese supportato o se il paese non corrisponde a Account country, compare un errore. Il modulo usa allora il paese dell'account.
MercadoPago
Enable / Disable: Enable MercadoPago card payments attiva o disattiva il metodo di pagamento. Predefinito: off.
Title: il nome del metodo di pagamento mostrato al cliente al checkout. È anche il nome del metodo salvato nell'ordine. Predefinito: Credit or debit card (MercadoPago). Obbligatorio.
Description: il testo mostrato sopra i campi della carta al checkout. Predefinito: Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.
Account MercadoPago
Ottieni le credenziali della tua applicazione nel pannello sviluppatori di MercadoPago: Your integrations > your application > Credentials. Le credenziali di test iniziano con TEST-, quelle di produzione con APP_USR-.
Account country: il paese del tuo account MercadoPago. Determina la valuta di addebito, la lingua dei campi della carta e se viene chiesto il documento del titolare. La valuta del negozio deve essere la stessa, per esempio ARS per l'Argentina. Al salvataggio delle credenziali il paese viene verificato con l'account. Predefinito: Argentina (ARS).
Test mode: in modalità test vengono usate le credenziali TEST- e paghi con le carte di test di MercadoPago; al checkout compare il badge TEST MODE. Disattivala per addebitare carte reali con le credenziali di produzione. Predefinito: on.
Test Public Key: inizia con TEST-. Usata nel browser per tokenizzare la carta.
Test Access Token: inizia con TEST-. Usato solo sul server. Tienilo segreto.
Production Public Key: inizia con APP_USR-.
Production Access Token: inizia con APP_USR-. Usato solo sul server. Tienilo segreto.
Gli Access Token salvati e il webhook secret non vengono più mostrati. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.
Opzioni di pagamento
Maximum installments: il numero massimo di rate che il cliente può scegliere, da 1 a 24. 1 = solo pagamento in un'unica soluzione, e il campo delle rate non viene mostrato. Il limite è applicato anche sul server. Predefinito: 1.
Notifiche di pagamento (webhook)
I pagamenti con carta di solito ricevono una risposta definitiva subito. I pagamenti che MercadoPago tiene in verifica (in elaborazione o in attesa) vengono completati dalle notifiche di MercadoPago. Il modulo invia l'URL di notifica con ogni pagamento quando il tuo negozio ha un indirizzo pubblico (non localhost né un dominio .local o .test). Puoi anche aggiungerlo in your application > Webhooks, evento Payments. L'URL è mostrato in Notification URL in questa sezione. Con URL parlanti ha questo aspetto: https://your-shop/en/module/wcp_mercadopago_gateway/webhook?source_news=webhooks. Copia l'URL esattamente come lo mostrano le impostazioni.
Una notifica non viene mai considerata attendibile di per sé. Il modulo rilegge il pagamento dalle API di MercadoPago con l'Access Token dell'ambiente in cui è stato effettuato il pagamento e lo associa a un tentativo di pagamento del tuo negozio. Senza notifiche, gli ordini in verifica restano in Awaiting MercadoPago payment finché non li aggiorni a mano.
Il modulo gestisce questi stati di pagamento di MercadoPago:
Webhook secret signature: facoltativo. La firma segreta mostrata in your application > Webhooks. Se è impostata, le notifiche senza una x-signature valida vengono rifiutate (HTTP 401).
Clear saved secrets: spunta Test Access Token, Production Access Token o Webhook secret signature e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.
Avanzate
Debug log: scrive le richieste e le notifiche di MercadoPago in logs/wc_mpg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche con questa impostazione disattivata. Access Token, token delle carte e dati dei pagatori non vengono registrati. Predefinito: off.
Log: mostra la dimensione e gli ultimi inserimenti 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 i log. I record dei pagamenti MercadoPago, i rimborsi e gli stati d'ordine del modulo restano sempre, così gli ordini pagati prima possono essere rimborsati anche dopo una reinstallazione. Predefinito: off.
Checkout
Nel passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit or debit card (MercadoPago)) e compila i campi della carta: Card number, Expiry (MM/YY), Security code e Cardholder name. A seconda del paese e della carta, il cliente sceglie anche Document type e inserisce il Document number, seleziona il Card issuer e il numero di Installments. Le opzioni di rate e gli interessi sono forniti da MercadoPago per il totale del carrello. Il formulario della carta funziona con i temi Classic e Hummingbird.
Quando il cliente conferma, MercadoPago trasforma la carta in un token monouso e il tuo negozio crea il pagamento sul server per il totale del carrello. E-mail e nome del cliente, documento e numero del carrello vengono passati a MercadoPago; il pagamento appare come Cart #, con il numero del carrello e il nome del tuo negozio. Gli importi in CLP e COP vengono addebitati senza decimali. Nessun ordine esiste prima della risposta di MercadoPago.
Un pagamento approvato crea un ordine pagato e il cliente vede la pagina di conferma dell'ordine con Your card payment has been received. Un pagamento in verifica crea un ordine in Awaiting MercadoPago payment, e la pagina mostra MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. Se un pagamento in verifica viene rifiutato in seguito, la pagina mostra Your MercadoPago payment was not completed. Please contact us about this order. Un ordine sospeso mostra Your payment is being reviewed. We will update your order as soon as the review is complete.
Una carta rifiutata non crea alcun ordine. Il cliente resta nel passaggio del pagamento con un motivo breve, per esempio Your card has insufficient funds. Please use another card or payment method. oppure Please check the security code of your card. Il cliente può correggere i dati o usare un'altra carta; a ogni tentativo viene creato un nuovo token.
Se MercadoPago non risponde, il cliente vede We could not confirm your payment with MercadoPago. Please wait a minute before trying again — if the payment went through, your order will be updated automatically. Il tentativo successivo cerca prima il pagamento, quindi la carta non viene addebitata due volte. Un secondo clic mentre il carrello viene pagato mostra This order is already being paid. Please wait a moment and check your e-mail before trying again. Un carrello che ha già un ordine non viene mai addebitato di nuovo; il cliente viene inviato alla pagina di conferma di quell'ordine.
L'URL di notifica funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.
Il modulo accetta solo carte di credito e di debito. Non prevede il reindirizzamento a Checkout Pro, il wallet o il saldo di MercadoPago, né pagamenti in contanti (Rapipago, OXXO, boleto e altri), Pix, PSE o Yape, né carte salvate o abbonamenti, nessuna autorizzazione e cattura separate, nessuna verifica 3-D Secure e nessuna conversione di valuta.
Ordini e rimborsi
Stati dell'ordine
No order: la carta è stata rifiutata, oppure MercadoPago non ha ancora risposto. Esiste solo il carrello.
Payment accepted: MercadoPago ha approvato il pagamento e importo e valuta coincidono con il carrello. Il pagamento viene registrato con l'ID del pagamento MercadoPago come ID transazione, e una nota mostra l'ID del pagamento, l'ambiente e il numero di rate.
Awaiting MercadoPago payment: il pagamento è in verifica (in elaborazione o in attesa) e attende la notifica di MercadoPago. L'ordine passa a Payment accepted quando MercadoPago lo approva.
MercadoPago payment on hold: l'importo o la valuta approvati differiscono dal carrello, oppure MercadoPago ha restituito uno stato imprevisto. La nota lo spiega. Controlla l'ordine e completalo oppure rimborsa il pagamento.
Payment error: un pagamento in verifica è stato rifiutato o annullato. La nota mostra lo stato e il suo dettaglio.
Refunded: il pagamento è stato rimborsato interamente tramite il modulo.
Se MercadoPago approva un pagamento per un ordine già annullato o rimborsato, lo stato non cambia e una nota ti chiede di completare l'ordine o di rimborsare il pagamento. Se arriva un altro pagamento per un ordine già pagato, una nota ti chiede di rimborsare il pagamento in eccesso dal pannello di MercadoPago.
Blocco pagamento MercadoPago
La pagina dell'ordine mostra un blocco MercadoPago payment con l'ID del pagamento, lo stato del pagamento, l'ambiente (un badge Test per i pagamenti di test), le rate, l'importo addebitato da MercadoPago e il totale dell'ordine, l'importo rimborsato, lo storico dei rimborsi e le MercadoPago notes dell'ordine.
Rimborsi
Nel blocco MercadoPago payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via MercadoPago. Conferma la domanda Refund this amount through MercadoPago? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini. I rimborsi sono limitati all'importo addebitato da MercadoPago, quindi dopo una differenza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato con le credenziali dell'ambiente in cui è stato effettuato il pagamento (test o produzione), quindi l'Access Token di quell'ambiente deve essere impostato. Se MercadoPago rifiuta il rimborso, il blocco mostra MercadoPago refused the refund con il motivo e nessun rimborso viene registrato. Un rimborso approvato o in elaborazione viene aggiunto allo storico dei rimborsi e alle note con l'ID del rimborso. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.
Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite MercadoPago.
I rimborsi, gli storni e le mediazioni effettuati nel pannello di MercadoPago arrivano con la notifica e vengono aggiunti alle note. Lo stato dell'ordine e le note di credito non vengono modificati automaticamente. Aggiornali manualmente se necessario.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox MercadoPago Gateway è il primo blocco di Modules > Module Manager > VibeFox MercadoPago 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 verificare 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-mercadopago 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 cambiare 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 che l'indirizzo del negozio cambia, o dopo che liberi 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 solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, MercadoPago non viene mostrato ai clienti al checkout. Se comunque viene avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche per 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
MercadoPago non compare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che la modalità attuale abbia entrambe le credenziali con il prefisso giusto: le chiavi TEST- in modalità test, le chiavi APP_USR- in produzione. Verifica che la valuta del carrello sia quella del tuo account MercadoPago. La pagina delle impostazioni indica quale 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 l'ordine resta in Awaiting MercadoPago payment: la notifica non è arrivata. Il modulo invia l'URL di notifica solo quando il tuo negozio ha un indirizzo pubblico (non localhost né un dominio .local o .test). Aggiungi l'URL da Notification URL in your application > Webhooks con l'evento Payments. Se Webhook secret signature è impostato, verifica che sia la firma segreta della stessa applicazione. Il pannello di MercadoPago mostra la risposta del tuo negozio per ogni notifica.
La notifica risponde invalid signature: la firma segreta appartiene a un'altra applicazione, oppure la notifica non ha una x-signature valida. Copia di nuovo la firma segreta o lascia il campo vuoto.
La notifica risponde no credentials for test o no credentials for live: l'Access Token dell'ambiente in cui è stato effettuato il pagamento non è impostato. Inseriscilo; MercadoPago ripete la notifica.
La notifica risponde not for this store: il pagamento non appartiene a un tentativo di pagamento di questo negozio. Nessun ordine viene modificato.
La notifica risponde order busy or payment could not be read: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento, oppure MercadoPago non era raggiungibile. MercadoPago ripete la notifica automaticamente.
Una credenziale non viene salvata: l'errore must start with indica che il valore ha il prefisso sbagliato per il campo. I campi di test accettano credenziali TEST-, quelli di produzione credenziali APP_USR-.
Il cliente vede This payment method is not configured correctly. Please choose another payment method or contact the store.: le credenziali della modalità attuale mancano, hanno il prefisso sbagliato o sono state rifiutate da MercadoPago. Controllale nella pagina delle impostazioni.
Il cliente vede MercadoPago cannot process payments in: la valuta del carrello non è quella del tuo account MercadoPago. MercadoPago non converte le valute.
Il modulo sicuro per la carta non si carica: il cliente vede The secure card form could not be loaded. Please reload the page or choose another payment method. Controlla la Public Key della modalità attuale.
Il cliente vede Your payment was received, but the order could not be completed automatically: MercadoPago ha preso il pagamento, ma PrestaShop non è riuscito a creare l'ordine (per esempio perché il modulo era disattivato in quel momento). Controlla il campo Log nella pagina del modulo: gli errori vengono sempre registrati. Al cliente viene chiesto di non pagare di nuovo; il tentativo di pagamento successivo o la notifica successiva per il carrello crea l'ordine senza un nuovo addebito.
L'ordine è in MercadoPago payment on hold dopo il pagamento: leggi le MercadoPago notes nel blocco dell'ordine (vedi Stati dell'ordine), poi completa l'ordine o rimborsa il pagamento.
Il rimborso non riesce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità test o produzione, e l'Access Token di quella modalità non è impostato. Inseriscilo e riprova.
Il rimborso non riesce con MercadoPago did not answer the refund request: controlla il pagamento nel pannello di MercadoPago prima di riprovare.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox MercadoPago 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, la verifica salvata dell'account e i log. Se è disattivo, tutte le impostazioni vengono conservate per una futura reinstallazione. I record dei pagamenti e dei rimborsi MercadoPago e gli stati d'ordine Awaiting MercadoPago payment e MercadoPago payment on hold restano sempre, quindi gli ordini pagati prima possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le loro note di pagamento e gli ID di transazione.
MercadoPago è un marchio del rispettivo titolare. Questo modulo non è affiliato né approvato da MercadoPago.