Preferences - Checkout customization - Mercado Pago Developers

Preference configurations

You can adapt the Checkout Pro integration to your business model by setting preference attributes.

If you offer high-value purchases, for example, you can accept payments with two credit cards or delete undesired payment methods for your operation.

Preference attribute settings also allow you to obtain business information and measure the effectiveness of your ads on platforms like Facebook and Google.

Example of complete preference

json

{
    "items": [
        {
            "id": "item-ID-1234",
            "title": "Mi producto",
            "currency_id": "ARS",
            "picture_url": "https://www.mercadopago.com/org-img/MP3/home/logomp3.gif",
            "description": "Descripción del Item",
            "category_id": "art",
            "quantity": 1,
            "unit_price": 75.76
        }
    ],
    "payer": {
        "name": "Juan",
        "surname": "Lopez",
        "email": "user@email.com",
        "phone": {
            "area_code": "11",
            "number": "4444-4444"
        },
        "identification": {
            "type": "DNI",
            "number": "12345678"
        },
        "address": {
            "street_name": "Street",
            "street_number": 123,
            "zip_code": "5700"
        }
    },
    "back_urls": {
        "success": "https://www.success.com",
        "failure": "http://www.failure.com",
        "pending": "http://www.pending.com"
    },
    "auto_return": "approved",
    "payment_methods": {
        "excluded_payment_methods": [
            {
                "id": "master"
            }
        ],
        "excluded_payment_types": [
            {
                "id": "ticket"
            }
        ],
        "installments": 12
    },
    "notification_url": "https://www.your-site.com/ipn",
    "statement_descriptor": "MYBUSINESS",
    "external_reference": "Reference_1234",
    "expires": true,
    "expiration_date_from": "2016-02-01T12:00:00.000-04:00",
    "expiration_date_to": "2016-02-28T12:00:00.000-04:00"
}

Define the desired payment methods

By default, all payment methods are offered in Checkout Pro. Through payment preference, you can configure a default payment method to be rendered, delete unwanted ones, or choose a maximum number of installments to be offered.

Preference attributeDescription
payment_methodsClass describing Checkout Pro's payment methods and attributes.
excluded_payment_typesMethod that excludes undesired payment methods for your operation, such as credit card, ticket, among others.
excluded_payment_methodsMethod that excludes specific credit and debit card brands, such as Visa, Mastercard, American Express, among others.
installmentsMethod that defines the maximum number of installments to be offered.
purposeBy indicating the value "wallet_purchase" in this method, Checkout Pro will only accept payments from registered users in Mercado Pago, with card and account balance.

For example:

          
<?php
$preference = new MercadoPago\Preference();
// ...
$preference->payment_methods = array(
  "excluded_payment_methods" => array(
    array("id" => "master")
  ),
  "excluded_payment_types" => array(
    array("id" => "ticket")
  ),
  "installments" => 12
);
// ...
?>

        
          
var preference = {}
preference = {
//...
"payment_methods": {
    "excluded_payment_methods": [
        {
            "id": "master"
        }
    ],
    "excluded_payment_types": [
        {
            "id": "ticket"
        }
    ],
    "installments": 12
	}
//...
}

        
          
PreferenceClient client = new PreferenceClient();
//...
List<PreferencePaymentMethodRequest> excludedPaymentMethods = new ArrayList<>();
excludedPaymentMethods.add(PreferencePaymentMethodRequest.builder().id("master").build());
excludedPaymentMethods.add(PreferencePaymentMethodRequest.builder().id("amex").build());

List<PreferencePaymentTypeRequest> excludedPaymentTypes = new ArrayList<>();
excludedPaymentTypes.add(PreferencePaymentTypeRequest.builder().id("ticket").build());

PreferencePaymentMethodsRequest paymentMethods =
   PreferencePaymentMethodsRequest.builder()
       .excludedPaymentMethods(excludedPaymentMethods)
       .excludedPaymentTypes(excludedPaymentTypes)
       .installments(12)
       .build();

PreferenceRequest request = PreferenceRequest.builder().paymentMethods(paymentMethods).build();

client.create(request);
//...

        
          
#...
preference_data = {
  # ...
  payment_methods: {
    excluded_payment_methods: [
      { id: 'master' }
    ],
    excluded_payment_types: [
      { id: 'ticket' }
    ],
    installments: 12
  }
  # ...
}
#...

        
          
var paymentMethods = new PreferencePaymentMethodsRequest
{
    ExcludedPaymentMethods = new List<PreferencePaymentMethodRequest>
    {
        new PreferencePaymentMethodRequest
        {
            Id = "master",
        },
    },
    ExcludedPaymentTypes = new List<PreferencePaymentTypeRequest>
    {
        new PreferencePaymentTypeRequest
        {
            Id = "ticket",
        },
    },
    Installments = 12,
};

var request = new PreferenceRequest
{
    // ...
    PaymentMethods = paymentMethods,
};

        
          
#...
preference_data = {
    "excluded_payment_methods": [
        { "id": "master" }
    ],
    "excluded_payment_types": [
        { "id": "ticket" }
    ],
    "installments": 12
}
#...

        

Accept payments with 2 credit cards

Pago 2 tarjetas

You can activate the option to offer payments with two credit cards from the Mercado Pago account.

To activate this payment option, go to Business Options and select the option Receive payments with 2 credit cards.

Config pago 2 tarjetas

Accept payments from registered users only

You can accept payments with the Mercado Pago wallet only from registered users, with a credit card, money in account, or Mercado Crédito.

This allows your customers to have their account information available instantly at the time of payment, such as their pre saved cards and addresses.

Important
By adding this option, you will not be able to receive payments from users who do not have a Mercado Pago or Mercado Livre account, as well as you will not be able to receive payments via cash or transfer.

To accept payments only from registered users, add the following attribute to your preferences:

json

"purpose": "wallet_purchase"

Once you complete the action, your preference should have a structure similar to the example below:

json

{
    "purpose": "wallet_purchase",
    "items": [
        {
            "title": "My product",
            "quantity": 1,
            "unit_price": 75.76
        }
    ],
}

Change the due date for cash payments

You can change the default expiration date for cash payments by sending the date_of_expiration field in the preference creation request. The date set by you must be between 1 day and 30 days from the date the payment is issued.

For example:

The date uses the ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssz

          
"date_of_expiration": "2020-05-30T23:59:59.000-04:00"

        
Note
The crediting period is between one day and two working days, depending on the chosen payment method. Therefore, we recommend setting the expiration date at least three days apart to ensure that payment is made.

Review the credit times according to each payment method to perform the configuration correctly.

Important
If the payment is made after the expiration date, the amount will be refunded in the payer's Mercado Pago account.

Enable binary mode

You can enable the binary mode if the business model requires payment approval to be instantaneous. This way, the payment can only be approved or declined.

The payment may be pending (if any action is required by the buyer) or processing (if a manual review is required) when the binary mode is disabled.

To enable it, just set the payment preference's binary_mode attribute to true:

json

"binary_mode": true
Important
Activating the binary mode simplifies the integration with Checkout Pro, but it can cause a decrease in the percentage rate of approved payments. That is because pending and in-processing payments will automatically be rejected by default.

Set an expiration date for your preferences

Set an expiration period for your payment preferences in the expires, expiration_date_from, and expiration_date_to attributes:

json

"expires": true,
"expiration_date_from": "2017-02-01T12:00:00.000-04:00",
"expiration_date_to": "2017-02-28T12:00:00.000-04:00"

Note that the date must follow the format ISO 8601: yyyy-MM-dd'T'HH:mm:ssz.

Send description on buyer card invoice

You can add a description for your business via the statement_descriptor attribute of the payment preferences, as shown in the example below:

json

"statement_descriptor": "MYBUSINESS"

Depending on the card brand, the description (attribute value) will appear on the buyer's card invoice.

Set a preference for multiple items

If you need to create a preference for more than one item, you must add them as a list, as shown in the example below:

          
<?php
  # Create a preference object
  $preference = new MercadoPago\Preference();
  # Create items in the preference
  $item1 = new MercadoPago\Item
  $item1->title = "Item de Prueba 1";
  $item1->quantity = 2;
  $item1->unit_price = 11.96;

  $item2= new MercadoPago\Item
  $item2->title = "Item de Prueba 2";
  $item2->quantity = 1;
  $item2->unit_price = 11.96;

  $preference->items = array($item1,$item2);
  # Save and post the preference
  $preference->save();
?>

        
          
// Set your preference
var preference = {
  items: [
      { title: 'Mi producto',
      quantity: 1,
      currency_id: 'ARS',
      unit_price: 75.56 },
	{ title: 'Mi producto 2’,
      quantity: 2,
      currency_id: 'ARS',
      unit_price: 96.56 }
    ]
};
// Create the preference
mercadopago.preferences.create(preference)
.then(function(preference){
  // This value replaces "$init_point$" string in your HTML
  global.init_point = preference.body.init_point;
}).catch(function(error){
  console.log(error);
});

        
          
// Create a preference object
PreferenceClient client = new PreferenceClient();
// Create items in the preference
List<PreferenceItemRequest> items = new ArrayList<>();

PreferenceItemRequest item1 =
   PreferenceItemRequest.builder()
       .id("1234")
       .title("Produto 1")
       .quantity(2)
       .currencyId("BRL")
       .unitPrice(new BigDecimal("100"))
       .build();   
PreferenceItemRequest item2 =
   PreferenceItemRequest.builder()
       .id("12")
       .title("Produto 2")
       .quantity(1)
       .currencyId("BRL")
       .unitPrice(new BigDecimal("100"))
       .build();

items.add(item1);
items.add(item2);

PreferenceRequest request = PreferenceRequest.builder().items(items).build();
// Save and post the preference
client.create(request);

        
          
sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')
# Create preference data with items
preference_data = {
  items: [
    {
      title: 'Mi producto 1',
      quantity: 1,
      currency_id: 'ARS',
      unit_price: 75.56
    },
    {
      title: 'Mi producto 2',
      quantity: 2,
      currency_id: 'ARS',
      unit_price: 96.56
    }
  ]
}

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

        
          
// Create the request with multiples items
var request = new PreferenceRequest
{
    Items = new List<PreferenceItemRequest>
    {
        new PreferenceItemRequest
        {
            Title = "My product 1",
            Quantity = 1,
            CurrencyId = "ARS",
            UnitPrice = 75.56m,
        },
        new PreferenceItemRequest
        {
            Title = "My product 2",
            Quantity = 2,
            CurrencyId = "ARS",
            UnitPrice = 96.56m,
        },
        // ...
    },
};

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

// Create the preference
Preference preference = await client.CreateAsync(request);

        
          
# Create items in the preference
preference_data = {
    "items": [
        {
            "title": "Mi producto",
            "quantity": 1,
            "unit_price": 75.56
        },
        {
            "title": "Mi producto2",
            "quantity": 2,
            "unit_price": 96.56
        }
    ]
}

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

        
          
curl -X POST \
  'https://api.mercadopago.com/checkout/preferences' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -H 'Authorization: Bearer PROD_ACCESS_TOKEN' \
  -d '{
	"items": [
	{
		"id_product":1,
		"quantity":1,
		"unit_price": 234.33,
		"titulo":"Mi producto"
	},
	{
		"id_product":2,
		"quantity":2,
		"unit_price": 255.33,
		"titulo":"Mi producto 2"
	}
]
}'

        

Keep in mind that the total value of the preference will be the sum of the unit price value of each item listed.

Show shipping cost

If your website already calculates the shipment value, you can display it separately from the total amount at the time of payment.

To configure such a scenario, add the item shipments with the value you want to charge in the cost attribute and the value not_specified in the mode attribute:

json

{
    "shipments":{
        "cost": 1000,
        "mode": "not_specified",
  }
}

Optimize your ad conversion

We know it's important to maximize the effectiveness and findability of your ads.

Therefore, we offer the possibility to integrate Checkout Pro with the Facebook Ads and Google Ads platforms to associate payments to your business campaigns.

Note
Only payments approved instantly with credit and debit cards, cash on Mercado Pago or Mercado Credits will be associated.

Integrate Checkout Pro with Facebook Ads

When creating a preference, you can associate it with a pixel (identifier) for tracking Facebook Ads conversions:

Add the following code in the preference and replace the pixel_id value with your identifier.

          
<?php
  // Create a preference object
  $preference = new MercadoPago\Preference();

  // Associate your Facebook Pixel
  $preference->tracks = array(
    array(
      'type' => 'facebook_ad',
      'values'=> array(
        'pixel_id' => 'PIXEL_ID'
      )
    )
  );

  // ...
  // Save and post the preference
  $preference->save();
?>

        

Add the following code in the preference and replace the pixel_id value with its identifier.

          
  // Create a preference object
var preference = {

  // Associate your Facebook Pixel
  tracks: [
        {
          type: "facebook_ad",
          values: {
            "pixel_id": 'PIXEL_ID'
          }
        }
      ]
  //...
};

        

Add the following code in the preference and replace the pixel_id value with its identifier.

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

  // Associate your Facebook Pixel
List<PreferenceTrackRequest> tracks = new ArrayList<>();
PreferenceTrackRequest trackFacebook = PreferenceTrackRequest.builder()
   .type("facebook_ad")
   .values(PreferenceTrackValuesRequest.builder().pixelId("PIXEL_ID").build())
   .build();
tracks.add(trackFacebook);

PreferenceRequest request = PreferenceRequest.builder().tracks(tracks).build();

  // Save and post the preference
client.create(request);

        

Add the following code in the preference and replace the pixel_id value with its identifier.

          
// Associate your Facebook pixel
var tracks = new List<PreferenceTrackRequest>
{
    new PreferenceTrackRequest
    {
        Type = "facebook_ad",
        Values = new PreferenceTrackValuesRequest
        {
            PixelId = "PIXEL_ID",
        },
    },
};

var request = new PreferenceRequest
{
    // ...
    Tracks = tracks,
};

var client = new PreferenceClient();
Preference preference = await client.CreateAsync(request);

        

Add the following code in the preference and replace the pixel_id value with its identifier.

          
# Associate your Facebook Pixel
preference_data = {
    # ...
    "tracks": [
        {
            "type": "facebook_ad",
            "values": {
                "pixel_id": "PIXEL_ID"
            }
        }
    ]
}

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

        

Add the following code in the preference and replace the pixel_id value with its identifier.

          

curl -X POST \
  'https://api.mercadopago.com/checkout/preferences' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -H 'Authorization: Bearer PROD_ACCESS_TOKEN' \
  -d '{
	"items": [
        {
            "id_product":1,
            "quantity":1,
            "unit_price": 234.33,
            "titulo":"Mi producto"
        }
    ],
    "tracks": [
        {
            "type": "facebook_ad",
            "values": {
                "pixel_id": "PIXEL_ID"
            }
        }
    ]
}'

        

When your action is complete, a Purchase event will be associated with the pixel specified in the code everytime a payment forwarded by your ad is approved in Checkout Pro.

Note
For now, it is only possible to configure a single pixel per preference. Test your integration working using the Chrome Facebook Pixel Helper extension. For more information, visit the official Facebook website.

Integrate Checkout Pro with Google Ads

When creating a preference, you can associate it with a tag (identifier) for tracking Google Ads conversions:

Add the code in the preference and replace the CONVERSION_ID and CONVERSION_LABEL values with the data from your tag.

          

<?php
  // Create a preference object
  $preference = new MercadoPago\Preference();
 
  // Associate your tag
  $preference->tracks = array(
    array(
        'type' => 'google_ad',
        'values' => array(
          'conversion_id' => 'CONVERSION_ID',
          'conversion_label' => 'CONVERSION_LABEL'
        )
    )
  );

  ...
  // Save and post the preference
  $preference->save();
?>

        

Add the code in the preference and replace the CONVERSION_ID and CONVERSION_LABEL values with the data from your tag.

          
// Configure your preference
var preference = {

 // Associate your tag
  tracks: [
        {
            type: "google_ad",
            values: {
              conversion_id: "CONVERSION_ID",
              conversion_label: "CONVERSION_LABEL"
            }
        }
      ]
  ...
};

        

Add the code in the preference and replace the CONVERSION_ID and CONVERSION_LABEL values with the data from your tag.

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

  // Associate your tag
List<PreferenceTrackRequest> tracks = new ArrayList<>();
PreferenceTrackRequest trackGoogle =
   PreferenceTrackRequest.builder()
       .type("google_ad")
       .values(
           PreferenceTrackValuesRequest.builder()
               .conversionId("CONVERSION_ID")
               .conversionLabel("CONVERSION_LABEL")
               .build())
       .build();
tracks.add(trackGoogle);

PreferenceRequest request = PreferenceRequest.builder().tracks(tracks).build();

  // Save and post the preference
client.create(request);

        

Add the code in the preference and replace the CONVERSION_ID and CONVERSION_LABEL values with the data from your tag.

          
// Associate your tag
var tracks = new List<PreferenceTrackRequest>
{
    new PreferenceTrackRequest
    {
        Type = "facebook_ad",
        Values = new PreferenceTrackValuesRequest
        {
            ConversionId = "CONVERSION_ID",
            ConversionLabel = "CONVERSION_LABEL",
        },
    },
};

var request = new PreferenceRequest
{
    // ...
    Tracks = tracks,
};

var client = new PreferenceClient();
Preference preference = await client.CreateAsync(request);

        

Add the code in the preference and replace the CONVERSION_ID and CONVERSION_LABEL values with the data from your tag.

          
# Associate your tag
preference_data = {
    # ...
    "tracks": [
        {
            "type": "google_ad",
            "values": {
                "conversion_id": "CONVERSION_ID",
                "conversion_label": "CONVERSION_LABEL"
            }
        }
    ]
}

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

        

Add the code in the preference and replace the CONVERSION_ID and CONVERSION_LABEL values with the data from your tag.

          
curl -X POST \
  'https://api.mercadopago.com/checkout/preferences' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -H 'Authorization: Bearer PROD_ACCESS_TOKEN' \
  -d '{
	"items": [
        {
            "id_product":1,
            "quantity":1,
            "unit_price": 234.33,
            "titulo":"Mi producto"
        }
    ],
    "tracks": [
        {
            "type": "google_ad",
            "values": {
                "conversion_id", "CONVERSION_ID",
                "conversion_label", "CONVERSION_LABEL"
            }
        }
    ]
}'

        

When your action is complete, a conversion will be associated with the specified tag everytime a payment forwarded for your ad is approved.

Note
For now, it is only possible to configure a single tag per preference. For more information about Google Ads conversion tags, visit the official Google website.

Work with business metrics

Our certified members in the Dev Program can obtain business metrics from Checkout Pro.

Use headers in your payment preference to work with metrics, adding the identification code according to the desired scenario (it is not mandatory to complete the three fields mentioned below):

HeaderCode TypeIdentifier
x-integrator-idIntegratorFor programmers or agencies that perform the integration.
x-platform-idPlatformFor platforms or modules that offer Mercado Pago in their solutions.
x-corporation-idCorporationsFor accounts associated with a seller account or an economic group.
Note
Remember to add the integrator_id it to your integrations to receive additional benefits of the program. You can find your integrator_id in your developer Dashboard.

Add the identification codes and replace the values according to the desired scenario: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.

          
MercadoPago\SDK::setPlatformId("PLATFORM_ID");
MercadoPago\SDK::setIntegratorId("INTEGRATOR_ID");
MercadoPago\SDK::setCorporationId("CORPORATION_ID");

        

Add the identification codes and replace the values according to the desired scenario: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.

          
mercadopago.configure({
    platform_id: 'PLATFORM_ID',
    integrator_id: 'INTEGRATOR_ID',
    corporation_id: 'CORPORATION_ID'
});

        

Add the identification codes and replace the values according to the desired scenario: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.

          
MercadoPago.SDK.setPlatformId("PLATFORM_ID");
MercadoPago.SDK.setIntegratorId("INTEGRATOR_ID");
MercadoPago.SDK.setCorporationId("CORPORATION_ID");

        

Add the identification codes and replace the values according to the desired scenario: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.

          
request_options = Mercadopago::RequestOptions.new()
request_options.platform_id = 'PLATFORM_ID'
request_options.integrator_id = 'INTEGRATOR_ID'
request_options.corporation_id = 'CORPORATION_ID'

sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN', request_options: request_options)

        

Add the identification codes and replace the values according to the desired scenario: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.

          
MercadoPagoConfig.PlatformId    = "PLATFORM_ID";
MercadoPagoConfig.IntegratorId  = "INTEGRATOR_ID";
MercadoPagoConfig.CorporationId = "CORPORATION_ID";

        

Add the identification codes and replace the values according to the desired scenario: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.

          
import mercadopago
from mercadopago.config import RequestOptions

request_options = RequestOptions(
    corporation_id="CORPORATION_ID",
    integrator_id="INTEGRATOR_ID",
    platform_id="PLATFORM_ID"
)
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN", request_options=request_options)

        

Add the identification codes and replace the values according to the desired scenario: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.

          
curl -X POST \
'https://api.mercadopago.com/checkout/preferences' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'x-corporation-id: CORPORATION_ID \
  -H 'x-integrator-id: INTEGRATOR_ID \
  -H 'x-platform-id: PLATFORM_ID \
  -H 'Authorization: Bearer PROD_ACCESS_TOKEN' \
  -d '{
    "items": [
       ...
       
    ],
    ...
}'