- Send customers to Checkout Pro, Mercado Pago’s hosted page for cards, Pix (Brazil’s instant bank transfer), boleto (a Brazilian bank slip), and Mercado Pago account balance
- Show a Pix QR code and copy-paste code on your own page (Brazil)
- Mark an order as paid only after Mercado Pago confirms the payment
- Refund a payment in full or in part
- Charge a card every month or year with a Mercado Pago subscription
- Read payments for a sales dashboard or reconciliation
Common use cases and example apps
These examples show what you can build with Mercado Pago, each with a prompt to start from.How to connect Mercado Pago
Who can create Mercado Pago connections depends on your plan and workspace settings. App + chat connectors are available by default. On Business and Enterprise plans, Who can create connections and clients starts at Admins. Some Enterprise workspaces start at No one, which disables the connector. An admin or owner changes it in Connectors → Admin settings → App + chat connectors. You can create multiple Mercado Pago connections using different access tokens, which is useful for connecting more than one Mercado Pago account. When the connection is created, you can link it to the projects where you want to use it. Anyone building in a project can ask Lovable in the project chat to link their project to it. Linking follows the connection’s access rules.Prerequisites
Before connecting Mercado Pago, make sure you have:- A Mercado Pago account you sell with
- An application in the Mercado Pago developer panel and its access token
- A registered Pix key, the address that receives a Pix transfer, if you want to take Pix payments on your own page
- Permission to create connections in your Lovable workspace (see Who can create connections and clients)
Payments made through this connector go to your Mercado Pago account. Mercado Pago charges its fees directly, and billing is handled by Mercado Pago, not Lovable.
Step 1: Get a Mercado Pago access token
The access token lets your Lovable app create and read payments in your Mercado Pago account. Each application has test credentials, for payments that move no real money, and production credentials, for real payments. To get an access token:1
Open the developer panel
Sign in to the Mercado Pago developer panel and select the application you want to take payments with. If you have none yet, create one.
2
Open the credentials
Click Credentials in the side menu, then select Test or Production.Production credentials must be activated first. Click Activate production environment, enter your business sector and website, accept the terms, and click Activate.
3
Copy the access token
Copy the Access Token and store it securely. Lovable rejects the Public Key, which can’t create payments.
Step 2: Connect Mercado Pago to Lovable
Use your test access token for the first connection, so you can try payments without moving real money.1
Open Mercado Pago in Connectors
Open Connectors and select Mercado Pago. For the other places to open the catalog from, see Where to find connectors.
2
Add a connection
Click Connect on the connector page. The form is split into collapsible sections, Details, Configure connection, and Sharing.
3
Name the connection
Under Details, Lovable fills in a name for the connection, which you can change. The name is only used inside Lovable to identify the connection.
4
Configure the connection
Under Configure connection, enter:
- Access token: paste the access token you copied. Get value next to the field opens the Mercado Pago developer panel.
5
Choose who can use this connection
Under Sharing, the connection is private to you by default and shows a Private label. To share it, click Share with others. Then add workspace members by email, or click Invite entire workspace to make the connection available to everyone in your Lovable workspace.See Who can use connections and clients for more information.
6
Connect
Click Connect at the bottom of the form. Lovable verifies the access token against the Mercado Pago API before saving the connection.
How payments are confirmed
Mercado Pago tells your app about each change to a payment by calling a webhook, a public address in your app. For one-off payments, Lovable sets that address on every payment it creates, so you don’t need to register a webhook in the Mercado Pago panel. You can take test payments before you publish the app. Your app looks up each payment in Mercado Pago and marks the order paid only when the payment is approved for the order’s amount. Your app also checks the payment when the customer returns to your site, or when the customer clicks a button to confirm they paid. A lost webhook call, or a Pix customer who never comes back, does not leave the order pending. A Pix code made with test credentials can’t be paid from a bank app. To see Pix work end to end, pay a small amount with production credentials and refund it. Subscriptions work differently in two ways:- Mercado Pago sends subscription updates only to a webhook URL saved in your Mercado Pago application. Ask Lovable in the project chat for the webhook URL. Save that URL under Webhooks in the developer panel, and select the subscriptions event.
- Mercado Pago accepts only your published app’s address or custom domain as the page a subscriber returns to, so publish the app before you test a subscription.
Limitations
The Mercado Pago connector cannot:- Collect card details on your own page. Card payments go through Checkout Pro, which needs no card form in your app.
- Charge Pix or boleto on a subscription. Mercado Pago subscriptions charge cards only, so for customers who pay with Pix, ask Lovable to sell each period as a one-off payment instead.
- Split a payment between sellers or take a marketplace fee. Each connection represents a single Mercado Pago account shared across all projects linked to it.
- Match payments made through a payment link you create in the Mercado Pago panel to an order, because those links carry no order reference. Ask Lovable to create the checkout from your app instead.
Troubleshooting
Use these checks when connecting fails or a payment does not go through.Mercado Pago did not validate your credentials
Mercado Pago did not validate your credentials
Mercado Pago rejected the access token you submitted. Check that you copied the whole token and that the application it belongs to still exists. Click Show error to see Mercado Pago’s own response.
Mercado Pago says one of the parties is a test user
Mercado Pago says one of the parties is a test user
Mercado Pago does not allow a payment between a test account and a real account. With test credentials, pay from a test account of the same country as your application. Create the test account under Test accounts in the developer panel. With production credentials, pay from a real account. If the Pay button is disabled, you’re signed in to Mercado Pago as the seller: pay from another account in a private browser window.
The customer paid, but the order is still pending
The customer paid, but the order is still pending
Ask Lovable in the project chat to check the order’s payment in Mercado Pago. Lovable reads the payment and finds why your app missed it. If payments are confirmed in the preview but not in your published app, publish the app again.
Manage your Mercado Pago connection
Connections are managed from Connectors: select Mercado Pago, then open the connection.- Unlink projects to remove Mercado Pago access from specific projects while keeping the connection available for others. See Unlink projects from a connection for the steps.
- Delete the connection to remove it from the workspace entirely. Deleting is permanent. It removes the credentials from all linked projects, and app features that use Mercado Pago stop working until a new connection is added. See Delete a connection for the steps and who can delete.