Mercado Pago

Who should use this guideThis guide is intended for merchants who:

Use Payrails as a payment orchestrator
Use Mercado Pago for cards or Mercado Pago checkout methods such as Yape and PagoEfectivo
Have access to your Mercado Pago developer panel

Create a Mercado Pago integration in Payrails

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

About workspacesWorkspaces 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.

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.

A screenshot showing Mercado Pago selected as the provider.

Step 3: Configure your Mercado Pago integration

What you’ll need from Mercado PagoBefore 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.

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.

A screenshot showing the integration instance name field.

Credentials

In Mercado Pago

In your Mercado Pago developer panel, open your application and go to General Information.
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.

A screenshot showing the Mercado Pago credential fields.

Session Configs

In Payrails

Field	Value
Session Expiration Hours	Optional. Refer to Configure Mercado Pago settings.

A screenshot showing the Mercado Pago session config fields.

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.

A screenshot showing the Mercado Pago payment method selection.

Webhooks or notifications

Payrails uses provider webhooks or notifications to receive asynchronous payment status updates.

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

In Payrails

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

In Mercado Pago

In your Mercado Pago developer panel, go to Webhooks and select Configure notifications.
Paste the Payrails notification URL.
Select the Payments and Orders events, and save.
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 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.

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

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

→ Continue to: Test a payment

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Create a Mercado Pago integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider