Mercado Pago Terminal Gateway
The Mercado Pago Terminal gateway lets you take in-person payments on Mercado Pago Point Smart terminals from WCPOS. A payment is started from WooCommerce and completed on the terminal, and Mercado Pago's confirmation is written back to the order.
Mercado Pago Terminal for WooCommerce is a new extension and 0.1.0 is its first release. Treat it as a beta: start in Test mode with Mercado Pago's sandbox virtual terminal and run a test payment before taking real payments.
Features
Point Smart Hardware
Take in-person payments on Mercado Pago Point Smart 1 and 2 terminals
Live Terminal List
Terminals are fetched live from your account, with a one-click Switch to PDV action in settings
Reliable Completion
Polling every 2 seconds, the Mercado Pago webhook, and a 5-minute background check confirm payments, even if the browser was closed
Refunds from WooCommerce
Send full or partial refunds from the WooCommerce order screen
Built-in Diagnostics
Check the connection and webhook status in settings, and download a support bundle for troubleshooting
How It Works
The gateway uses Mercado Pago's cloud Orders API for Point. Starting a payment creates a Mercado Pago order for the full WooCommerce order total and pushes it to the selected terminal. The Mercado Pago order expires after 5 minutes.
The payment page polls Mercado Pago every 2 seconds. The webhook and a 5-minute background check can also complete a paid order, even if the browser was closed. The webhook is optional but recommended; without a Webhook secret, notifications are still processed but are not signature-verified.
The terminal must be in PDV (integrated) mode. Terminals ship in STANDALONE mode, so switch to PDV in the gateway settings and restart the terminal before taking payments.
Setup
Install Mercado Pago Terminal for WooCommerce
Download the plugin zip asset (not the GitHub source-code zip) from the GitHub releases page. Upload it via Plugins > Add New > Upload Plugin and activate it with WooCommerce installed and active.
Add your Mercado Pago credentials
- Go to
WP Admin > WooCommerce > Settings > Paymentsand open Mercado Pago Terminal - Choose Mode:
Testdrives the sandbox virtual terminal;Livedrives real terminals - Paste the Access token (
APP_USR-…) from your application under Mercado Pago → Your integrations → Credentials
A TEST- token in Live mode sends payments to the sandbox. The settings screen warns about this combination; paste your production token before taking real payments.
Register the webhook
- In Mercado Pago, go to Your integrations → your application → Webhooks
- Add the webhook URL shown on the gateway settings screen
- Select the Order (Mercado Pago) event and save
- Copy the secret signature into Webhook secret in WooCommerce
The webhook is optional. Payments still complete by polling without it, but configuring the secret lets the plugin verify webhook signatures.
Set up your terminals
- Save and reload the settings screen. The Default terminal dropdown and Terminals table list your account's terminals
- For a terminal shown in STANDALONE mode, click Switch to PDV, then restart the terminal
- Choose a Default terminal
- (Optional) Restrict Enabled terminals to the devices cashiers can choose. Leave it empty to allow all terminals; the saved default remains available even if it is not selected here
- (Optional) Enable Lock terminal selection to always use the default terminal and prevent cashiers from changing it. This requires a default terminal
- Save your settings
Enable in WCPOS
- Go to
WP Admin > POS > Settings > Checkout - Find the Mercado Pago Terminal gateway and enable it for the POS
- Save your settings
The Enable/Disable checkbox on the WooCommerce settings screen controls the online store checkout only. WCPOS uses this gateway once it is configured, whether or not that box is ticked.
Settings reference
| Setting | What it does |
|---|---|
| Enable/Disable | Enables the gateway for online store checkout. POS enablement is controlled under POS > Settings > Checkout |
| Title | The checkout label; defaults to Mercado Pago Terminal |
| Description | The checkout description; defaults to Pay in person on a Mercado Pago Point terminal. |
| Mode | Test (default) uses the sandbox virtual terminal; Live uses real terminals with live credentials |
| Access token | Your application's token from Mercado Pago → Your integrations → Credentials. A saved token is not shown again; leave blank to keep it |
| Webhook secret | The secret signature from Mercado Pago's webhook settings, used to verify notifications |
| Default terminal | The terminal used by default at checkout, fetched live from your account. A text field appears if the list cannot be fetched |
| Enabled terminals | Restricts the terminals cashiers can choose. Empty allows all terminals; the default is always available. Hidden if the list cannot load |
| Lock terminal selection | Always uses the default terminal so cashiers cannot change it. Requires a default terminal |
| Checkout debug logs | Shows Show logs, Copy, and Clear on the payment panel. Off by default; enable when gathering logs for support |
| Log level | Off, Errors only, or Debug. Defaults to Debug in this release, recording requests and responses with secrets removed |
Below the fields, the Mercado Pago Terminal diagnostics table shows the API check (including terminal and PDV counts), last verified webhook, active environment, whether credentials are configured, default terminal, webhook URL, and payment logs link.
Usage
Processing Payments
- Add Items: Add products to your cart in the POS
- Select Gateway: Choose Mercado Pago Terminal as the payment method
- Choose Terminal: Pick a terminal, or use the default when selection is locked
- Start Payment: Click Start Terminal Payment to send the order total to the terminal
- Customer Payment: Follow the status messages —
Sending to terminal…→Waiting for terminal…→Customer is paying on the terminal…— while the customer completes payment on the terminal - Automatic Completion: When Mercado Pago confirms payment, the order completes and the POS goes to the receipt
Payment Controls
- Start Terminal Payment: Send a new payment request to the selected terminal
- Cancel Terminal Payment: Cancel only before the terminal picks up the payment. After that, cancel on the terminal or wait for the 5-minute expiry
- Reloading the page: Resumes a payment already in progress
Receipts
The terminal prints no ticket. Use the POS receipt after payment completes.
Refunds
Open the WooCommerce order refund screen and choose Refund via Mercado Pago Terminal to send a full or partial refund. Mercado Pago allows refunds up to 90 days after payment.
Some card acquirers only allow refunds on the terminal. In that case, refund on the terminal and record a manual refund in WooCommerce.
Logs and support bundle
Find logs in WooCommerce > Status > Logs, under source mercadopago-terminal. The log level defaults to Debug in this release. Requests, responses, webhooks, and payment state changes are recorded with secrets and card numbers redacted.
Click Download support bundle on the gateway settings screen to download a .txt file and attach it to your support request. It contains environment details, settings with credentials masked, the terminal list and operating modes, payment attempts from the 10 most recent orders, and the last 500 log lines; nothing in it can be used to take payments.
Enable Checkout debug logs to add Show logs, Copy, and Clear to the payment panel. Payment activity is recorded in WooCommerce logs regardless of this setting.
Requirements
Scope & Limitations
- The terminal is charged the full order total. Paying only part of an order on the terminal is not supported
- Tips are not supported
- Amounts are sent with two decimals. Stores selling in Chilean or Colombian pesos should confirm with a test payment first
- The online-store Blocks checkout is not supported
- The plugin does not yet declare HPOS compatibility
Troubleshooting
Common Issues
Access token rejected by Mercado Pago (HTTP 401)
- The access token is invalid or stale
- Copy a fresh token from Your integrations → Credentials and save it in Access token
No terminals are listed
- If no Point terminals are linked to the account, log in on the terminal with that Mercado Pago account, switch to PDV, and restart it
- If Default terminal is a text box instead of a dropdown, the list could not be fetched. Check the token and diagnostics, then reload the settings screen
The terminal is in STANDALONE mode
- Integrated payments require PDV mode
- Click Switch to PDV in the settings screen's Terminals table, then restart the terminal
The payment is already on the terminal
- The terminal has picked up the payment, so it can no longer be cancelled from WooCommerce
- Cancel on the terminal or wait for the 5-minute expiry. The payment page continues checking its status
The webhook has never been verified
- Check the webhook URL and secret in Mercado Pago if diagnostics shows Last verified webhook: never
- If Webhook secret is missing, paste the secret signature from Mercado Pago. Payments still complete by polling, but notifications without the secret are not signature-verified
The card acquirer refused the refund
- Some acquirers only allow refunds on the terminal; Mercado Pago also limits refunds to 90 days
- Refund on the terminal and record a manual refund in WooCommerce
The payment expired on the terminal
- Mercado Pago orders expire after 5 minutes
- Start the payment again
Getting Help
- Attach the support bundle from the gateway settings screen to your support request
- Visit the GitHub repository to report issues
- Contact Mercado Pago support for account and hardware questions