> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your app to Mercado Pago

> Connect your app to Mercado Pago, a Latin American payments provider, to take payments with Pix, cards, and Checkout Pro from your Lovable app.

[Mercado Pago](https://www.mercadopago.com/) is a payments provider used across Latin America, including Brazil, Argentina, and Mexico. The Mercado Pago connector lets your Lovable app take payments into your own Mercado Pago account and confirm each payment with Mercado Pago before it releases an order. It's designed for apps whose owners already sell with a Mercado Pago account.

Mercado Pago is available as an [app + chat connector](https://docs.lovable.dev/integrations/app-connectors.md): one shared connection that works in [Chats](https://docs.lovable.dev/features/chats.md), in the project chat while you build, and in your published apps.

With Mercado Pago, your app can:

* 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

If you don't have a Mercado Pago account, [Lovable payments](https://docs.lovable.dev/features/payments.md) can set up Stripe or Paddle for you instead. Built-in payments require the Pro plan or higher.

## Common use cases and example apps

These examples show what you can build with Mercado Pago, each with a prompt to start from.

| Example app | Example prompt | Description |
| :- | :- | :- |
| **Online store checkout** | *Use Mercado Pago and build a checkout for my shop so customers can pay for their cart with Checkout Pro.* | **Take payment for a cart in one step.** The app creates a Checkout Pro payment for the cart total, sends the customer to Mercado Pago, and marks the order paid when Mercado Pago confirms it. |
| **Pix payment page** | *Use Mercado Pago and build an order page that shows a Pix QR code and a copy-paste code, and confirms the order when it's paid.* | **Let customers pay with Pix without leaving your app.** The app shows the Pix code on your page and confirms the order as soon as Mercado Pago reports the payment as approved. |
| **Monthly membership** | *Use Mercado Pago and build a members area with a monthly Pro plan for R\$29.90.* | **Charge members every month.** The app creates a Mercado Pago subscription for the plan and gives access while the subscription is active. |
| **Refunds for support** | *Use Mercado Pago and build an admin page where my team can look up an order and refund it.* | **Refund orders from your own admin.** The app finds the order's payment in Mercado Pago and refunds the full amount or part of it. |
| **Sales dashboard** | *Use Mercado Pago and build a dashboard of this month's payments with their status and totals.* | **See your sales in one place.** The app reads payments from your Mercado Pago account, including refunds and chargebacks on older payments. |

## 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](https://docs.lovable.dev/integrations/admin-controls.md#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](https://docs.lovable.dev/integrations/app-connectors.md#link-a-connection-to-a-project) 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](https://www.mercadopago.com/developers/panel/app) and its access token
* A registered [Pix key](https://www.mercadopago.com.br/developers/en/docs/checkout-api/integration-configuration/integrate-pix), 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](https://docs.lovable.dev/integrations/admin-controls.md#who-can-create-connections-and-clients))

> [!NOTE]
>
> 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](https://www.mercadopago.com/developers/panel/app) 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.

> [!WARNING]
>
> Your access token functions like a password. Keep it secure and never share it publicly. You'll need it in the next step.

See Mercado Pago documentation for more: [Credentials](https://www.mercadopago.com/developers/en/docs/your-integrations/credentials).

### 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](https://lovable.dev/dashboard?connectors) and select **Mercado Pago**. For the other places to open the catalog from, see [Where to find connectors](https://docs.lovable.dev/integrations/introduction#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:

1. **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](https://docs.lovable.dev/integrations/admin-controls.md#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.

When connected, anyone building in a project can ask Lovable in the project chat to link their project to Mercado Pago. Linking follows the connection's access rules. Your Lovable apps can then take payments and confirm them with Mercado Pago.

When you're ready to take real payments, open the connection. Under **Configure connection**, click **Edit**, paste the production access token, and click **Update**. Every project linked to the connection then takes real payments.

## 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](https://docs.lovable.dev/features/publish.md) 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.

> [accordion] 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.

> [accordion] 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](https://www.mercadopago.com/developers/en/docs/your-integrations/test/accounts) 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.

> [accordion] 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**](https://lovable.dev/dashboard?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](https://docs.lovable.dev/integrations/app-connectors.md#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](https://docs.lovable.dev/integrations/app-connectors.md#delete-a-connection) for the steps and who can delete.
