Volver

VibeFox MercadoPago for Adobe Commerce — Ayuda

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL extension.

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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-mercadopago-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/MercadopagoPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_MercadopagoPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox MercadoPago Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Choose the Account country, enter the test and live credentials and, optionally, set up notifications in your MercadoPago application (see Configuration). Set Enable to Yes and click Save Config. Test a payment in test mode with MercadoPago test cards, then set Test mode to No.

The module adds the Credit or debit card (MercadoPago) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the MercadoPago payment attempts, their events and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox MercadoPago Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website or a store view with the Scope switcher at the top of the page. Delete settings on uninstall should be set in the Default Config. Save Config saves the whole page.

If the Title is empty or longer than 128 characters, Magento shows Enter a payment title of 1 to 128 characters. and nothing on the page is saved. A credential that does not start with the expected prefix (TEST- for test fields, APP_USR- for live fields) or contains other characters than letters, digits, - and _ is not saved: Magento shows Invalid MercadoPago credential in and the field code, for example test_public_key, Its previous value was kept; other valid settings were saved.

The row Connection and account at the top of the group shows the Notification URL (see Payment notifications). While Enable is Yes, it also shows warnings: TEST MODE: Use MercadoPago test cards; no real charges. while test mode is on, Enter the Public Key and Access Token for the selected environment. when a credential of the current mode is missing, Credentials belong to another country: and the country code when an access token belongs to an account in another country than Account country, The access token belongs to an unsupported MercadoPago site. and The store currency does not match the account currency with the currency code. To check the country, the module asks MercadoPago which account each access token belongs to and remembers the answer for one hour. When the answer is known, the module uses the country of the account, not the Account country setting.

General

Enable: shows or hides the payment method at checkout. Default: No.

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, at most 128 characters.

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: AR (ARS).

AR (ARS), BR (BRL), CL (CLP), CO (COP), MX (MXN), PE (PEN), UY (UYU): the supported countries: Argentina, Brazil, Chile, Colombia, Mexico, Peru and Uruguay. 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; customers see TEST MODE: No real charges. Use MercadoPago test cards. at checkout. Set it to No to charge real cards with the live credentials. Default: Yes.

Test Public Key: starts with TEST-. Used in the browser to turn the card into a token.

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

Clear saved test access token: set to Yes and click Save Config to delete the saved test access token. The field goes back to No after saving.

Live Public Key: starts with APP_USR-.

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

Clear saved live access token: set to Yes and click Save Config to delete the saved live access token.

Magento stores the access tokens and the webhook secret encrypted and shows only a mask (******) after saving. Leave the mask or the empty field as it is to keep the saved value (Blank secret input retains its saved value.), type a new value to change it. To delete a saved value, use the matching Clear saved … field. An emptied public key field is saved empty.

Payment options

Maximum installments: the highest number of installments (cuotas or parcelas) the customer can choose. The server clamps this value to 1 through 24. With 1 only a single payment is offered. 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 store has a public address (not localhost or a .local, .test or .localhost domain). You can also add it in your application > Webhooks, event Payments. The URL is shown in Notification URL in the Connection and account row: the storefront address of the store view of the selected scope (the default store view in the Default Config). It looks like https://your-store/wcpmercadopagogateway/webhook/index. 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 store. Without notifications, orders under review stay in Pending 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 Pending Payment and is completed by a later notification.
rejected, cancelled: the payment was declined or cancelled. The order is cancelled.
refunded, charged_back, in_mediation: a note is added to a paid order; the order is not changed.

Webhook Secret: optional. The secret signature shown in your application > Webhooks. When set, notifications without a valid x-signature are rejected (HTTP 401). The secret is read for the store view of the payment, so set it in the Default Config or for the website or store view where customers pay.

Clear saved webhook secret: set to Yes and click Save Config to delete the saved webhook secret.

Advanced

Debug logging: writes MercadoPago requests and notifications to var/log/wc_mpg_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings are always logged, also while this setting is No. Access tokens, card tokens and payer data are not logged. Default: No.

Debug log: shown in the Default Config. It shows the size and the last 50 KB of the log. Click Clear log to empty it.

Delete settings on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings, the saved account check and the log (see Uninstall). The license key is always removed. The MercadoPago payment records and refunds always stay, so orders paid before can still be refunded after a re-install. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Credit or debit card (MercadoPago)), sees the description and fills in the card fields: Card number, Expiry, Security code and Cardholder name. Depending on the country and the card, the customer also chooses the document type and enters the number in Document, selects the Issuer and the number of Installments. The installment options and interest come from MercadoPago for the cart total. If a field is missing, the customer sees Please complete the secure card fields and cardholder details. The card form is made for the standard Magento checkout (Luma); other checkout themes may need adaptation.

After Place Order, MercadoPago turns the card into a one-time token and Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. Your store then creates the payment on the server for the order total in the order currency. The customer's e-mail and name, the document and the cart number are passed to MercadoPago; the payment shows as Order #, the order number and your store name. CLP and COP amounts are charged without decimals.

An approved payment creates the invoice with the MercadoPago payment ID as the transaction ID, sets the order to Processing and sends the order and invoice e-mails. The customer sees the standard order success page with Your MercadoPago payment has been verified. A payment under review leaves the order in Pending Payment, and the page shows Awaiting MercadoPago payment confirmation. Your order will be updated when the payment is confirmed. An order put on hold shows Your MercadoPago payment requires review by the store. Please do not pay again.

A declined card cancels the order (the stock goes back), restores the cart and shows a short reason in the cart, 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 a Payment confirmation page with 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. and a Check again link. 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 is already paid is never charged again: a new order of that cart is cancelled and the customer is sent to the paid order.

When MercadoPago reviews a payment for a long time, the Magento cron may cancel the order after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). If the payment is approved later, the order stays cancelled and gets a note (see Orders and refunds).

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. MercadoPago is not offered for orders created in the Admin or for multishipping checkout.

Orders and refunds

Order statuses

Pending Payment: the order was placed and is waiting for the MercadoPago answer, or the payment is under review (in process or pending) and waits for the notification. There is no invoice.

Processing: MercadoPago approved the payment and the amount and currency match the order. The invoice is created with the MercadoPago payment ID as the transaction ID, and a note shows the payment ID and the amount.

On Hold: the approved amount or currency differs from the order, or MercadoPago returned an unexpected status. No invoice is created. The note MercadoPago payment requires manual review. shows the actual charge and the payment ID. Check the payment, then fulfil the order or refund the payment (see Refunds without an invoice).

Canceled: the card was declined, the payment could not be started, or a payment under review was rejected or cancelled. The note shows the reason.

Closed: the payment was fully refunded with a credit memo.

If MercadoPago approves a payment for an order that is already cancelled or closed, the order is not changed and the note MercadoPago payment … arrived after cancellation. Reconcile or refund it manually. is added. If another payment arrives for a cart that is already paid, a note asks you to refund the extra payment manually. The notes are order comments that the customer does not see.

MercadoPago payment history

On the admin order page (Sales > Orders > View, Information tab) the section MercadoPago payment history lists every payment attempt of the order: payment ID, mode (test or live), result, detail, the requested amount and currency and the amount and currency MercadoPago received (amounts in minor units). It is shown also when the module is disabled. The customer sees only the payment method title.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through MercadoPago. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through MercadoPago.

The refund is made in the order currency, up to the amount MercadoPago charged minus the amounts already refunded. For CLP and COP the credit memo total is rounded to whole units like the charge, and the credit memo that refunds the rest of the order refunds exactly what is left of the charge. The refund is sent with the credentials of the environment the payment was made in (test or live), so that environment's access token must be set. If MercadoPago does not accept the refund, Magento shows the error and the credit memo is not created. An approved or in-process refund is recorded on the order with the MercadoPago refund ID. A full refund closes the order.

Refunds, chargebacks and mediations made in the MercadoPago panel arrive by the notification and are added to the order notes. The order and credit memos are not changed automatically. After a refund in the MercadoPago panel, online refunds of that order are refused with Provider refunds differ from native history. Reconcile before another online refund. Create a credit memo with Refund Offline to record it in Magento.

Refunds without an invoice

A charge without a paid invoice (an order On Hold after a mismatch, or a payment that arrived after cancellation) cannot be refunded with a credit memo. Under MercadoPago payment history the order page then shows This received charge has no paid invoice. Refund it here; no artificial Invoice or Credit Memo will be created., an amount field with the amount not refunded yet and the button Refund received payment. Confirm This cannot be undone. Refund this amount?. You need the Admin permission to create credit memos. The amount must have the decimals of the currency (none for CLP and COP). After MercadoPago refund accepted. a note records the refund. When the whole charge is refunded, the order is cancelled.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox MercadoPago Gateway is the first row of the VibeFox MercadoPago Gateway group in Stores > Configuration > Sales > Payment Methods, 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 store. Below them are the line Product: magento-payment-mercadopago and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees This payment method is not configured correctly. Please choose another payment method or contact the store. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

MercadoPago does not appear at checkout: check that the license is active and Enable is Yes for the store, and that the current mode has both credentials with the right prefix: the TEST- keys in test mode, the APP_USR- keys in live mode. Check that the cart currency is the currency of your MercadoPago account. The Connection and account row shows warnings for a missing credential, another account country and another store currency.

The payment went through, but the order stays Pending Payment: the notification did not arrive. The module sends the notification URL only when your store has a public address (not localhost or a .local, .test or .localhost domain). Add the URL from Notification URL in your application > Webhooks with the event Payments. If Webhook Secret is set, check that it is the secret of the same application and that it is set for the store view where customers pay. 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 clear it with Clear saved webhook secret.

Notification answers Payment could not be verified, retry later: the access token of the environment the payment was made in is not set, MercadoPago could not be reached, or the payment does not belong to a payment attempt of this store. No order is changed. Enter the missing access token; MercadoPago retries the notification.

Notification answers Busy, retry later or Retry later: the order was being updated by another request at the same moment, or an error occurred. MercadoPago retries the notification automatically.

The notification URL shows Method not allowed in the browser: this is normal. The URL accepts only POST requests from MercadoPago.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. MercadoPago retries the notification later.

A credential is not saved: the warning Invalid MercadoPago credential in shows that the value has the wrong prefix for the field. Test fields take TEST- credentials, live fields APP_USR- credentials.

The customer is back in the cart with This payment method is not configured correctly. Please choose another payment method or contact the store.: the license is not active, or the credentials of the current mode are missing, have the wrong prefix or were rejected by MercadoPago. Check them on the settings page. The order of that attempt is cancelled.

The customer is back in the cart with The order currency is not supported by this MercadoPago account.: 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 fields could not be loaded. Please try again. Check the Public Key of the current mode.

The customer sees The card number is not recognised. Please check it.: MercadoPago did not recognise the card number typed into the secure fields, or could not return the issuer and installment options for it. The customer can check the number or use another card.

Order is On Hold after payment: read the order notes and MercadoPago payment history (see Order statuses), then fulfil the order or refund the payment.

An approved payment arrived for a cancelled order: the order was cancelled, for example by the Magento cron after the Pending Payment Order Lifetime, before MercadoPago approved it. Refund the payment with Refund received payment or reconcile it manually. A longer lifetime gives MercadoPago more time to review payments.

Refund fails with The original MercadoPago payment could not be verified.: the access token of the environment the payment was made in (test or live) is not set, or MercadoPago could not be reached. Enter the token and try again.

Refund fails with The refund outcome is unknown. Check provider history before retrying.: MercadoPago did not answer. Check the payment in the MercadoPago panel before trying again. A retry with the same amount is matched to the earlier refund instead of sending a new one.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice is refunded with Refund received payment (see Refunds without an invoice).

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_MercadopagoPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_MercadopagoPayment to remove the data, then bin/magento module:disable Vibefox_MercadopagoPayment, delete the folder app/code/Vibefox/MercadopagoPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Delete settings on uninstall is Yes, the gateway settings, the saved account check and the log are removed too. If it is No, the settings are kept for a re-install. The MercadoPago payment records and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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