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

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Mercado Pago

> Connect Mercado Pago to Payrails for cards and Mercado Pago checkout methods, covering your access token, public key and webhook.

<Note>
  **Who should use this guide**

  This guide is intended for merchants who:

  * Use **Payrails** as a payment orchestrator
  * Use **Mercado Pago** for cards or [Mercado Pago](/docs/orchestration/payment-methods/mercadopago/mercadopago) checkout methods such as [Yape](/docs/orchestration/payment-methods/yape/mercadopago) and [PagoEfectivo](/docs/orchestration/payment-methods/pagoefectivo/mercadopago)
  * Have access to your Mercado Pago developer panel
</Note>

***

## Create a Mercado Pago integration in Payrails

1. Log in to the **Payrails** portal.
2. Go to **Settings** → **Integrations**.
3. Select **Add instance** to create a new integration configuration.
4. Select the **workspaces** where this integration should be available.

<Note>
  **About workspaces**

  Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.
</Note>

***

## Step 1: Choose the integration type

* Select **Payment**.
* Continue to the next step.

***

## Step 2: Choose the provider

* Select **MercadoPago**.
* Continue to the next step.

<img src="https://mintcdn.com/payrails-42074109/DS81KC-NNGTwOcXz/images/docs/mercado-pago-image-01.png?fit=max&auto=format&n=DS81KC-NNGTwOcXz&q=85&s=1d432bd4b46d82305c9688dcda5d934d" alt="A screenshot showing Mercado Pago selected as the provider." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/mercado-pago-image-01.png" />

***

## Step 3: Configure your Mercado Pago integration

<Tip>
  **What you'll need from Mercado Pago**

  Before you begin, make sure you can log in to your Mercado Pago developer panel. You'll copy your application's credentials and set up a webhook there.
</Tip>

***

### Integration instance name

> An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing.

**In Payrails**

* Enter an **Instance name** for your integration, for example `merchant_mercadopago`.

<img src="https://mintcdn.com/payrails-42074109/145W1v58K5wnDMNC/images/docs/orchestration/integrations/shared/integration-instance-name.png?fit=max&auto=format&n=145W1v58K5wnDMNC&q=85&s=470be58979509680650b0cbf8b5eecc4" alt="A screenshot showing the integration instance name field." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/orchestration/integrations/shared/integration-instance-name.png" />

***

### Credentials

**In Mercado Pago**

1. In your Mercado Pago developer panel, open your application and go to **General Information**.
2. Copy the **Public Key** and **Access Token**.

**In Payrails**

| Field | Value |
| :- | :- |
| **Access Token** | Your Mercado Pago access token |
| **Public Key** | Optional. Your Mercado Pago public key. Payrails uses it to look up the card BIN and offer installments. |
| **HMAC** | The secret signature of your Mercado Pago webhook. Fill it in after you set up the webhook in the next section. |

Payments go to Mercado Pago's test or live mode depending on your credentials, so use the credentials that match the mode of your Payrails integration.

<img src="https://mintcdn.com/payrails-42074109/DS81KC-NNGTwOcXz/images/docs/mercado-pago-image-02.png?fit=max&auto=format&n=DS81KC-NNGTwOcXz&q=85&s=f41bf2e580cbf7696180ec60ad5307c6" alt="A screenshot showing the Mercado Pago credential fields." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/mercado-pago-image-02.png" />

***

### Session Configs

**In Payrails**

| Field | Value |
| :- | :- |
| **Session Expiration Hours** | Optional. Refer to [Configure Mercado Pago settings](#configure-mercado-pago-settings). |

<img src="https://mintcdn.com/payrails-42074109/DS81KC-NNGTwOcXz/images/docs/mercado-pago-image-03.png?fit=max&auto=format&n=DS81KC-NNGTwOcXz&q=85&s=0fb5f35a5b3027b2fa064f6295154161" alt="A screenshot showing the Mercado Pago session config fields." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/mercado-pago-image-03.png" />

***

### Payment methods

**In Payrails**

* Select **Card**, **Generic Redirect**, **Mercado Pago** or any combination. **Generic Redirect** and **Mercado Pago** send your customer to the Mercado Pago checkout.

<img src="https://mintcdn.com/payrails-42074109/DS81KC-NNGTwOcXz/images/docs/mercado-pago-image-04.png?fit=max&auto=format&n=DS81KC-NNGTwOcXz&q=85&s=294c2e9666fe8e40b80172dbeaba1874" alt="A screenshot showing the Mercado Pago payment method selection." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/mercado-pago-image-04.png" />

***

### Webhooks or notifications

<Info>
  Payrails uses provider webhooks or notifications to receive asynchronous
  payment status updates.
</Info>

<Warning>
  Create webhooks in the same mode (test or live) as your Payrails integration.
</Warning>

**In Payrails**

* Copy the **Notification URL** shown under **Account configuration** at the top of the integration form.

**In Mercado Pago**

1. In your Mercado Pago developer panel, go to **Webhooks** and select **Configure notifications**.
2. Paste the Payrails notification URL.
3. Select the **Payments** and **Orders** events, and save.
4. Copy the secret signature into the **HMAC** field in Payrails.

Mercado Pago has separate test and production webhook settings, so set up the webhook for the mode that matches your credentials. Payrails also sends its notification URL with every Mercado Pago checkout payment.

***

## Request fields for Mercado Pago

Send these fields in the [authorize request](/reference/authorizeaction) for card payments, in addition to the standard authorize fields. **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to Mercado Pago when you include them. For more about meta fields, refer to [Meta fields](/docs/orchestration/meta-fields).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Sent to Mercado Pago as the total amount and currency. Use the currency of your Mercado Pago country. |
| `meta.customer.email` | Required | Sent as the payer email. |
| `meta.order` | Required | Sent as the items and shipment. The lines, tax, discount and shipping must add up to `amount`. |
| `meta.order.softDescriptor` | Required | Sent as the description and statement descriptor. |
| `meta.customer.name`, `meta.customer.lastName` | Optional | Sent as the payer and card holder name. |
| `meta.customer.identityCardNumber`, `meta.customer.identityCardType` | Optional | Sent as the payer identification. `identityCardType` is `nationalId` (default), `passport`, `foreignId` or `tradeLicense`. |
| `meta.customer.phone` | Optional | Sent as the payer phone. |
| `meta.customer.createdAt` | Optional | Sent as the payer registration date. |
| `meta.order.billingAddress`, `meta.order.deliveryAddress` | Optional | Sent as the payer address and shipping address. Include `deliveryAddress.state` for Mercado Pago fraud checks. |
| `meta.order.lines[].categoryId` | Optional | Sent as the item category for fraud checks, for example `fashion`. |
| `meta.deviceId` | Optional | Sent as the device session ID for Mercado Pago fraud checks. |
| `meta.payerAuthenticationType`, `meta.payerIsPrimeUser`, `meta.payerIsFirstPurchaseOnline`, `meta.payerLastPurchase` | Optional | Sent as extra payer information for fraud checks. |
| `installments.count` | Optional | Sent as the number of installments. Defaults to 1. |
| `merchantReference` | Optional | Sent as the external reference. |

Mercado Pago card payments are captured straight away, so use instant capture in your workflow.

***

## Configure Mercado Pago settings

Some Mercado Pago integration settings change how Payrails processes your payments. The portal shows the same description when you hover over each setting.

| Setting | What it does |
| :- | :- |
| **Session Expiration Hours** | The number of hours before a Mercado Pago checkout session expires. After that, your customer can't complete the payment in that session. Defaults to 24. It applies to the **Generic Redirect** and **Mercado Pago** methods. |

***

## Enable the integration

**In Payrails**

* Select **Save account** to enable the integration.
* Confirm the integration shows as **Enabled**.

Your **Mercado Pago** integration is now ready to process payments.

***

## Next steps

1. Run a test card payment with your Mercado Pago test credentials.
2. Verify that:
   * The payment appears in Mercado Pago.
   * The payment status updates correctly in Payrails.
3. Once verified in test mode, repeat the setup with your live credentials.

→ Continue to: [Test a payment](/docs/orchestration/payment-acceptance/test-payments)


## Related topics

- [Mercado Pago](/docs/orchestration/payment-methods/mercadopago.md)
- [PagoEfectivo via Mercado Pago](/docs/orchestration/payment-methods/pagoefectivo/mercadopago.md)
- [Mercado Pago Checkout Pro](/docs/orchestration/payment-methods/mercadopago/mercadopago.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.