PagoEfectivo via Mercado Pago

Accept PagoEfectivo payments from customers in Peru with Mercado Pago as the payment service provider (PSP). The customer selects Mercado Pago in your checkout, goes to the Mercado Pago hosted checkout and picks PagoEfectivo there. The customer then gets a payment code (CIP) to pay at a bank, at an agent, or through online banking. Payrails records the payment as PagoEfectivo once Mercado Pago reports the method the customer used.

Supported workflows

Before you begin

Complete these steps before you send your first PagoEfectivo payment through Mercado Pago:

Set up a Mercado Pago integration in your workspace with your Mercado Pago access token and HMAC key. To add Mercado Pago to your Payrails Portal, contact your Payrails account team.
Ask Mercado Pago to enable PagoEfectivo on your Mercado Pago account for Peru.
In the Payrails Portal, go to Settings → Integrations, open your Mercado Pago integration, select Mercado Pago under Payment methods, and save.
Add Mercado Pago as a payment option in your workflow.

Request fields for Mercado Pago

Send these fields in the authorize request, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to the PSP when you include them.

Field	Status	Description
`amount.currency`	Required	Send `PEN`. Mercado Pago offers PagoEfectivo on its Peru checkout, and Payrails picks the Peru site from the currency.
`returnInfo.success`	Required	A full URL. The customer returns here after a successful payment.
`returnInfo.error`	Required	A full URL. The customer returns here after a failed payment.
`meta.customer`	Required	The customer object. Payrails builds the Mercado Pago payer from it.
`meta.customer.email`	Required	Sent to Mercado Pago as the payer email. Mercado Pago links the PagoEfectivo payment to this email.
`meta.order`	Required	The order object. Payrails builds the Mercado Pago items from it.
`meta.order.lines`	Required	One or more order lines, each with `id`, `name`, and `unitPrice` and `quantity` or `total`. The lines must add up to the payment amount. Send `meta.order.total` instead when you don’t send lines.
`meta.customer.name`	Optional	Sent to Mercado Pago as the payer first name.
`meta.customer.lastName`	Optional	Sent to Mercado Pago as the payer surname.
`meta.customer.identityCardNumber`	Optional	The customer’s document number. Sent to Mercado Pago as the payer identification.
`meta.customer.identityCardType`	Optional	Leave it empty for a DNI. Send `tradeLicense` for a RUC or `foreignId` for a foreigner identity card.
`meta.customer.phone`	Optional	Sent to Mercado Pago as the payer phone. `countryCode` becomes the area code.
`meta.customer.createdAt`	Optional	The date the customer opened their account, in RFC 3339 format. For a guest order, send the order date.
`meta.order.lines[].categoryId`	Optional	The Mercado Pago item category.
`meta.order.lines[].description`	Optional	Sent to Mercado Pago as the item description.
`meta.order.billingAddress`	Optional	Sent to Mercado Pago as the payer address: `postalCode`, `street` and `doorNumber`.
`meta.order.deliveryAddress`	Optional	Sent to Mercado Pago as the shipping address.
`meta.order.softDescriptor`	Optional	Sent to Mercado Pago as the statement descriptor.

Authorize a PagoEfectivo payment

Call authorize a payment with mercadoPago as the paymentMethodCode and hpp as the integrationType. The response includes the redirect to the Mercado Pago hosted checkout, where the customer picks PagoEfectivo.

Authorize request

{
  "amount": {
    "value": "100.00",
    "currency": "PEN"
  },
  "paymentComposition": [
    {
      "integrationType": "hpp",
      "paymentMethodCode": "mercadoPago",
      "amount": {
        "value": "100.00",
        "currency": "PEN"
      }
    }
  ],
  "meta": {
    "customer": {
      "name": "Carlos",
      "lastName": "Quispe",
      "email": "carlos.quispe@example.com",
      "identityCardNumber": "12345678",
      "country": {
        "code": "PE"
      }
    },
    "order": {
      "lines": [
        {
          "id": "sku-2001",
          "name": "Running shoes",
          "quantity": 1,
          "unitPrice": {
            "value": "100.00",
            "currency": "PEN"
          }
        }
      ]
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}

The payment stays pending until the customer pays the code. Confirm the result through webhook notifications or the execution status before you fulfill the order.

How Mercado Pago handles PagoEfectivo

Payrails creates a Mercado Pago checkout session for each authorize request. The customer picks the payment method on the Mercado Pago page, and can pick PagoEfectivo when Mercado Pago offers it for the payment.
After the customer picks PagoEfectivo, the Mercado Pago page shows the payment code. The customer can pay it online or note it and pay at a bank or agent.
The payment stays pending until the customer pays the code. Treat the pending notification as a reserved order.
When Mercado Pago reports the payment, Payrails updates its payment method from mercadoPago to pagoEfectivo.
The checkout session stays open for the Session Expiration Hours set on your Mercado Pago integration, or 24 hours by default.
Payrails captures Mercado Pago payments immediately, so a successful payment is final. To return funds, refund the payment. Mercado Pago returns the money to the PagoEfectivo account linked to the customer’s email.
Payrails sends your merchantReference to Mercado Pago as the external reference of the payment.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

PagoEfectivo via Mercado Pago

Supported workflows

Before you begin

Request fields for Mercado Pago

Authorize a PagoEfectivo payment

How Mercado Pago handles PagoEfectivo

​Supported workflows

​Before you begin

​Request fields for Mercado Pago

​Authorize a PagoEfectivo payment

​How Mercado Pago handles PagoEfectivo

Supported workflows

Before you begin

Request fields for Mercado Pago

Authorize a PagoEfectivo payment

How Mercado Pago handles PagoEfectivo