Set Up Mercado Pago Payments

In Latin America, a card is often not how people want to pay. Many buyers in Brazil use Pix or boleto, in Mexico they pay cash at OXXO, and across the region they keep a Mercado Pago balance. A card-only checkout loses them.

The Mercado Pago module adds Mercado Pago Checkout Pro to WooCommerce for one-time payments. Each payment is read back from Mercado Pago before the order is marked paid, cash and bank payments hold the order until they clear, refunds go back through Mercado Pago, and signed webhooks bring in refunds and chargebacks.

Countries and Currencies

A Mercado Pago account belongs to one country and charges in that country’s currency:

Country	Currency
Argentina	ARS
Brazil	BRL
Chile	CLP
Colombia	COP
Mexico	MXN
Peru	PEN
Uruguay	UYU

When you save an access token, Stackless reads the account’s country from Mercado Pago and shows it above the token, for example “Connected to a Mercado Pago account in MLB (charges in BRL).” From then on, Mercado Pago shows at checkout only when the order is in that currency. Chilean and Colombian pesos are sent as whole numbers.

Mercado Pago works with Multi-Currency Checkout, and Currency-Aware Payment Gateways knows the account’s currency.

Turn On the Gateway

1. Switch on the Mercado Pago module under Stackless → Dashboard.
2. Go to WooCommerce → Settings → Payments → Mercado Pago (Stackless).
3. Tick Enable (Accept payments with Mercado Pago).

Stackless → Settings → Mercado Pago only shows a link to that screen and your webhook URL. Mercado Pago stays off the checkout until the current mode has an access token.

Add Your Access Tokens

Open Your integrations in Mercado Pago, or use the Open Your integrations button, and pick your application. Then fill in:

• Test mode: on by default. No real money moves.
• Production access token: from Production → Production credentials.
• Production webhook secret
• Test access token: from Tests → Test credentials of the same application.
• Test webhook secret

Test and production tokens can both start with APP_USR-, so Stackless tells them apart by the account they belong to. When you save, it checks each token with Mercado Pago. A production token that belongs to a test account, or a test token that belongs to a real seller account, gets an error, so test orders never move real money. To test a payment, pay with a test buyer account and Mercado Pago’s test cards.

You can also set these as wp-config.php constants, which win over saved settings and hide their fields: STACKLESS_MERCADOPAGO_LIVE_ACCESS_TOKEN, STACKLESS_MERCADOPAGO_LIVE_WEBHOOK_SECRET, STACKLESS_MERCADOPAGO_TEST_ACCESS_TOKEN and STACKLESS_MERCADOPAGO_TEST_WEBHOOK_SECRET.

Connect the Webhook

1. In Your integrations, open your application, then Webhooks → Configure notifications.
2. Paste https://yoursite.com/wp-json/stackless/v1/mercadopago/webhook as both the test mode URL and the production mode URL. The gateway settings show your exact URL.
3. Select the Payments event and save.
4. Copy the secret signature Mercado Pago shows into the webhook secret field for each mode you use.

Mercado Pago signs each notification in the x-signature header: an HMAC-SHA256, keyed with that secret, of the payment ID, the x-request-id header and a timestamp. A notification without a valid signature is refused. A notification only says which payment changed, so Stackless reads the payment itself from the API, and applies each delivery once.

Webhooks confirm payments that settle later, such as boleto, OXXO and Pix, and payments whose buyer never came back, and bring refunds and chargebacks made in Mercado Pago into WooCommerce. Mercado Pago doesn’t let plugins set this up. Without the webhook secret, those updates never reach the order, so saving with the gateway on and no secret shows an error.

What Buyers See

At checkout, Mercado Pago shows with its default title, “Mercado Pago”, and “You’ll finish paying on Mercado Pago with a card, your Mercado Pago balance or a local payment method.” Test mode adds “Test mode: no real payment will be taken.” It works in the Checkout block, the classic checkout and the order payment page.

• Placing the order sends the buyer to Checkout Pro with one line, “Order [number] at [store name]”, for the order total, so shipping, discounts and tax always add up to what WooCommerce charges. Their email and name are filled in.
• Checkout Pro offers the methods of the account’s country, such as cards, Pix, boleto, OXXO and Mercado Pago balance.
• An approved payment returns the buyer to the order received page. Mercado Pago only sends buyers back automatically on HTTPS sites.
• A rejected payment sends the buyer back to the order payment page to try again.
• Placing the same order again within 30 minutes reuses the same Checkout Pro link.

Cash and Bank Payments

Boleto, OXXO and other cash or bank methods aren’t paid when the buyer leaves Checkout Pro. Stackless puts the order On hold, which keeps its stock reserved, with a note that the order is paid automatically once Mercado Pago approves the payment. Payments Mercado Pago is still reviewing are held the same way.

• When Mercado Pago approves the payment, the webhook marks the order paid.
• If the payment is rejected or cancelled, the order becomes Failed so the buyer can pay it again.

How Payments Are Verified

Neither the return address nor a notification marks an order paid on its own. Stackless reads the payment from Mercado Pago’s API, in the mode the order was started in, and checks that:

• its external reference names this order on this site
• its status is approved
• its currency and amount match the order total

A payment that passes marks the order paid, with a note naming the payment ID and method. A mismatch puts the order on hold with a note to check it in Mercado Pago. If a test payment ever reaches a live order, the order goes on hold with a note that no real money was taken.

Refunds and Chargebacks

• Refunds from the WooCommerce order screen, partial or full, are made in Mercado Pago. Retrying a refund that timed out never pays the customer twice.
• Mercado Pago refunds payments up to 180 days old, and only when your Mercado Pago balance covers the refund. Otherwise the refund fails with a message saying so.
• Refunds made in Mercado Pago are recorded on the order once when the notification arrives. Items aren’t restocked.
• Chargebacks add an order note. Review them in your Mercado Pago account.

Subscriptions With Mercado Pago

Mercado Pago takes one-time payments. It doesn’t save a payment method for Stackless to charge later, so subscriptions bought with it renew by pay link. The product’s Renewal mode decides whether Mercado Pago shows:

• Automatic only hides Mercado Pago at checkout.
• Automatic when the gateway supports it, otherwise manual shows Mercado Pago, and paying with it makes the subscription manual.
• Manual only shows Mercado Pago as usual.

At each renewal the customer gets the Subscription renewal invoice email with a link to pay the renewal order. They can pay it with Mercado Pago or any other available method, and paying reactivates the subscription if it went on hold. See Create Subscription Products and Renewals, Failed Payments and Retries for grace periods and reminders.

Check the Connection

• Billing Health lists Mercado Pago setup problems: no access token for the current mode, a token for the other mode, no webhook secret, no webhook received yet, and test mode left on. It also shows recent webhook events that failed.
• Turn on Debug log to write Mercado Pago activity to WooCommerce → Status → Logs (stackless-mercadopago_gateway). Tokens are never logged.

Limits

• Mercado Pago charges in the currency of the account’s country, so it shows at checkout only when the order is in that currency. One account covers one country.
• One-time payments only. Subscriptions renew by emailed invoice, never automatically.
• Refunds work for 180 days after the payment and need enough balance in the Mercado Pago account.
• The webhook has to be set up in Your integrations by hand.
• Mercado Pago only returns buyers automatically to HTTPS sites.
• Mercado Pago isn’t used for orders with nothing to pay, and can’t be duplicated for a second account with Payment Gateway Tools.

For Developers

stackless_mercadopago_gateway_checkout_args changes the Checkout Pro preference and receives the body, the order and the gateway. stackless_mercadopago_gateway_currencies changes the currency list and receives the account’s country site ID, such as MLB. The stackless_mercadopago_gateway_webhook action runs after each applied notification with its type, the notification and the mode. To allow card payments in one installment only:

add_filter('stackless_mercadopago_gateway_checkout_args', function ($args, $order, $gateway) {
    $args['payment_methods'] = ['installments' => 1];
    return $args;
}, 10, 3);

Override the checkout fields by copying the template to yourtheme/stackless/mercadopago_gateway/payment-fields.php.