Other functionalities
You can adapt the integration to your business by adding attributes in the preference. There is a lot of details in a preference that can be set, but always keep in mind what your business needs.
If you offer purchases of high amounts, for example, you can accept payments with two credit cards or, also, exclude payment methods that you do not want to accept.
You can get business information using preference. And you can also measure advertising effectiveness and track ads by integration to Facebook Pixel or associate your Google Ads.
Example of a complete preference
json
{
"items": [
{
"id": "item-ID-1234",
"title": "Mi producto",
"currency_id": "BRL",
"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"
}
Attributes for the preference
Definition of Payment Methods
By default, all payment methods are offered. If you want to exclude any, it can be done from the payment preference. You can also set a payment method to appear by default or define the maximum number of installments to offer.
Attribute | Description |
---|---|
payment_methods | Class that describes the attributes and methods of payment methods. |
excluded_payment_methods | Method that excludes by specific payment methods: Visa, Mastercard or American Express, among others. |
excluded_payment_types | Method that excludes by type of payment method: cash, credit or debit cards. |
installments | Method that defines the amount of maximum number of installments to offer. |
purpose | When the "wallet purchase" value is indicated, Checkout will accept payments exclusively from Mercado Pago registered users, with card and account balance. |
<?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
}
//...
}
Preference preference = new Preference();
//...
PaymentMethods paymentMethods = new PaymentMethods();
paymentMethods.setExcludedPaymentMethods("master", "amex");
paymentMethods.setExcludedPaymentTypes("ticket");
paymentMethods.setInstallments(12);
preference.setPaymentMethods(paymentMethods);
//...
preference = MercadoPago::Preference.new
#...
preference.payment_methods = {
excluded_payment_methods: [id: "master"],
excluded_payment_types: [id: "ticket"],
installments: 12
}
#...
Preference preference = new Preference();
PaymentMethods paymentmethods = new PaymentMethods();
List<PaymentMethod> excludedPaymentMethod = new List<PaymentMethod>();
excludedPaymentMethod.Add(new PaymentMethod()
{
Id = "master"
});
paymentmethods.excludedPaymentType = excludedPaymentMethod;
List<PaymentType> ExcludedPaymentType = new List<PaymentType>();
excludedPaymentType.Add(new PaymentType()
{
Id = "ticket"
});
paymentmethods.ExcludedPaymentTypes = excludedPaymentType;
paymentmethods.Installments = 12;
Expiration date of cash payment
If you want, you can change the default due date of a cash payment by sending the date_of_expiration
field in the preference creation request. The configured date must be between 1 and 30 days from the preference creation date.
"date_of_expiration": "2020-05-30T23:59:59.000-04:00"
The deadline for approval of the cash payment is between 1 and 2 working days according to the payment method. Therefore, we recommend that you set the due date with at least 3 days to ensure that payment is made.
Check credit times by payment method when configuring.
Binary Mode
You can activate the binary mode if the business model requires payment approval to be instantaneous. This way, payment can only be approved or declined.
In case the binary mode is not activated, the payment may be pending (in case of requiring any action by the buyer) or in process (if a manual review is necessary).
To activate it, you only have to set the binary_mode
attribute of the payment preference to true
:
json
"binary_mode": true
Validity of Preferences
If you want to enable the payment of a preference with a certain duration, you can activate a period of validity or complete directly with the following 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"
Description in the card summary
You can send the name of your business in the attribute statement_descriptor
in this way in the summary of your payer's card the name of your business is shown and in this way the payer knows where made the purchase.
json
"statement_descriptor": "MYBUSINESS"
Multiple Items
If you need to create a preference for more than one item, you should only add them as a list within items. Keep in mind that the total amount of the preference will be the sum of the amount for the unit price of each item.
<?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: 'BRL',
unit_price: 75.56 },
{ title: 'Mi producto 2’,
quantity: 2,
currency_id: 'BRL',
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
Preference preference = new Preference();
// Create items in the preference
Item item1 = new Item();
item1.setId("1234")
.setTitle("Producto 1")
.setQuantity(2)
.setCurrencyId("BRL")
.setUnitPrice((float) 75.56);
Item item2 = new Item();
item2.setId("12")
.setTitle("Producto 2")
.setQuantity(1)
.setCurrencyId("BRL")
.setUnitPrice((float) 75.56);
preference.appendItem(item1, item2);
// Save and post the preference
preference.save();
// Create items in the preference
item = MercadoPago::Item.new({
title: "Mi producto",
quantity: 1,
unit_price: 75.56
})
item2 = MercadoPago::Item.new({
title: "Mi producto2”,
quantity: 2,
unit_price: 96.56
})
// Create a preference object
preference = MercadoPago::Preference.new({
items: [item, item2]
})
preference.save()
// Create a preference object
Preference preference = new Preference();
// Create items in the preference
reference.Items.Add(
new Item()
{
Title = "Mi producto",
Quantity = 1,
CurrencyId = CurrencyId.BRL,
UnitPrice = (decimal)75.56
},
new Item()
{
Title = "Mi producto2”,
Quantity = 2,
CurrencyId = CurrencyId.BRL,
UnitPrice = (decimal)96.56
}
);
preference.Save()"
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"
}
]
}'
Accept payments from registered users only
You can accept payments with the Mercado Pago wallet exclusively from registered users, with cards, money in account and Mercado Crédito.
This allows your customers to have their account information available instantly, such as their saved cards and addresses.
To accept payments from registered users only, add the following attribute to your preferences:
json
"purpose": "wallet_purchase"
In doing so, your preference would be as follows:
json
{
"purpose": "wallet_purchase",
"items": [
{
"title": "My product",
"quantity": 1,
"unit_price": 75.76
}
],
}
Shipment cost
If you already have estimated shipping from your website, you can define the amount and show it separately from the total when offering payment.
To configure it, add the node shipments
with the value of the amount you want to charge in the attribute cost
, and the value not_specified
in the attribute mode
.
json
{
"shipments":{
"cost": 1000,
"mode": "not_specified",
}
}
Optimize Ad Conversion
We know it’s important to maximize your ads effectiveness. For this reason, we offer you the choice integrating Checkout Pro with Facebook Ads and Google Ads platforms, in order to associate payments to your campaigns.
Associate a Facebook Pixel
When creating a preference, associate the corresponding identifier to your Facebook Pixel as follows:
Add the code in the preference and replace the value PIXEL_ID 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 code in the preference and replace the value PIXEL_ID with your identifier.
// Create a preference object
var preference = {
// Associate your Facebook Pixel
tracks: [
{
type: "facebook_ad",
values: {
"pixel_id": 'PIXEL_ID'
}
}
]
//...
};
Add the code in the preference and replace the value PIXEL_ID with your identifier.
// Create a preference object
Preference preference = new Preference();
// Associate your Facebook Pixel
Track trackFacebook = new Track()
.setType("facebook_ad")
.setValues(new TrackValues()
.setPixelId("PIXEL_ID")
);
Preference preference = new Preference()
.appendTrack(trackFacebook);
// Save and post the preference
preference.save();
Add the code in the preference and replace the value PIXEL_ID with your identifier.
List<Track> tracks = new List<Track>();
// Associate your Facebook Pixel
tracks.Add(
new Track
{
Type = "facebook_ad",
Values = new JObject
{
{ "pixel_id", "PIXEL_ID" }
}
});
MercadoPago.Resources.Preference preference = new MercadoPago.Resources.Preference
{
// ...
Tracks = tracks
};
preference.Save();
Add the code in the preference and replace the value PIXEL_ID with your 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"
}
}
]
}'
Once set up, you’ll see a Purchase
event for the specified Pixel everytime a payment is approved through your Checkout Pro.
Associate a Google Ads tag
When creating a preference, you can associate a Google Ads conversion tracking tag as follows:
Add the code in the preference and replace the values CONVERSION_ID y CONVERSION_LABEL with your tag data.
<?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 values CONVERSION_ID y CONVERSION_LABEL with your tag data.
// 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 values CONVERSION_ID y CONVERSION_LABEL with your tag data.
// Create a preference object
Preference preference = new Preference();
// Associate your tag
Track trackGoogle = new Track()
.setType("google_ad")
.setValues(new TrackValues()
.setConversionId("CONVERSION_ID")
.setConversionLabel("CONVERSION_LABEL")
);
Preference preference = new Preference()
.appendTrack(Google);
// Save and post the preference
preference.save();
Add the code in the preference and replace the values CONVERSION_ID y CONVERSION_LABEL with your tag data.
List<Track> tracks = new List<Track>();
// Associate your tag
tracks.Add(
new Track
{
Type = "google_ad",
Values = new JObject
{
{ "conversion_id", "CONVERSION_ID" },
{ "conversion_label", "CONVERSION_LABEL" }
}
});
MercadoPago.Resources.Preference preference = new MercadoPago.Resources.Preference
{
...
Tracks = tracks
};
preference.Save();
Add the code in the preference and replace the values CONVERSION_ID y CONVERSION_LABEL with your tag data.
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"
}
}
]
}'
Once set up, you’ll see a conversion associated to the configured label everytime a payment is approved through your Checkout Pro.
Get information about your business
Our Partners can obtain business metrics. To get business metrics, use headers
in your preference. You should only add identification codes, as applicable. It is not required to complete the three fields mentioned.
Header | Code Type | Identifiers |
---|---|---|
x-integrator-id | Integrator | For developers or agencies that conducted the integration. |
x-platform-id | Platform | For the platforms or modules that offer Mercado Pago in their solutions. |
x-corporation-id | Corporations | For accounts associated with a seller's account or economic group. |
Add identification codes and replace any value that you wish: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.
MercadoPago\SDK::setPlatformId("PLATFORM_ID");
MercadoPago\SDK::setIntegratorId("INTEGRATOR_ID");
MercadoPago\SDK::setCorporationId("CORPORATION_ID");
Add identification codes and replace any value that you wish: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.
mercadopago.configure({
platform_id: 'PLATFORM_ID',
integrator_id: 'INTEGRATOR_ID',
corporation_id: 'CORPORATION_ID'
});
Add identification codes and replace any value that you wish: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.
MercadoPago.SDK.setPlatformId("PLATFORM_ID");
MercadoPago.SDK.setIntegratorId("INTEGRATOR_ID");
MercadoPago.SDK.setCorporationId("CORPORATION_ID");
Add identification codes and replace any value that you wish: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.
$mp.set_platform_id("PLATFORM_ID")
$mp.set_integrator_id("INTERATOR_ID")
$mp.set_corporation_id("CORPORATION_ID")
Add identification codes and replace any value that you wish: CORPORATION_ID, INTEGRATOR_ID and PLATFORM_ID.
MercadoPago.SDK.PlatformId = "PLATFORM_ID";
MercadoPago.SDK.IntegratorId = "INTEGRATOR_ID";
MercadoPago.SDK.CorporationId = "CORPORATION_ID";
Add identification codes and replace any value that you wish: 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": [
...
],
...
}'
Payments with Two Credit Cards
You can enable the option to offer to pay with two credit cards from the Mercado Pago account. To activate the payment option, go to your business options and choose the option Receive payments with 2 credit cards.
The date uses the ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssz