VibeFox MercadoPago for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Shop 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 for a cart in another currency.

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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox MercadoPago Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

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

5. Turn on Enable / Disable and click Save. Test a payment in test mode with MercadoPago test cards, then turn off Test mode.

On install the module creates two order statuses, Awaiting MercadoPago payment and MercadoPago payment on hold. PrestaShop assigns a new payment module to the countries that are active at install time. Check the currencies, countries and customer groups of the module in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox MercadoPago Gateway > Configure. Each section has its own Save button, which saves the whole page. 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 Public Key or Access Token of the current mode is missing or when the shop 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.

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: the error must start with … — the previous value was kept. is shown. The module also asks MercadoPago which country each access token belongs to. If the token of the current mode cannot be checked, if the account is not in a supported country or if the country differs from Account country, an error is shown. The module then uses the country of the account.

MercadoPago

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. It is also the payment method name stored in the order. Default: Credit or debit card (MercadoPago). Required.

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 shop currency must be the same, for example ARS for Argentina. When credentials are saved, the country is checked against the account. 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: in test mode the TEST- credentials are used and you pay with MercadoPago test cards; a TEST MODE badge is shown at checkout. Turn it off to charge real cards with the production credentials. Default: on.

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.

Saved access tokens and the webhook secret are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

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 module sends the notification URL with every payment when your shop has a public address (not localhost or a .local or .test domain). You can also add it in your application > Webhooks, event Payments. The URL is shown in Notification URL in this section. With friendly URLs it looks like https://your-shop/en/module/wcp_mercadopago_gateway/webhook?source_news=webhooks. Copy the URL exactly as the settings show it.

A notification is never trusted as such. The module re-reads the payment from the MercadoPago API with the access token of the environment the payment was made in and binds it to a payment attempt of your shop. Without notifications, orders under review stay in Awaiting MercadoPago payment until you update them by hand.

The module 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 waits in Awaiting MercadoPago payment and is completed by a later notification.

rejected, cancelled: the payment was declined or cancelled. No order is created; an order that was waiting gets Payment error.

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

Clear saved secrets: tick Test Access Token, Production Access Token or Webhook secret signature and click Save to remove it. An empty field keeps the saved value.

Advanced

Debug log: writes MercadoPago requests and notifications to logs/wc_mpg_debug.log.php in the module folder. The file cannot be opened from the web. Errors are always logged, also while this setting is off. Access tokens, card tokens and payer data are not logged. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: when on, uninstalling the module removes the gateway settings and the logs. MercadoPago payment records, refunds and the module's order statuses always stay, so orders paid before can still be refunded after a re-install. Default: off.

Checkout

At the payment step 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 cart total. The card form works with the Classic and Hummingbird themes.

When the customer confirms, MercadoPago turns the card into a one-time token and your shop creates the payment on the server for the cart total. The customer's e-mail and name, the document and the cart number are passed to MercadoPago; the payment shows as Cart #, the cart number and your shop name. CLP and COP amounts are charged without decimals. No order exists before MercadoPago answers.

An approved payment creates a paid order, and the customer sees the order confirmation page with Your card payment has been received. A payment under review creates an order in Awaiting MercadoPago payment, and the page shows MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. If a payment under review is later rejected, the page shows Your MercadoPago payment was not completed. Please contact us about this order. An order on hold shows Your payment is being reviewed. We will update your order as soon as the review is complete.

A declined card creates no order. The customer stays on the payment step with a short reason, 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 cart is being paid shows This order is already being paid. Please wait a moment and check your e-mail before trying again. A cart that already has an order is never charged again; the customer is sent to its confirmation page.

The notification URL works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module 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

No order: the card was declined, or MercadoPago has not answered yet. Only the cart exists.

Payment accepted: MercadoPago approved the payment and the amount and currency match the cart. The payment is recorded with the MercadoPago payment ID as the transaction ID, and a note shows the payment ID, the environment and the number of installments.

Awaiting MercadoPago payment: the payment is under review (in process or pending) and waits for the MercadoPago notification. The order moves to Payment accepted when MercadoPago approves it.

MercadoPago payment on hold: the approved amount or currency differs from the cart, or MercadoPago returned an unexpected status. The note explains it. Check the order and fulfil it or refund the payment.

Payment error: a payment under review was rejected or cancelled. The note shows the status and its detail.

Refunded: the payment was fully refunded through the module.

If MercadoPago approves a payment for an order that is already cancelled or refunded, 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.

MercadoPago payment block

The order page shows a MercadoPago payment block with the payment ID, the payment status, the environment (a Test badge for test payments), the installments, the amount MercadoPago charged and the order total, the amount refunded, the refund history and the MercadoPago notes of the order.

Refunds

In the MercadoPago payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via MercadoPago. Confirm the question Refund this amount through MercadoPago? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders. Refunds are limited to the amount MercadoPago charged, so after an amount mismatch you can refund up to what the customer actually paid, not the order total. 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, the block shows MercadoPago refused the refund with the reason and no refund is recorded. An approved or in-process refund is added to the refund history and the notes with the refund ID. A full refund sets the order to Refunded. A partial refund does not change the status.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through MercadoPago.

Refunds, chargebacks and mediations made in the MercadoPago panel arrive by the notification and are added to the notes. The order status and credit slips are not changed automatically. Update them manually if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox MercadoPago Gateway is the first block on Modules > Module Manager > VibeFox MercadoPago Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-mercadopago and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 cart currency is the currency of your MercadoPago account. The settings page tells you which one is missing. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but the order stays Awaiting MercadoPago payment: the notification did not arrive. The module sends the notification URL only when your shop has a public address (not localhost or a .local or .test domain). Add the URL from Notification URL 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 shop 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 no credentials for test or no credentials for live: the access token of the environment the payment was made in is not set. Enter it; MercadoPago retries the notification.

Notification answers not for this store: the payment does not belong to a payment attempt of this shop. No order is changed.

Notification answers order busy or payment could not be read: the order was being updated by another request at the same moment, or MercadoPago could not be reached. MercadoPago retries the notification automatically.

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

The customer sees Your payment was received, but the order could not be completed automatically: MercadoPago took the payment, but PrestaShop could not create the order (for example, the module was disabled at that moment). Look at the Log field on the module page: errors are always logged. The customer is asked not to pay again; the next payment attempt or notification for the cart creates the order without a new charge.

Order is MercadoPago payment on hold after payment: read the MercadoPago notes in the order block (see Order statuses), then fulfil the order or refund the payment.

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.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox MercadoPago Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the gateway settings, the saved account check and the logs are removed. If it is off, all settings are kept for a later re-install. The MercadoPago payment records and refunds and the order statuses Awaiting MercadoPago payment and MercadoPago payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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