Configurações de preferência

Você pode adaptar a integração do Checkout Pro ao seu modelo negócio configurando atributos de preferência.

Se você oferece compras de valores altos, por exemplo, pode excluir meios de pagamento indesejados para a sua operação.

As configurações dos atributos de preferência te permitem ainda obter informações de negócio e mensurar a efetividade dos seus anúncios em plataformas como Facebook e Google.

Exemplo de preferência completa

{
    "items": [
        {
            "id": "item-ID-1234",
            "title": "Meu produto",
            "currency_id": "CLP",
            "picture_url": "https://www.mercadopago.com/org-img/MP3/home/logomp3.gif",
            "description": "Descrição do Item",
            "category_id": "art",
            "quantity": 1,
            "unit_price": 75.76
        }
    ],
    "payer": {
        "name": "João",
        "surname": "Silva",
        "email": "user@email.com",
        "phone": {
            "area_code": "11",
            "number": "4444-4444"
        },
        "identification": {
            "type": "CPF",
            "number": "19119119100"
        },
        "address": {
            "street_name": "Street",
            "street_number": 123,
            "zip_code": "06233200"
        }
    },
    "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": "MEUNEGOCIO",
    "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"
}

Defina os meios de pagamento desejados

Por padrão, todos os meios de pagamento são oferecidos no Checkout Pro. Por meio da preferência de pagamento, você pode configurar um meio de pagamento padrão para ser renderizado, excluir algum indesejado, ou ainda escolher um número máximo de parcelas a serem ofertadas.

Atributo de preferência	Descrição
`payment_methods`	Classe que descreve os atributos e métodos de meios de pagamento do Checkout Pro.
`excluded_payment_types`	Método que exclui meios de pagamento indesejados, como cartão de crédito, ticket (boleto ou pagamento em lotérica), entre outros.
`excluded_payment_methods`	Método que exclui bandeiras específicas de cartões de crédito e débito, como Visa, Mastercard, American Express, entre outros.
`installments`	Método que define o número máximo de parcelas a serem ofertadas.
`purpose`	Ao indicar o valor "wallet_purchase" neste método, o Checkout Pro apenas aceitará pagamentos de usuários cadastrados no Mercado Pago, com cartão e saldo em conta.

Por exemplo:

          
<?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_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
}
#...

Aceite pagamentos somente de usuários cadastrados

Você pode aceitar pagamentos com a carteira do Mercado Pago apenas de usuários cadastrados, com cartão e saldo disponível.

Isto permite que seus clientes tenham suas informações de conta disponíveis no ato do pagamento, tais como seus cartões e endereços salvos.

Importante

Ao adicionar esta opção, você não poderá receber pagamentos de usuários que não possuem uma conta Mercado Pago ou Mercado Livre, assim como não poderá receber pagamentos via dinheiro ou transferência.

Para aceitar pagamentos somente de usuários cadastrados, adicione o seguinte atributo as suas preferências:

"purpose": "wallet_purchase"

Ao completar a ação, sua preferência teria estrutura similar a do exemplo abaixo:

{
    "purpose": "wallet_purchase",
    "items": [
        {
            "title": "Meu produto",
            "quantity": 1,
            "unit_price": 75.76
        }
    ],
}

Ative o modo binário

Você pode ativar o modo binário se o modelo de negócios exigir que a aprovação do pagamento seja instantânea. Dessa forma, o pagamento só poderá ser aprovado ou recusado.

Se o modo binário estiver desativado, o pagamento poderá ficar pendente (no caso de exigir qualquer ação do comprador) ou em processo (se for necessária uma revisão manual).

Para ativá-lo, basta definir o atributo binary_mode da preferência de pagamento como true:

"binary_mode": true

Importante

A ativação do modo binário simplifica a integração com o Checkout Pro, mas pode acarretar no decréscimo da taxa de porcentagem de pagamentos aprovados. Isto porque, para manter o fluxo instantâneo, pagamentos pendentes ou ainda sendo processados serão por padrão automáticamente rejeitados.

Defina a vigência das suas preferências

Defina um período de validade para as suas preferências de pagamento a partir dos atributos expires, expiration_date_from e expiration_date_to:

"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 que a data deve seguir o formato ISO 8601: yyyy-MM-dd'T'HH:mm:ssz.

Envie descrição na fatura do cartão comprador

Você pode adicionar uma descrição para o seu negócio através do atributo statement_descriptor das preferências de pagamento, como mostra o exemplo abaixo:

"statement_descriptor": "MEUNEGOCIO"

Dependendo da bandeira do cartão, a descrição (valor do atributo) aparecerá na fatura do cartão do comprador.

Defina uma preferência para diversos itens

Se você precisar criar uma preferência para mais de um item, deverá adicioná-los como uma lista, como mostra o exemplo abaixo:

          
<?php
  # Criar um objeto preferência
  $preference = new MercadoPago\Preference();
  # Cria itens na preferência
  $item1 = new MercadoPago\Item
  $item1->title = "Item de Teste 1";
  $item1->quantity = 2;
  $item1->unit_price = 11.96;

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

  $preference->items = array($item1,$item2);
  # Salvar e postar a preferência
  $preference->save();
?>

          
// Configura sua preferência
var preference = {
  items: [
      { title: 'Meu produto',
      quantity: 1,
      currency_id: 'CLP',
      unit_price: 75.56 },
	{ title: 'Meu produto 2’,
      quantity: 2,
      currency_id: 'CLP',
      unit_price: 96.56 }
    ]
};
// Cria um botão de pagamento no seu site
mercadopago.preferences.create(preference)
.then(function(preference){
  // Este valor substituirá o string "$init_point$" no seu HTML
  global.init_point = preference.body.init_point;
}).catch(function(error){
  console.log(error);
});

          
// Cria um objeto preferência
Preference preference = new Preference();
// Cria itens na preferência
Item item1 = new Item();
item1.setId("1234")
    .setTitle("Produto 1")
    .setQuantity(2)
    .setCurrencyId("CLP")
    .setUnitPrice((float) 75.56);

Item item2 = new Item();
item2.setId("12")
    .setTitle("Produto 2")
    .setQuantity(1)
    .setCurrencyId("CLP")
    .setUnitPrice((float) 75.56);

preference.appendItem(item1, item2);
// Salvar e postar a preferência
preference.save();

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

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

          
# Cria itens na preferência
preference_data = {
    "items": [
        {
            "title": "Mi producto",
            "quantity": 1,
            "unit_price": 75.56
        },
        {
            "title": "Mi producto2",
            "quantity": 2,
            "unit_price": 96.56
        }
    ]
}

# Cria a preferência
preference_response = sdk.preference().create(preference_data)
preference = preference_response["response"]

          
// Cria o request com múltiplos itens
var request = new PreferenceRequest
{
    Items = new List<PreferenceItemRequest>
    {
        new PreferenceItemRequest
        {
            Title = "Meu produto 1",
            Quantity = 1,
            CurrencyId = "CLP",
            UnitPrice = 75.56m,
        },
        new PreferenceItemRequest
        {
            Title = "Meu produto 2",
            Quantity = 2,
            CurrencyId = "CLP",
            UnitPrice = 96.56m,
        },
        // ...
    },
};

// Cria um objeto client
var client = new PreferenceClient();

// Cria a preferência
Preference preference = await client.CreateAsync(request);

          
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":"Meu produto"
	},
	{
		"id_product":2,
		"quantity":2,
		"unit_price": 255.33,
		"titulo":"Meu produto 2"
	}
]
}'

Lembre-se de que o valor total da preferência será a soma do valor do preço unitário de cada item listado.

Mostre o valor do envio

Se você já possui o envio estimado pelo seu site, pode definir o valor do mesmo e mostrá-lo separadamente do valor total no momento do pagamento.

Para configurar tal cenário, adicione o item shipments com o valor que quiser cobrar no atributo cost e o valor not_specified no atributo mode:

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

Otimize a conversão dos seus anúncios

Sabemos que é importante maximizar a eficácia e encontrabilidade dos seus anúncios.

Por isso, oferecemos a possibilidade de integrar o Checkout Pro com as plataformas Facebook Ads e Google Ads para associar pagamentos às suas campanhas de negócio.

Nota

Só serão associados os pagamentos aprovados instantaneamente com cartões de crédito e débito, ou com dinheiro no Mercado Pago.

Integre o Checkout Pro com o Faceboook Ads

Ao criar uma preferência, você pode associá-la a um pixel (identificator) para acompanhamento das conversões do Facebook Ads:

Adicione o código na preferência e substitua o valor pixel_id pelo seu identificador.

          
<?php
  // Criar um objeto preferencia
  $preference = new MercadoPago\Preference();

  // Associar seu pixel do Facebook
  $preference->tracks = array(
    array(
      'type' => 'facebook_ad',
      'values'=> array(
        'pixel_id' => 'PIXEL_ID'
      )
    )
  );

  // ...
  // Salvar e postar a preferencia
  $preference->save();
?>

Adicione o código na preferência e substitua o valor pixel_id pelo seu identificador.

          
  // Criar um objeto preferencia
var preference = {

  // Asocia tu píxel de Facebook
  tracks: [
        {
          type: "facebook_ad",
          values: {
            "pixel_id": 'PIXEL_ID'
          }
        }
      ]
  //...
};

Adicione o código na preferência e substitua o valor pixel_id pelo seu identificador.

          
  // Criar um objeto preferencia
Preference preference = new Preference();

  // Associar seu pixel do Facebook
Track trackFacebook = new Track()
                .setType("facebook_ad")
                .setValues(new TrackValues()
                        .setPixelId("PIXEL_ID")
                );

Preference preference = new Preference()
        .appendTrack(trackFacebook);

  // Salvar e postar a preferencia
preference.save();

Adicione o código na preferência e substitua o valor pixel_id pelo seu identificador.

          
// Associe seu pixel do Facebook
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);

Adicione o código na preferência e substitua o valor pixel_id pelo seu identificador.

          
# Associar seu pixel do Facebook
preference_data = {
    # ...
    "tracks": [
        {
            "type": "facebook_ad",
            "values": {
                "pixel_id": "PIXEL_ID"
            }
        }
    ]
}

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

Adicione o código na preferência e substitua o valor pixel_id pelo seu identificador.

          

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"
            }
        }
    ]
}'

Ao concluir a configuração, um evento Purchase será associado ao pixel especificado quando um pagamento encaminhado pelo seu anúncio for aprovado.

Nota

Por enquanto, só é possível configurar um único pixel por preferência. Teste o funcionamento da sua integração utilizando a extensão do Chrome Facebook Pixel Helper. Para mais informações, visite o site oficial do Facebook .

Integre o Checkout Pro com o Google Ads

Ao criar uma preferência, você pode associá-la a uma tag (identificador) para acompanhamento das conversões do Google Ads:

Adicione o código na preferência e substitua os valores CONVERSION_ID e CONVERSION_LABEL pelos dados da sua tag.

          

<?php
  // Criar um objeto preferencia
  $preference = new MercadoPago\Preference();
 
  // Associar sua tag do Google ads
  $preference->tracks = array(
    array(
        'type' => 'google_ad',
        'values' => array(
          'conversion_id' => 'CONVERSION_ID',
          'conversion_label' => 'CONVERSION_LABEL'
        )
    )
  );

  ...
  // Salvar e postar a preferencia
  $preference->save();
?>

Adicione o código na preferência e substitua os valores CONVERSION_ID e CONVERSION_LABEL pelos dados da sua tag.

          
  // Criar um objeto preferencia
var preference = {
 
  // Associar sua tag do Google ads
  tracks: [
        {
            type: "google_ad",
            values: {
              conversion_id: "CONVERSION_ID",
              conversion_label: "CONVERSION_LABEL"
            } 
        }
      ]
  ...
};

Adicione o código na preferência e substitua os valores CONVERSION_ID e CONVERSION_LABEL pelos dados da sua tag.

          
  // Criar um objeto preferencia
Preference preference = new Preference();

  // Associar sua tag do Google ads
Track trackGoogle = new Track()
                .setType("google_ad")
                .setValues(new TrackValues()
                        .setConversionId("CONVERSION_ID")
                        .setConversionLabel("CONVERSION_LABEL")
                );


Preference preference = new Preference()
        .appendTrack(Google);

  // Salvar e postar a preferencia
preference.save();

Adicione o código na preferência e substitua os valores CONVERSION_ID e CONVERSION_LABEL pelos dados da sua tag.

          
// Associe sua tag do Google ads
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);

Adicione o código na preferência e substitua os valores CONVERSION_ID e CONVERSION_LABEL pelos dados da sua tag.

          
# Associar sua tag do Google ads
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"]

Adicione o código na preferência e substitua os valores CONVERSION_ID e CONVERSION_LABEL pelos dados da sua 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"
            }
        }
    ]
}'

Ao concluir a configuração, uma conversão será associada à tag especificada quando um pagamento encaminhado pelo seu anúncio for aprovado.

Nota

Por enquanto, só é possível configurar uma única tag por preferência. Para mais informações sobre as tags de conversões do Google Ads, visite o site oficial do Google .

Trabalhe com métricas de negócio

Nossos membros certificados no Dev Program podem obter métricas de negócio a partir do Checkout Pro.

Para trabalhar com métricas, utilize headers na sua preferência de pagamento, agregando o código de identificação de acordo com o cenário desejado (não é obrigatório completar os três campos mencionados abaixo):

Header	Tipo de código	Identificador
`x-integrator-id`	Integrador	Para programadores ou agências que realizam a integração.
`x-platform-id`	Plataforma	Para as plataformas ou módulos que oferecem Mercado Pago em suas soluções.
`x-corporation-id`	Corporações	Para contas associadas a uma conta vendedor ou a um grupo econômico.

Nota

Não deixe de adicionar o header integrator_id em suas integrações para receber benefícios adicionais do programa. Você consegue encontrar seu integrator_id no seu Dashboard de desenvolvedor .