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 Easy Digital Downloads for one-time payments. Each payment is read back from Mercado Pago before the order is marked paid, and 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 | Account site | Currency |
|---|---|---|
| Argentina | MLA | ARS |
| Brazil | MLB | BRL |
| Chile | MLC | CLP |
| Colombia | MCO | COP |
| Mexico | MLM | MXN |
| Peru | MPE | PEN |
| Uruguay | MLU | UYU |
When you save an access token, Stackless reads the account’s country from Mercado Pago and shows it at the top of that mode’s section, 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. Until a token is saved, every currency in the table counts. Chilean and Colombian pesos are sent as whole numbers.
Mercado Pago works with Sell in Multiple Currencies, and Match Payment Gateways to Currencies knows the account’s currency.
Turn On the Gateway
- Switch on the Mercado Pago module under Stackless → Dashboard.
- Add your access token under Stackless → Settings → Mercado Pago and save.
- Go to Downloads → Settings → Payments and switch on Mercado Pago (Stackless) under Active Gateways. Save.
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 in the Production section, and pick your application. Then fill in:
- Title: the gateway name at checkout. Default “Mercado Pago”.
- Description: the text under it. Default “You’ll finish paying on Mercado Pago with a card, your Mercado Pago balance or a local payment method.”
- Test mode: uses your Mercado Pago test credentials, so no real money moves. On by default. This switch is separate from EDD’s Enable Test Mode.
- Debug log: writes Mercado Pago activity to the EDD debug log. Off by default.
- 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 reads each new token’s account from 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_EDD_MERCADOPAGO_LIVE_ACCESS_TOKEN, STACKLESS_EDD_MERCADOPAGO_LIVE_WEBHOOK_SECRET, STACKLESS_EDD_MERCADOPAGO_TEST_ACCESS_TOKEN and STACKLESS_EDD_MERCADOPAGO_TEST_WEBHOOK_SECRET.
Connect the Webhook
- In Your integrations, open your application, then Webhooks → Configure notifications.
- Paste
https://yoursite.com/wp-json/stackless-edd/v1/mercadopago/webhookas both the test mode URL and the production mode URL. The Webhook section of the settings screen shows your exact URL. - Select the Payments event and save.
- 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. They also bring refunds and chargebacks made in Mercado Pago into EDD. 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 as “Mercado Pago” with “You’ll finish paying on Mercado Pago with a card, your Mercado Pago balance or a local payment method.” In test mode, checkout adds “Test mode: no real payment will be taken.”
- Purchasing sends the buyer to Checkout Pro with one line, “Order [number] at [store name]”, for the order total, so discounts and tax always add up to what EDD 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 your EDD success page. Mercado Pago only sends buyers back automatically on HTTPS sites.
- A rejected payment sends the buyer back to pay the same order again, with “Your payment did not go through. Please try again or choose another payment method.”
- Paying 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 with a note that it’s paid automatically once Mercado Pago approves the payment, and the buyer sees the success page. Payments Mercado Pago is still reviewing are held the same way. A Pending, Failed or Abandoned order can be held like this.
- When Mercado Pago approves the payment, the webhook completes the order.
- If the payment is rejected or cancelled, the order becomes Failed.
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 completes the order, 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
- EDD’s refund form on the order gets a Refund transaction in Mercado Pago box, ticked by default. Mercado Pago is asked first. If it refuses, you see its error and EDD records nothing. Partial and full refunds both work. 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.
- Untick the box to record the refund in EDD only. The order gets a note saying the transaction wasn’t refunded in Mercado Pago.
- Refunds made in Mercado Pago are recorded on the order once when the notification arrives: a full refund, or a partial one spread across the order’s items.
- 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 download’s Renewal mode decides whether Mercado Pago shows at checkout:
- Automatic only (requires a gateway that saves cards) hides Mercado Pago.
- Automatic when the gateway supports it, otherwise manual shows Mercado Pago, and paying with it makes the subscription manual.
- Manual only (customer pays each renewal invoice) 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 active gateway, and paying puts an on-hold subscription back to Active. See Sell Downloads as Subscriptions and Handle Renewals and Failed Payments 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.
- With Alerts on in Extra Enhancements (“Email me about failed live payments”), failed live Mercado Pago orders and failed live calls to Mercado Pago are emailed to you.
- Turn on Debug log to write Mercado Pago activity to Downloads → Tools → Debug Log, tagged
stackless-edd-mercadopago_gateway, while EDD debug mode is on. 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 pay link, 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.
- A buyer who finishes paying in a different browser from the one they checked out in lands on the success page without the purchase details. The webhook still confirms the order.
- 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_edd_mercadopago_gateway_checkout_args changes the Checkout Pro preference and receives the body, the order and the gateway. stackless_edd_mercadopago_gateway_currencies changes the currency list and receives the account’s site ID, such as MLB. The stackless_edd_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_edd_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-edd/mercadopago_gateway/payment-fields.php.