Yape via Mercado Pago

Accept Yape 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, picks Yape there and approves the payment with their Yape account. Payrails records the payment as Yape once Mercado Pago reports the method the customer used.

Supported workflows

Before you begin

Complete these steps before you send your first Yape 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 Yape 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 Yape 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.
`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 Yape 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 Yape.

Authorize request

{
  "amount": {
    "value": "45.00",
    "currency": "PEN"
  },
  "paymentComposition": [
    {
      "integrationType": "hpp",
      "paymentMethodCode": "mercadoPago",
      "amount": {
        "value": "45.00",
        "currency": "PEN"
      }
    }
  ],
  "meta": {
    "customer": {
      "name": "Lucía",
      "lastName": "Quispe",
      "email": "lucia.quispe@example.com",
      "identityCardNumber": "43451826",
      "country": {
        "code": "PE"
      }
    },
    "order": {
      "lines": [
        {
          "id": "sku-1001",
          "name": "Polo shirt",
          "quantity": 1,
          "unitPrice": {
            "value": "45.00",
            "currency": "PEN"
          }
        }
      ]
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}

After the customer approves the payment, they return to your success or error URL. Confirm the result through webhook notifications or the execution status before you fulfill the order.

How Mercado Pago handles Yape

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 Yape when Mercado Pago offers it for the payment.
On the Yape screen, the customer enters the phone number of their Yape account and the approval code from the Yape app.
When Mercado Pago reports the payment, Payrails updates its payment method from mercadoPago to yape.
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 customer’s Yape account.
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

Supported workflows

Before you begin

Request fields for Mercado Pago

Authorize a Yape payment

How Mercado Pago handles Yape

​Supported workflows

​Before you begin

​Request fields for Mercado Pago

​Authorize a Yape payment

​How Mercado Pago handles Yape

Supported workflows

Before you begin

Request fields for Mercado Pago

Authorize a Yape payment

How Mercado Pago handles Yape