# Mercado Pago Terminal Gateway The till sends the order total to a Mercado Pago **Point Smart** terminal, the customer pays on the terminal, and the sale finishes on its own when Mercado Pago confirms it. This page is in two parts: [taking a payment](#take-payment) at the till, and [setting it up](#setup) in WP Admin. Beta: run a test payment first This extension is new. No card payment or refund has been completed with it yet, so take a small payment and refund it before you rely on it. What has been tried so far On a live account and a real Point Smart, listing terminals, switching a terminal to PDV mode, and creating and cancelling a payment for it through Mercado Pago have worked. Whether the payment then shows on the terminal, a paid card payment, Mercado Pago's notification for a paid order, refunds, and Mercado Pago's sandbox (**Test** mode) have not been tried yet. ## Take a payment[​](#take-payment "Enlace directo a Take a payment") You need [WCPOS Pro](/es/getting-started/pro-license.md) and a store that's online, because the payment runs on your store's own payment page, inside the POS. Someone with WP Admin access [sets the gateway up](#setup) first. Open the register first With **Open and close the register** switched on, the till won't record a payment while the register is closed, and a card you've already taken would have to be refunded. See [Checkout](/es/getting-started/make-sale.md). The terminal runs from the **Legacy** tab of the checkout. In the shot below Mercado Pago isn't set up, so the list shows other gateways, with **Card** chosen. On your store, **Mercado Pago Terminal** is in that list: ![The checkout's Legacy tab on a store without Mercado Pago set up: the tab itself, the store's payment page inside the POS with the order total and its list of other gateways, and the Process Payment button](/img/2.x/payment/gateways/mercadopago-terminal/en/tablet-light-regular--mp-1-legacy-tab.png)123 1. **Legacy** tab — opens your store's own payment page inside the POS. 2. **Your store's payment page** — the order total and the store's gateways. **Mercado Pago Terminal** is in this list once it's set up. Choose it and its panel opens beneath it, with **Terminal** and **Start Terminal Payment**. 3. **Process Payment** — not needed for Mercado Pago: the sale finishes on its own when the payment is confirmed. 1) Build the cart and press **Checkout**. 2) Open the **Legacy** tab. Your store's payment page opens inside the POS. See [The Legacy Tab](/es/sell/take-payment/legacy-tab.md). 3) Choose **Mercado Pago Terminal**. Your store may have given it another name. 4) Check the terminal under **Terminal**. The default terminal is already chosen; when the terminal is locked, you can't change it. 5) Press **Start Terminal Payment**. The panel says **Sending to terminal…**, then **Waiting for terminal…**, and the full order total goes to that terminal. 6) The customer pays on the terminal. The panel says **Customer is paying on the terminal…** while they do. If it says **Confirm the payment on the terminal.**, finish the step the terminal is asking for. 7) When Mercado Pago confirms the payment, the panel says **Payment complete — finishing order…** and the POS moves on to the receipt. You don't need **Process Payment** at the foot of the Legacy tab: the sale finishes on its own when Mercado Pago confirms. Pressed before then, it only says the order hasn't been paid yet. The terminal is always charged the whole order, so it can't share a sale with another method. Once a payment has been taken on the order, the Legacy tab can't be used; [cancel that payment](/es/sell/take-payment/cancel-payment.md) first. ### Cancel or wait[​](#payment-controls "Enlace directo a Cancel or wait") * **Cancel Terminal Payment** replaces **Start Terminal Payment** while a payment runs. It works only until the terminal picks the payment up. After that the panel says **The payment is already on the terminal. Cancel it on the terminal, or wait for it to expire.** * **A payment expires** on Mercado Pago's side 5 minutes after you start it. The panel keeps checking, so a payment the customer finishes before then still completes the sale. * **Reloading the page** picks up the payment already in progress, with **Cancel Terminal Payment** showing. * **If the till closed** during a payment, don't charge the card again. Your store is built to finish a paid order on its own, from Mercado Pago's notification and from a check it runs every 5 minutes, but that has not been run live yet. Open the order, and the payment in your Mercado Pago account, and check whether it was paid. ## After the sale[​](#receipts "Enlace directo a After the sale") The terminal doesn't print a ticket. Print or email the POS receipt as usual; see [Receipts at Checkout](/es/sell/print-email-receipts.md). The order records the payment with Mercado Pago's order ID as its transaction ID. ## Refunds[​](#refunds "Enlace directo a Refunds") In WP Admin, open the order, click **Refund**, enter the amount and press **Refund … via Mercado Pago Terminal**. The whole order goes back as a full refund; any smaller amount as a partial refund. Mercado Pago allows refunds up to **90 days** after the payment. Some card acquirers only allow refunds on the terminal. If Mercado Pago refuses the refund, refund on the Point terminal, then record the refund in WooCommerce with **Refund manually**. See [Refunds](/es/sell/refunds.md). ## If something goes wrong[​](#goes-wrong "Enlace directo a If something goes wrong") The panel's status line tells you what happened. Open the one that starts with the same words. ### The payment won't start[​](#wont-start "Enlace directo a The payment won't start") Select a terminal first. Pick a terminal under **Terminal**, then press **Start Terminal Payment** again. Terminal … is in STANDALONE mode. The terminal can't take payments from the till yet. Ask whoever set up the gateway to [switch it to PDV](#terminals) and restart it. No terminals found on this Mercado Pago account. / Could not load terminals. The store can't list its terminals. Ask whoever set up the gateway to check the [diagnostics](#settings). Mercado Pago Terminal is disabled. The gateway is switched off for the POS. Ask whoever runs WP Admin to [turn it on](#turn-on). Mercado Pago Terminal request failed. The till couldn't reach your store or Mercado Pago. If the customer may have paid, check the order and your Mercado Pago account before starting another payment. Otherwise check the connection and try again. If it keeps happening, send the [support bundle](#logs-and-support-bundle). ### The payment stalls or fails[​](#stalls "Enlace directo a The payment stalls or fails") Before you start again, look at the terminal. **Never charge the card twice**: if the customer may have paid, check the order and your Mercado Pago account first. Still waiting for the terminal. A minute has passed with no answer. If the terminal shows the payment, let the customer finish; if not, press **Cancel Terminal Payment** and start again. The payment is already on the terminal. Cancel it on the terminal, or wait the 5 minutes for it to expire. The panel keeps checking, so if the customer pays anyway, the sale still finishes. Payment failed. The card or the payment was refused. Press **Start Terminal Payment** to try again, or take another method. The payment expired on the terminal. Five minutes passed. Press **Start Terminal Payment** again. Timed out waiting for the terminal. Six minutes passed with no result, and the till asks Mercado Pago to cancel the payment. Check the terminal before you start again. Mercado Pago reported a payment that does not match this order. The payment didn't match this order, for example its total or currency changed. Don't charge the card again. Check the order notes and the payment in your Mercado Pago account, and call your manager. Messages while setting up **Access token rejected by Mercado Pago (HTTP 401).** The token is wrong or out of date. Copy a fresh one from **Your integrations** → **Credentials** in Mercado Pago and save it in **Access token**. **Access token is not allowed to use Point (HTTP 403).** The application behind the token can't use Point. Check the application in **Your integrations**. **Could not reach Mercado Pago.** The store couldn't connect. Check the token, then reload the settings page. **No Point terminals are linked to this Mercado Pago account yet.** Log in on the terminal with this Mercado Pago account, then switch it to PDV and restart it. **Default terminal is a text box, not a list.** The terminal list couldn't be loaded. Check the token and the diagnostics, then reload the settings page. **Live mode is selected but the access token is a test token (TEST-…).** Payments would go to Mercado Pago's sandbox. Paste your production token, or switch **Mode** back to **Test**. **Last verified webhook: never.** Mercado Pago hasn't sent a signed notification yet. Check the webhook URL and the **Webhook secret**. The payment panel still completes payments while it stays open. **Mercado Pago refused the refund.** Some acquirers only allow refunds on the terminal: refund there, then record it with **Refund manually**. **Activation is refused.** The server needs **PHP 7.4** or newer. ## Set it up[​](#setup "Enlace directo a Set it up") This part is for whoever runs the store's WP Admin. Check [what you need](#requirements) before step 1. ### What you need[​](#requirements "Enlace directo a What you need") Mercado Pago Account : A seller account in Argentina, Brazil, Mexico, Uruguay, Colombia, Chile or Peru, with an application and its access token Terminal : A Mercado Pago Point Smart 1 or 2, in PDV mode Connection : Online only. The store sends each payment to the terminal over the internet, so any till can use any terminal and picks one at checkout WCPOS : WCPOS Pro Server : WordPress 5.2 or newer, WooCommerce, and PHP 7.4 or newer Currency : The same currency as your Mercado Pago account ### 1. Install the extension[​](#install "Enlace directo a 1. Install the extension") Open `WP Admin > POS > Settings > Extensions`, find **Mercado Pago Terminal for WooCommerce** and click **Install**. WCPOS downloads it, installs it and activates it in one go. See [Installing an Extension](/es/manage-store/add-ons.md#installing-an-extension). Without the directory, download the **plugin zip** (not the source-code zip) from the [GitHub releases page](https://github.com/wcpos/mercadopago-terminal-for-woocommerce/releases), upload it with **Upload Plugin** in `Plugins > Add Plugin`, then activate it. WooCommerce must be active. ### 2. Get ready in Mercado Pago[​](#mercado-pago-account "Enlace directo a 2. Get ready in Mercado Pago") 1. Create an application under **Your integrations** and activate its production credentials. Mercado Pago asks for your industry and website, and for you to accept the terms and pass a reCAPTCHA. 2. Create a **Store** and a **POS** in Mercado Pago. The extension doesn't create them for you. 3. Link your Point Smart terminal: log in on the terminal with the same Mercado Pago account. ### 3. Fill in the gateway settings[​](#gateway-settings "Enlace directo a 3. Fill in the gateway settings") 1. Go to `WP Admin > WooCommerce > Settings > Payments` and open **Mercado Pago Terminal**. 2. Choose **Mode**: **Test** (the default) drives Mercado Pago's sandbox virtual terminal; **Live** drives real terminals. 3. Paste the **Access token** (`APP_USR-…`) from your application under **Your integrations** → **Credentials**. Use the token that matches **Mode**. 4. If your currency has no cents, such as Chilean pesos, set **Number of decimals** to **0** under `WooCommerce > Settings > General`. Mercado Pago refuses amounts with decimals on those accounts, and the extension sends whole amounts only when this setting is 0. 5. Save. ### 4. Add the webhook (recommended)[​](#webhook "Enlace directo a 4. Add the webhook (recommended)") The webhook lets Mercado Pago tell your store when a payment is done. It is meant to finish a paid order even if the till was closed, but that hasn't been run live yet: [check the order](#payment-controls) before charging again. Without the webhook, the payment panel still completes payments while it stays open. 1. In Mercado Pago, open **Your integrations** → your application → **Webhooks**. 2. Add the webhook URL shown under **Webhook secret** in the gateway settings. It ends in `admin-ajax.php?action=mptfwc_webhook`. 3. Select the **Order (Mercado Pago)** event and save. 4. Copy the **secret signature** into **Webhook secret**, and save. With the secret saved, the store refuses any notification that isn't signed with it. Without a secret, the store still acts on Mercado Pago's notifications but can't check that they came from Mercado Pago, and **Last verified webhook** stays at **never**. ### 5. Set up your terminals[​](#terminals "Enlace directo a 5. Set up your terminals") 1. Reload the settings page. The **Default terminal** list and the **Terminals** table now show your account's terminals. 2. Terminals ship in **STANDALONE** mode. For each one, click **Switch to PDV**, then **restart the terminal**. Mercado Pago needs the restart. 3. Choose a **Default terminal**. 4. Optional: limit **Enabled terminals** to the ones cashiers may pick. Leave it empty to allow all; the default is always allowed. 5. Optional: tick **Lock terminal selection** so cashiers always use the default terminal. 6. Save. ### 6. Turn it on for the POS[​](#turn-on "Enlace directo a 6. Turn it on for the POS") Go to `WP Admin > POS > Settings > Checkout`, find **Mercado Pago Terminal** and switch **Enabled** on. See [Enabling a Gateway](/es/settings/checkout.md#enabling-a-gateway). Leave **Enable/Disable** in the WooCommerce settings off unless you want it online too. The POS uses the gateway once it is enabled here, whether that box is ticked or not. ## Settings reference[​](#settings "Enlace directo a Settings reference") On `WP Admin > WooCommerce > Settings > Payments > Mercado Pago Terminal`. The steps above cover the ones you need; open the list for every setting and its default. All 11 settings, and the diagnostics | Setting | What it does | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Enable/Disable** | Offers the gateway on the online store too. Off by default. The POS has its own switch, under `POS > Settings > Checkout` | | **Title** | The name cashiers choose on the payment page. Defaults to `Mercado Pago Terminal` | | **Description** | The line shown under the title. Defaults to `Pay in person on a Mercado Pago Point terminal.` | | **Mode** | **Test** (default) drives the sandbox virtual terminal; **Live** drives real terminals | | **Access token** | From your application under Your integrations → Credentials. Once saved it isn't shown again, only its last four characters; leave it blank to keep it | | **Webhook secret** | The secret signature from Mercado Pago's webhook settings. Saved and shown like the token | | **Default terminal** | The terminal chosen at the start. A list fetched from your account, or a text box when the list can't be loaded | | **Enabled terminals** | The terminals cashiers may pick. Empty allows all; the default is always allowed. Hidden when the list can't be loaded | | **Lock terminal selection** | Cashiers can't change the terminal: the default is always used. Needs a default terminal | | **Checkout debug logs** | Shows **Show logs**, **Copy** and **Clear** on the payment panel. Off by default; turn it on when gathering logs for support. Payments are logged either way | | **Log level** | **Off**, **Errors only** or **Debug** (the default) | Under the settings, **Mercado Pago Terminal diagnostics** shows the API check with the number of terminals and how many are in PDV mode, the last verified webhook, the active environment, whether the token and secret are set, the default terminal, the webhook URL and a link to the logs. The **Terminals** table lists each terminal's ID, label and operating mode, with **Switch to PDV** where it is needed. ## Logs and support bundle[​](#logs-and-support-bundle "Enlace directo a Logs and support bundle") Logs are in `WP Admin > WooCommerce > Status > Logs`, under the source `mercadopago-terminal`. **Log level** starts on **Debug**, which records every request to Mercado Pago and every answer, every webhook and every change in a payment's state, with tokens, signatures and card numbers removed. When a payment fails, click **Download support bundle** on the gateway's settings page and send the `.txt` file to support with the **order number**. Nothing in it can be used to take payments. What the support bundle holds * Your store's setup: the extension, WordPress, WooCommerce, PHP and WCPOS versions, and whether HPOS is on. * The gateway settings, with the access token and webhook secret masked. * Your terminals and their operating modes. * Payment attempts from the 10 most recent orders that used the terminal. * The last 500 lines of the `mercadopago-terminal` log. ## What it doesn't do[​](#scope-and-limitations "Enlace directo a What it doesn't do") * Part-payments: the terminal is always charged the whole order. * Tips. * A store priced in a different currency from the Mercado Pago account: the order won't complete. * Printing a ticket on the terminal. * The online store's block checkout. * HPOS (WooCommerce's order tables): the extension doesn't declare support for it yet. How it works, for developers The gateway uses Mercado Pago's **Orders API** for Point (`POST /v1/orders` with `type: point`). Starting a payment saves an idempotency key and an external reference on the order, then creates a Mercado Pago order for the order total on the chosen terminal, with a 5-minute expiry (filter `mptfwc_order_expiration_time`). A retry after a timeout reuses the key, so it can't charge twice. The panel asks for the status every 2 seconds (filter `mptfwc_poll_interval_ms`) and gives up after 6 minutes. The webhook (`x-signature`, HMAC-SHA256) and a scheduled check every 5 minutes can also complete the order; the webhook body is never trusted, and the order is always fetched again from Mercado Pago. The order completes only when the Mercado Pago order names it, was created by this store for it, is a `point` order, matches its total and currency, and used the attempt's terminal. Completion runs once, under a per-order lock. The transaction ID is the Mercado Pago order ID. ## Related Documentation[​](#related-documentation "Enlace directo a Related Documentation") * [The Legacy Tab](/es/sell/take-payment/legacy-tab.md) * [Checkout](/es/getting-started/make-sale.md) * [Checkout Settings](/es/settings/checkout.md) * [Extensions](/es/manage-store/add-ons.md) * [Report an issue on GitHub](https://github.com/wcpos/mercadopago-terminal-for-woocommerce/issues). For your account, credentials and terminals, contact Mercado Pago. [The Legacy TabGateways that take payment on the store's own payment page](/es/sell/take-payment/legacy-tab.md) [Checkout SettingsTurn gateways on for the POS](/es/settings/checkout.md) [All GatewaysThe other card terminals WCPOS works with](/es/settings/checkout/payment-gateways.md)