Mercado Pago Wallet - Checkout customization - Mercado Pago Developers
Which documentation are you looking for?

Do not know how to start integrating? 

Check the first steps

Mercado Pago Wallet

The option to pay with Mercado Pago Wallet, by default, is presented in all Mercado Pago Checkouts in combination with guest user payments (no login).

This option allows users registered in Mercado Pago and/or Mercado Livre to log in and use the available methods to make their payments, in addition to being able to include new payment options, such as credit cards.

It is possible to pay with card, available balance and installments without card in a safe and optimized environment, increasing the chances of converting sales, in addition to allowing the seller to only offer payments with wallet. With this, the option to pay without logging in will not exist, however, it will contribute to an increase in the conversion of payments.

By adding this option, it will not be possible to receive payments from users not registered in Mercado Pago, as well as you will not be able to receive payments via cash or bank transfer.

Follow the steps below to configure the Mercado Pago Wallet as a payment method.

Create preference


If you are a user and want all your payments to be made via Wallet, you can determine this via an attribute in the preferences API. To create a preference, use one of the SDKs below.

In addition to the SDKs, it is also possible to create a preference through the preferences API. For that, send a POST with the parameter purpose and the value wallet_purchase to the endpoint /checkout/preferences and execute the request or, if you prefer, use one of the SDKs below.

Wallet mode works by adding the purpose attribute to the preference.

   $client = new PreferenceClient();
   $preference = $client->create([
          "items"=> array(
              "title" => "My product",
              "description" => "Test product",
              "picture_url" => "",
              "category_id" => "electronics",
              "quantity" => 1,
              "currency_id" => "BRL",
              "unit_price" => 100
          "purpose"=> "wallet_purchase"
  echo implode($preference);


Wallet mode works by adding the purpose attribute to the preference.

const client = new MercadoPagoConfig({ accessToken: '<ACCESS_TOKEN>' });

const preference = new Preference(client);

  body: {
    items: [
        id: '<ID>',
        title: '<title>',
        quantity: 1,
        unit_price: 100
    purpose: "wallet_purchase",


Wallet mode works by adding the purpose attribute to the preference.

// Create a preference object
PreferenceClient client = new PreferenceClient();

// Create an item in the preference
PreferenceItemRequest item =
.title("My product")
.unitPrice(new BigDecimal("75"))

List<PreferenceItemRequest> items = new ArrayList<>();

PreferenceRequest request =



Wallet mode works by adding the purpose attribute to the preference.

# Create a preference object
preference_data = {
items: [
title: 'My product',
unit_price: 100,
quantity: 1
purpose: 'wallet_purchase'
preference_response = sdk.preference.create(preference_data)
preference = preference_response[:response]

# This value will replace the string "<%= @preference_id %>" in your HTML
@preference_id = preference['id']


Wallet mode works by adding the purpose attribute to the preference.

// Create the preference request object
var request = new PreferenceRequest
Items = new List<PreferenceItemRequest>
new PreferenceItemRequest
Title = "My product,
quantity = 1,
CurrencyId = "ARS",
UnitPrice = 75m,
Purpose = "wallet_purchase",
// Create the preference
var client = new PreferenceClient();
Preference preference = await client.CreateAsync(request);

preference_data = {
"items": [
"title": "My product",
"unit_price": 100,
"quantity": 1
"purpose": "wallet_purchase"

preference_response = sdk.preference().create(preference_data)
preference = preference_response["response"]


Add checkout


The steps to configure the Mercado Pago Wallet (client-side) are the same as those presented in this section.