Accepting Payments with Mercado Pago

The Mercado Pago add-on lets your clients pay for their photo orders with your Mercado Pago account. Mercado Pago is the most common way to pay online in much of Latin America, so it's a good fit if you and your clients are in Argentina, Brazil, Mexico, Chile, Colombia, Peru or Uruguay.

Countries and Currencies

A Mercado Pago account takes payments in one currency: the currency of the country the account was opened in.

Your store currency in Sunshine has to match your Mercado Pago account's currency. For example, a Brazilian Mercado Pago account needs the store currency set to Brazilian real. You'll find the store currency in Sunshine > Settings > General.

If the two don't match, Mercado Pago would charge the same number in its own currency (a 150 BRL order would become 150 ARS on an Argentine account). Sunshine catches this before the customer is sent to pay. The customer isn't charged, and with Checkout Pro they see this message at checkout:

Mercado Pago can't take payments in [your currency] for this store. Please choose another way to pay.

A note is added to the order explaining which currency the account takes, and the Admin Payment Problem email is sent if you have it turned on.

Installing the Add-on

Mercado Pago is included in the Plus and Pro plans.

• Plus or Pro plan: go to Sunshine > Add-ons and activate Mercado Pago. Sunshine downloads it and sets up its license for you. See Install add-ons for Pro/Plus/Basic licenses.
• Add-on bought by itself: install the plugin file, then enter its license key in Sunshine > Settings > Licenses. See Install individually purchased add-on.

Your license keys are in Account > Licenses. More help is in License Keys.

Checkout Pro or the On-site Card Form

The add-on gives you two separate payment methods. Each one is turned on and set up on its own in Sunshine > Settings > Payments, and you can use either one or both.

Mercado Pago (Checkout Pro)

When the customer places their order, they're sent to a payment page on Mercado Pago's website. They can pay with any way Mercado Pago offers in your country: credit and debit cards, their Mercado Pago account balance, and local options like Pix or cash vouchers where they're available. Once they're done, Mercado Pago sends them back to your site.

Mercado Pago (on-site card form)

This one is listed simply as Mercado Pago. Mercado Pago's card form appears right on your checkout page, so the customer types in their card and never leaves your site.

Which one to use

• Use Checkout Pro if you're not sure. It offers the most ways to pay, and it handles payments that take time to clear (like a cash voucher) by finishing the order once Mercado Pago confirms the money arrived.
• Use the on-site card form if your clients mostly pay by card and you'd like them to stay on your site. The order is only completed when Mercado Pago approves the payment right away. A payment that's still being reviewed or waiting to be paid is not accepted, and the customer is asked to try again.

Both methods charge the full amount in one payment. Installment plans (paying in several monthly parts) aren't offered.

Getting Your Mercado Pago Keys

Sunshine connects to Mercado Pago with two keys, a Public Key and an Access Token. You get them from Mercado Pago's developer area. You don't need to be a developer; it's just where Mercado Pago keeps them.

1. Log in to your Mercado Pago account, then go to Mercado Pago Developers and open Your integrations
2. Click Create application if you don't have one yet. Give it a name (your business name is fine) and choose an online payments option when asked
3. Open your application
4. For real payments, open Production credentials in the menu on the left. If you haven't used them before, Mercado Pago asks for your business type and website before it shows them
5. Copy the Public Key and the Access Token

For test payments, open Test credentials in the same application instead. Test keys work right away and never move real money.

Keep your Access Token private. Anyone who has it can make charges and refunds on your account.

Settings

Go to Sunshine > Settings > Payments, turn on the Mercado Pago method you want with its toggle, then click Configure. Checkout Pro and the card form have the same list of settings, but each keeps its own values, so if you use both you'll fill in both.

• Name: what customers see as the payment option at checkout. Leave it blank to use "Mercado Pago" or "Mercado Pago (Checkout Pro)".
• Description: a short line shown under the name at checkout. Leave it blank to use the default ("Pay with credit card" for the card form, "Pay with credit card or your Mercado Pago (Checkout Pro) account" for Checkout Pro).
• Fees: add an extra charge to orders paid this way, as a percentage of the order or a fixed amount. Choose No added fees to leave orders as they are. When you add a fee, Fee Name is what the customer sees it called and Fee Amount is how much it is. See Payment Gateway Fees.
• Mode: Live takes real payments. Test uses your test keys so you can try checkout without moving any money. Live is chosen by default.
• Public Key and Access Token: paste the keys you copied from Mercado Pago. There's one pair for Live and one pair for Test, and you only see the pair for the mode that's selected. Put production keys in the Live fields and test keys in the Test fields. Checkout Pro only uses the Access Token, but it's fine to fill in both.
• Statement Descriptor: the short name shown on your customer's card statement, like your business name. It's sent with Checkout Pro payments. Payments made with the on-site card form show the name set in your Mercado Pago account.

Testing Before You Go Live

1. Copy the test keys from Test credentials in your Mercado Pago application
2. In the Mercado Pago settings in Sunshine, set Mode to Test and paste the test keys into the Test fields
3. Place an order in a private or incognito browser window

While test mode is on, customers see "This will be processed as a test payment and no real money will be exchanged" at checkout, so it's easy to tell which mode you're in.

Mercado Pago lists test cards you can use. The name you type as the cardholder decides what happens: APRO approves the payment, and OTHE declines it, which is a handy way to see what a declined payment looks like. Checkout Pro also asks you to log in as a test buyer, which you can create under Test accounts in your Mercado Pago application.

Switch Mode back to Live when you're ready to take real payments.

What Customers See at Checkout

With Checkout Pro, the customer fills out checkout as usual, picks Mercado Pago (Checkout Pro), and clicks Continue to payment details. They're taken to Mercado Pago's page to pay. Their cart stays in place until the payment is done, so nothing is lost if they come back without paying.

With the on-site card form, Mercado Pago's card fields load on your checkout page as soon as the customer picks Mercado Pago. Depending on your country, the form may also ask for an ID number (like a CPF in Brazil), because Mercado Pago needs it for card payments there. The customer fills it in and places the order without leaving your site.

Neither method asks for a billing address.

After the Customer Pays

When Mercado Pago approves a payment, Sunshine checks it with Mercado Pago before marking the order paid. The payment has to be approved, made for this order, in the order's currency, and for the full order total. A payment that was already used to pay a different order isn't accepted either.

Once it passes, the order is marked New, the customer lands on their order receipt page, and the usual order emails go out. The Mercado Pago payment ID is saved on the order. Open the order in Sunshine > Orders and click the Mercado Pago tab to see the transaction ID and Mercado Pago's fee for that payment.

If a payment is approved but doesn't match the order (for example, the amount is different), the order is left unpaid and a note on the order explains why. Check your Mercado Pago account before doing anything else, since the customer may have been charged.

When a Payment Is Declined, Cancelled or Fails

Sunshine keeps the order in every one of these cases. Nothing is deleted, so you can always see that the customer tried to pay.

• Customer cancels or leaves Mercado Pago's page (Checkout Pro): they're sent back to checkout with the message "Payment has been cancelled", and the order is marked Cancelled. Their cart is still there so they can try again or pick another way to pay. If they paid on Mercado Pago's page after all, Mercado Pago lets Sunshine know and the cancelled order is completed.
• Card is declined (on-site card form): the customer stays on checkout and sees "Payment could not be processed, please try again". The order stays Pending Payment with a note saying the payment was declined.
• Mercado Pago can't set up the payment (Checkout Pro): the customer sees "Could not prepare payment" at checkout, and the order is marked Failed with Mercado Pago's reason added to the order notes.

When the customer tries again, Sunshine may start a fresh order for the new try. The earlier order stays on record either way.

Payment Notices from Mercado Pago

Mercado Pago sends your site a notice (sometimes called a webhook) whenever a Checkout Pro payment changes. This is what finishes the order when a customer pays and then closes their browser before coming back to your site, or when a payment takes a day or two to clear, like a cash voucher.

You don't need to set anything up for this. Sunshine tells Mercado Pago where to send the notice with every payment, so there's nothing to add in your Mercado Pago account. Your site does need to be live on the internet for the notices to reach it, so they won't arrive on a site that only runs on your own computer.

The on-site card form doesn't need notices at all, because the payment is checked with Mercado Pago while the customer is still at checkout.

Refunds

You can refund a Mercado Pago payment from your WordPress admin without logging in to Mercado Pago.

1. Open the order in Sunshine > Orders
2. In the Order Actions panel, choose Refund payment in Mercado Pago (or Refund payment in Mercado Pago (Checkout Pro))
3. Leave Full refund checked to refund everything that's left, or uncheck it and enter a smaller amount
4. Leave Notify customer via email checked to email the customer about the refund, or uncheck it to skip the email
5. Click Submit

A full refund marks the order Refunded. A partial refund is recorded on the order but keeps its current status, and you can refund more later up to what's left. The amount is shown in the order's own currency.

If Mercado Pago turns the refund down, you'll see "Could not refund payment" with Mercado Pago's reason at the top of the screen, and the same message is added to the order notes.

Admin Payment Problem Email

Sunshine can email you when something goes wrong with a payment, so you don't have to spot it in the orders list. It's off by default. Turn on Admin Payment Problem in Sunshine > Settings > Email, and use its Send when options to pick which problems you hear about. See Emails for more on each email.

For Mercado Pago, this email covers:

• a payment that didn't match the order (wrong amount or currency, or made for another order)
• a store currency that doesn't match your Mercado Pago account
• a declined or cancelled payment (tick the "declined or cancelled" option to get these)
• an order marked Failed because Mercado Pago couldn't set up the payment

Each email includes the order and the reason, and the reply-to address is the customer's email.

Troubleshooting

The customer is asked to choose another way to pay

Your store currency doesn't match your Mercado Pago account's currency. Change the currency in Sunshine > Settings > General to your Mercado Pago account's currency, or use a Mercado Pago account opened in the same country as your store's currency.

The on-site card form doesn't appear, or checkout keeps loading

The card form couldn't start. Check that:

• the store currency matches your Mercado Pago account's currency
• both the Public Key and Access Token are filled in for the mode you've selected
• you didn't mix up keys, like test keys in the Live fields

"Could not prepare payment" with Checkout Pro

Mercado Pago wouldn't create the payment page. Open the order in Sunshine > Orders; the order notes show Mercado Pago's reason. The most common cause is a wrong or expired Access Token, or test keys entered in the Live fields.

An order is still Pending Payment after the customer paid

With Checkout Pro, the order is finished when the customer comes back to your site or when Mercado Pago's notice arrives. If neither has happened:

• check that your site is live on the internet and not blocked by a maintenance or "coming soon" mode
• look in your Mercado Pago account to see if the payment is approved or still waiting (cash and bank payments can take a while)
• read the order notes, which explain when a payment was found but didn't match the order

The card form says "Payment could not be processed, please try again"

The payment wasn't approved right away. It may have been declined by the card's bank or held for review by Mercado Pago. The order notes show Mercado Pago's status for the payment. The customer can try another card or another way to pay.

A refund won't go through

Read the reason in the "Could not refund payment" message. Make sure the Access Token for the order's mode is still filled in, and that the amount isn't more than what's left to refund.