VibeFox MercadoPago for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. Without WooCommerce the plugin refuses to activate.

PHP: 8.0 or later.

Store currency: the currency of your MercadoPago account country: ARS (Argentina), BRL (Brazil), CLP (Chile), COP (Colombia), MXN (Mexico), PEN (Peru) or UYU (Uruguay). MercadoPago charges in the account currency and does not convert, so the payment method is hidden when the currencies differ.

MercadoPago account: you need an application in the MercadoPago developer panel (Your integrations > your application > Credentials) with its test credentials (start with TEST-) and production credentials (start with APP_USR-): a Public Key and an Access Token for each. For the optional signature check of notifications you also need the secret signature from your application > Webhooks.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_mercadopago_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > MercadoPago > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Choose the Account country, enter the test and production credentials and, optionally, set up notifications in your MercadoPago application (see Configuration).

6. Turn on Enable / Disable and save. Test with MercadoPago test cards (cardholder name APRO = approved, CONT = pending, OTHE = declined), then untick Test mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > MercadoPago. Above the fields the page shows Test mode is on: the TEST- credentials are used and no real money is charged. while test mode is on. It warns you when the credentials of the current mode are missing or when the store currency is not the currency of your MercadoPago account (the payment method is then hidden at checkout), and when the credentials belong to an account in another country than Account country. In the list of payment methods, MercadoPago is marked as needing setup until the current mode has its credentials.

When you save, a credential that does not start with the expected prefix (TEST- for test fields, APP_USR- for production fields) is not saved: an error is shown and the previous value is kept. The plugin also asks MercadoPago which country the access token belongs to. If it cannot check the token, if the account is not in a supported country or if the country differs from Account country, an error is shown. The plugin then uses the country of the account.

General

Enable / Disable: Enable MercadoPago card payments turns the payment method on or off. Default: off.

Title: the payment method name shown to the customer at checkout. Default: Credit or debit card (MercadoPago).

Description: the text shown above the card fields at checkout. Default: Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.

MercadoPago account

Get the credentials of your application in the MercadoPago developer panel: Your integrations > your application > Credentials. Test credentials start with TEST-, production credentials with APP_USR-.

Account country: the country of your MercadoPago account. It decides the charged currency, the language of the card fields and whether the cardholder document is asked. The store currency must be the same, for example ARS for Argentina. Default: Argentina (ARS).

Argentina (ARS), Brazil (BRL), Chile (CLP), Colombia (COP), Mexico (MXN), Peru (PEN), Uruguay (UYU): the supported countries. The document field is shown for all of them except Mexico.

Test mode: Use the test credentials (no real charges). In test mode the TEST- credentials are used and you pay with MercadoPago test cards; a TEST MODE badge is shown at checkout. Untick it to charge real cards with the production credentials. Default: on. To test with a MercadoPago test user account (APP_USR- credentials), enter that account's credentials in the production fields and turn test mode off.

Test Public Key: starts with TEST-. Used in the browser to tokenize the card.

Test Access Token: starts with TEST-. Used on the server only. Keep it secret.

Production Public Key: starts with APP_USR-.

Production Access Token: starts with APP_USR-. Used on the server only. Keep it secret.

Payment options

Maximum installments: the highest number of installments (cuotas or parcelas) the customer can choose, from 1 to 24. 1 = single payment only, and no installments field is shown. The limit is also enforced on the server. Default: 1.

Payment notifications (webhooks)

Card payments usually get a final answer at once. Payments that MercadoPago keeps under review (in process or pending) are completed by MercadoPago notifications. The plugin sends the notification URL with every payment when your site has a public address. You can also add it in your application > Webhooks, event Payments. The URL is shown in this section of the settings and looks like https://your-site/wc-api/wc_mpg_webhook/?source_news=webhooks.

A notification is never trusted as such. The plugin re-reads the payment from the MercadoPago API with the access token of the environment the payment was made in and binds it to the order by order ID and order key. Without notifications, orders under review stay On hold until you update them by hand.

The plugin handles these MercadoPago payment statuses:

approved: the payment was approved. The order is marked paid when the amount and currency match.

in_process, pending, authorized: the payment is under review. The order is put on hold and completed by a later notification.

rejected, cancelled: the payment was declined or cancelled. An unpaid order is marked Failed.

refunded, charged_back, in_mediation: a note is added; the order status is not changed.

Webhook secret signature: optional. The secret signature shown in your application > Webhooks. When set, notifications without a valid x-signature are rejected (HTTP 401).

Advanced

Debug log: Log API requests and notifications writes to WooCommerce > Status > Logs, source wcp_mercadopago_gateway. Access tokens, card tokens and payer data are not logged. Default: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. MercadoPago payment IDs saved on orders are payment history and are always kept. Default: off.

Checkout

The customer chooses the payment method (by default Credit or debit card (MercadoPago)) and fills in the card fields: Card number, Expiry (MM/YY), Security code and Cardholder name. Depending on the country and the card, the customer also chooses Document type and enters Document number, selects the Card issuer and the number of Installments. The installment options and interest come from MercadoPago for the order total.

When the order is placed, MercadoPago turns the card into a one-time token and your store creates the payment on the server for the order total. The billing e-mail and name, the document and the order number are passed to MercadoPago. CLP and COP amounts are charged without decimals and rounded to a whole number, so set the WooCommerce number of decimals to 0 for these currencies.

An approved payment is marked paid at once, and the customer goes to the order received page. A payment under review puts the order on hold, and the customer also goes to the order received page; the order is completed by the notification. A declined card shows a short reason on the checkout, for example Your card has insufficient funds. Please use another card or payment method. or Please check the security code of your card. The customer can correct the data or use another card; a new card token is created for each attempt.

If MercadoPago does not answer, the customer sees 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. The next attempt first looks the payment up, so the card is not charged twice. A second click while the order is being paid shows This order is already being paid. Please wait a moment and check your e-mail before trying again.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes credit and debit cards only. It has no Checkout Pro redirect, MercadoPago wallet or account money, no cash (Rapipago, OXXO, boleto and others), Pix, PSE or Yape, no saved cards or subscriptions, no separate authorize and capture, no 3-D Secure challenge and no currency conversion.

Orders and refunds

Order statuses

Pending payment: the order was created and no payment result has arrived yet, for example after a timeout.

Processing: MercadoPago approved the payment and the amount and currency match. Orders with only virtual downloadable products become Completed, the WooCommerce default. The order note shows the MercadoPago payment ID and the number of installments. The transaction ID is the MercadoPago payment ID.

On hold: the payment is under review (in process or pending) and waits for the MercadoPago notification. On hold is also set when the approved amount or currency differs from the order, or when MercadoPago returns an unexpected status. The order note explains it.

Failed: the payment was rejected or cancelled. The order note shows the status and its detail. The customer can pay again.

If MercadoPago approves a payment for a cancelled or refunded order, the status is not changed and a note asks you to complete the order or refund the payment. If another payment arrives for an order that is already paid, a note asks you to refund the extra payment in the MercadoPago panel.

Refunds

Open the order, click Refund, enter the amount and click Refund via Credit or debit card (MercadoPago) (the button shows your Title). Full and partial refunds are supported. The refund is sent with the credentials of the environment the payment was made in (test or production), so that environment's access token must be set. If MercadoPago refuses the refund, WooCommerce shows MercadoPago refused the refund with the reason and no refund is recorded. An approved or in-process refund is added to the order notes with the refund ID.

Refunds and chargebacks made in the MercadoPago panel arrive by the notification and are added to the order notes. They are not recorded as WooCommerce refunds automatically.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > MercadoPago. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, MercadoPago is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

MercadoPago does not appear at checkout: check that the license is active, Enable / Disable is on and the current mode has both credentials with the right prefix: the TEST- keys in test mode, the APP_USR- keys in production. Check that the store currency (or the order currency on the Pay for order page) is the currency of your MercadoPago account. The settings page tells you which one is missing.

The payment went through, but the order stays On hold or Pending payment: the notification did not arrive. The plugin sends the notification URL only when your site has a public address (not localhost or a .local or .test domain). Add the URL from the settings in your application > Webhooks with the event Payments. If Webhook secret signature is set, check that it is the secret of the same application. The MercadoPago panel shows the answer of your store for each notification.

Notification answers invalid signature: the secret signature belongs to another application, or the notification has no valid x-signature. Copy the secret again or leave the field empty.

Notification answers not for this store: the payment does not belong to an order of this store paid with MercadoPago. The order is not changed.

A credential is not saved: the error must start with shows that the value has the wrong prefix for the field. Test fields take TEST- credentials, production fields APP_USR- credentials.

The customer sees This payment method is not configured correctly. Please choose another payment method or contact the store.: the credentials of the current mode are missing, have the wrong prefix or were rejected by MercadoPago. Check them on the settings page.

The customer sees MercadoPago cannot process payments in: the order currency is not the currency of your MercadoPago account. MercadoPago does not convert currencies.

The secure card form does not load: the customer sees The secure card form could not be loaded. Please reload the page or choose another payment method. Check the Public Key of the current mode. For more details turn on Debug log and look at WooCommerce > Status > Logs, source wcp_mercadopago_gateway.

Refund fails with a message about the mode: the payment was made in test or production mode, and the access token of that mode is not set. Enter it and try again.

Refund fails with MercadoPago did not answer the refund request: check the payment in the MercadoPago panel before trying again.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the saved account check and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, MercadoPago payment IDs and transaction IDs.

MercadoPago is a trademark of its respective owner. This plugin is not affiliated with or endorsed by MercadoPago.