VibeFox MercadoPago for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Senza WooCommerce il plugin non si attiva.

PHP: 8.0 o successivo.

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 quando le valute non corrispondono.

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. 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_mercadopago_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > MercadoPago > 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. Scegli il Account country, inserisci le credenziali di test e di produzione e, se vuoi, configura le notifiche nella tua applicazione MercadoPago (vedi Configurazione).

6. Attiva Enable / Disable e salva. Prova con le carte di test di MercadoPago (nome del titolare APRO = approvata, CONT = in attesa, OTHE = rifiutata), poi deseleziona Test mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > MercadoPago. 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 quando mancano le credenziali della modalità attuale o quando la valuta del negozio non è quella del tuo account MercadoPago (in quel caso il metodo di pagamento è nascosto al checkout), e quando le credenziali appartengono a un account di un paese diverso da Account country. Nell'elenco dei metodi di pagamento MercadoPago risulta da configurare finché la modalità attuale non ha le sue credenziali.

Al salvataggio, una credenziale che non inizia con il prefisso previsto (TEST- per i campi di test, APP_USR- per i campi di produzione) non viene salvata: appare un errore e resta il valore precedente. Il plugin chiede inoltre a MercadoPago a quale paese appartiene l'Access Token. Se non riesce a verificare il token, se l'account non si trova in un paese supportato o se il paese non coincide con Account country, appare un errore. Il plugin usa quindi il paese dell'account.

Generale

Enable / Disable: Enable MercadoPago card payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: Credit or debit card (MercadoPago).

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 richiesto il documento del titolare. La valuta del negozio deve essere la stessa, per esempio ARS per l'Argentina. Predefinito: Argentina (ARS).

Argentina (ARS), Brazil (BRL), Chile (CLP), Colombia (COP), Mexico (MXN), Peru (PEN), Uruguay (UYU): i paesi supportati. Il campo del documento è mostrato per tutti tranne il Messico.

Test mode: Use the test credentials (no real charges). In modalità test si usano le credenziali TEST- e paghi con le carte di test di MercadoPago; al checkout compare un badge TEST MODE. Deseleziona il campo per addebitare carte reali con le credenziali di produzione. Predefinito: attivato. Per testare con un account utente di test di MercadoPago (credenziali APP_USR-), inserisci le credenziali di quell'account nei campi di produzione e disattiva la modalità test.

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.

Opzioni di pagamento

Maximum installments: il numero massimo di rate (cuotas o parcelas) che il cliente può scegliere, da 1 a 24. 1 = solo pagamento in unica soluzione, e il campo delle rate non viene mostrato. Il limite viene applicato anche sul server. Predefinito: 1.

Notifiche di pagamento (webhook)

I pagamenti con carta di solito ricevono subito una risposta definitiva. I pagamenti che MercadoPago tiene in verifica (in elaborazione o in attesa) vengono completati dalle notifiche di MercadoPago. Il plugin invia l'URL di notifica con ogni pagamento quando il tuo sito ha un indirizzo pubblico. Puoi anche aggiungerlo in your application > Webhooks, evento Payments. L'URL è mostrato in questa sezione delle impostazioni e ha questo aspetto: https://your-site/wc-api/wc_mpg_webhook/?source_news=webhooks.

Una notifica non viene mai considerata attendibile di per sé. Il plugin rilegge il pagamento dalle API di MercadoPago con l'Access Token dell'ambiente in cui è stato effettuato il pagamento e lo associa all'ordine tramite ID e chiave dell'ordine. Senza notifiche, gli ordini in verifica restano In attesa finché non li aggiorni a mano.

Il plugin gestisce questi stati di pagamento di MercadoPago:

approved: il pagamento è stato approvato. L'ordine viene segnato come pagato quando importo e valuta corrispondono.

in_process, pending, authorized: il pagamento è in verifica. L'ordine passa In attesa ed è completato da una notifica successiva.

rejected, cancelled: il pagamento è stato rifiutato o annullato. Un ordine non pagato viene segnato come Non riuscito.

refunded, charged_back, in_mediation: viene aggiunta una nota; lo stato dell'ordine non cambia.

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).

Avanzate

Debug log: Log API requests and notifications scrive in WooCommerce > Status > Logs, origine wcp_mercadopago_gateway. Access Token, token delle carte e dati del pagatore non vengono registrati. Predefinito: disattivato.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Gli ID di pagamento MercadoPago salvati sugli ordini sono lo storico dei pagamenti e vengono sempre conservati. Predefinito: disattivato.

Checkout

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 Document number, seleziona il Card issuer e il numero di Installments. Le opzioni di rateizzazione e gli interessi arrivano da MercadoPago per il totale dell'ordine.

Quando l'ordine viene effettuato, MercadoPago trasforma la carta in un token monouso e il tuo negozio crea il pagamento sul server per il totale dell'ordine. L'e-mail e il nome di fatturazione, il documento e il numero dell'ordine vengono trasmessi a MercadoPago. Gli importi in CLP e COP vengono addebitati senza decimali, arrotondati a un numero intero, quindi imposta a 0 il numero di decimali di WooCommerce per queste valute.

Un pagamento approvato viene segnato subito come pagato e il cliente va alla pagina dell'ordine ricevuto. Un pagamento in verifica mette l'ordine In attesa; anche in questo caso il cliente va alla pagina dell'ordine ricevuto, e l'ordine viene completato dalla notifica. Una carta rifiutata mostra al checkout 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; per ogni tentativo viene creato un nuovo token della carta.

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 l'ordine viene pagato mostra This order is already being paid. Please wait a moment and check your e-mail before trying again.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin accetta solo carte di credito e di debito. Non prevede il reindirizzamento a Checkout Pro, il wallet o il saldo di MercadoPago, nessun pagamento in contanti (Rapipago, OXXO, boleto e altri), nessun Pix, PSE o Yape, nessuna carta salvata o abbonamento, nessuna autorizzazione e cattura separate, nessuna verifica 3-D Secure e nessuna conversione di valuta.

Ordini e rimborsi

Stati dell'ordine

Pending payment: l'ordine è stato creato e non è ancora arrivato alcun esito del pagamento, per esempio dopo un timeout.

Processing: MercadoPago ha approvato il pagamento e importo e valuta corrispondono. Gli ordini con soli prodotti virtuali scaricabili passano a Completato, il comportamento predefinito di WooCommerce. La nota dell'ordine mostra l'ID del pagamento MercadoPago e il numero di rate. L'ID della transazione è l'ID del pagamento MercadoPago.

On hold: il pagamento è in verifica (in elaborazione o in attesa) e attende la notifica di MercadoPago. L'ordine viene messo In attesa anche quando l'importo o la valuta approvati non corrispondono all'ordine, oppure quando MercadoPago restituisce uno stato inatteso. La nota dell'ordine lo spiega.

Failed: il pagamento è stato rifiutato o annullato. La nota dell'ordine mostra lo stato e il relativo dettaglio. Il cliente può pagare di nuovo.

Se MercadoPago approva un pagamento per un ordine 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 più dal pannello di MercadoPago.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Credit or debit card (MercadoPago) (il pulsante mostra il tuo Title). Sono supportati rimborsi totali e parziali. 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, WooCommerce mostra MercadoPago refused the refund con il motivo e nessun rimborso viene registrato. Un rimborso approvato o in elaborazione viene aggiunto alle note dell'ordine con l'ID del rimborso.

I rimborsi e i chargeback effettuati nel pannello di MercadoPago arrivano tramite notifica e vengono aggiunti alle note dell'ordine. Non vengono registrati automaticamente come rimborsi di WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > MercadoPago. 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 solo dominio. Rimuovere la chiave da un sito non libera lo slot del dominio. Libera lo slot dal tuo account vibefox.net.

Senza una chiave attiva, MercadoPago 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. I gestori del negozio connessi 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 appare nella pagina Plugins e nelle pagine di WooCommerce. 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

MercadoPago does not appear at checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che la modalità attuale abbia entrambe le credenziali con il prefisso corretto: le chiavi TEST- in modalità test, le chiavi APP_USR- in produzione. Verifica che la valuta del negozio (o la valuta dell'ordine nella pagina Pay for order) sia quella del tuo account MercadoPago. La pagina delle impostazioni indica quale manca.

The payment went through, but the order stays On hold or Pending payment: il pagamento è andato a buon fine, ma l'ordine resta In attesa o In attesa di pagamento: la notifica non è arrivata. Il plugin invia l'URL di notifica solo quando il tuo sito ha un indirizzo pubblico (non localhost né un dominio .local o .test). Aggiungi l'URL delle impostazioni in your application > Webhooks con l'evento Payments. Se è impostata la Webhook secret signature, verifica che sia la firma segreta della stessa applicazione. Il pannello di MercadoPago mostra la risposta del tuo negozio per ogni notifica.

Notification answers 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.

Notification answers not for this store: il pagamento non appartiene a un ordine di questo negozio pagato con MercadoPago. L'ordine non viene modificato.

A credential is not saved: l'errore must start with indica che il valore ha il prefisso sbagliato per il campo. I campi di test accettano credenziali TEST-, i campi di produzione credenziali APP_USR-.

The customer sees This payment method is not configured correctly. Please choose another payment method or contact the store.: mancano le credenziali della modalità attuale, hanno il prefisso sbagliato oppure MercadoPago le ha rifiutate. Controllale nella pagina delle impostazioni.

The customer sees MercadoPago cannot process payments in: la valuta dell'ordine non è quella del tuo account MercadoPago. MercadoPago non converte le valute.

The secure card form does not load: 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. Per maggiori dettagli attiva il Debug log e consulta WooCommerce > Status > Logs, origine wcp_mercadopago_gateway.

Refund fails with a message about the mode: il pagamento è stato effettuato in modalità test o produzione, e l'Access Token di quella modalità non è impostato. Inseriscilo e riprova.

Refund fails with MercadoPago did not answer the refund request: controlla il pagamento nel pannello di MercadoPago prima di riprovare.

The license block shows an error: 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 della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, la verifica dell'account salvata e i log vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento, gli ID dei pagamenti MercadoPago e gli ID delle transazioni.

MercadoPago è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da MercadoPago.