Preferência na inicialização - Configure a integração - Mercado Pago Developers

Preferência na inicialização

Para configurar a integração do Wallet Brick para receber pagamentos com a Conta Mercado Pago você precisa seguir os passos abaixo.

Criar preferência
Criar container
Incluir e configurar a biblioteca MercadoPago.js
Instanciar Brick
Renderizar Brick

Os passos são realizados no back-end ou no front-end. As pills Client-Side e Server-Side localizadas imediatamente ao lado do título te ajudam a identificar qual passo é realizado em qual instância.

E, para ajudar, preparamos um exemplo de código completo da configuração do Wallet Brick com Conta Mercado Pago que você pode usar como modelo.

Criar preferência

Server-Side

O primeiro passo para dar ao usuário a possibilidade de pagar utilizando a Conta Mercado Pago, é criar uma preferência em seu backend. Adicione o SDK do Mercado Pago e as credenciais necessárias ao seu projeto para habilitar o uso de preferências:

          
<?php
// SDK do Mercado Pago
require __DIR__ .  '/vendor/autoload.php';
// Adicione as credenciais
MercadoPago\SDK::setAccessToken('PROD_ACCESS_TOKEN');
?>

          
// SDK do Mercado Pago
const mercadopago = require ('mercadopago');
// Adicione as credenciais
mercadopago.configure({
  access_token: 'PROD_ACCESS_TOKEN'
});

          
// SDK do Mercado Pago
import com.mercadopago.MercadoPagoConfig;
// Adicione as credenciais
MercadoPagoConfig.setAccessToken("PROD_ACCESS_TOKEN");

          
# SDK do Mercado Pago
require 'mercadopago'
# Adicione as credenciais
sdk = Mercadopago::SDK.new('PROD_ACCESS_TOKEN')

          
// SDK do Mercado Pago
using MercadoPago.Config;
 // Adicione as credenciais
MercadoPagoConfig.AccessToken = "PROD_ACCESS_TOKEN";

          
# SDK do Mercado Pago
import mercadopago
# Adicione as credenciais
sdk = mercadopago.SDK("PROD_ACCESS_TOKEN")

Em seguida, configure a preferência de acordo com o seu produto ou serviço.

Os exemplos de código abaixo configuram o purpose da preferência como wallet_purchase, onde o usuário deverá fazer login quando for redirecionado para sua conta do Mercado Pago.

          
<?php
// Cria um objeto de preferência
$preference = new MercadoPago\Preference();
 
// Cria um item na preferência
$item = new MercadoPago\Item();
$item->title = 'Meu produto';
$item->quantity = 1;
$item->unit_price = 75.56;
$preference->items = array($item);
 
// o $preference->purpose = 'wallet_purchase'; permite apenas pagamentos logados
// para permitir pagamentos como guest, você pode omitir essa propriedade
$preference->purpose = 'wallet_purchase';
$preference->save();
?>

          
// Cria um objeto de preferência
let preference = {
  // o "purpose": "wallet_purchase" permite apenas pagamentos logados
  // para permitir pagamentos como guest, você pode omitir essa propriedade
  "purpose": "wallet_purchase",
  "items": [
    {
      "id": "item-ID-1234",
      "title": "Meu produto",
      "quantity": 1,
      "unit_price": 75.76
    }
  ]
};
 
mercadopago.preferences.create(preference)
  .then(function (response) {
    // Este valor é o preferenceId que será enviado para o Brick na inicialização
    const preferenceId = response.body.id;
  }).catch(function (error) {
    console.log(error);
  });

          
// Cria um objeto de preferência
PreferenceClient client = new PreferenceClient();
 
// Cria um item na preferência
List<PreferenceItemRequest> items = new ArrayList<>();
PreferenceItemRequest item =
   PreferenceItemRequest.builder()
       .title("Meu produto")
       .quantity(1)
       .unitPrice(new BigDecimal("100"))
       .build();
items.add(item);
 
PreferenceRequest request = PreferenceRequest.builder()
  // o .purpose('wallet_purchase') permite apenas pagamentos logados
  // para permitir pagamentos como guest, você pode omitir essa linha
  .purpose('wallet_purchase')
  .items(items).build();
 
client.create(request);

          
# Cria um objeto de preferência
preference_data = {
  # o purpose: 'wallet_purchase', permite apenas pagamentos logados
  # para permitir pagamentos como guest, você pode omitir essa propriedade
  purpose: 'wallet_purchase',
  items: [
    {
      title: 'Meu produto',
      unit_price: 75.56,
      quantity: 1
    }
  ]
}
preference_response = sdk.preference.create(preference_data)
preference = preference_response[:response]
 
# Este valor é o preferenceId que você usará no HTML na inicialização no Brick
@preference_id = preference['id']

          
// Cria o objeto de request da preferência
var request = new PreferenceRequest
{
  // o Purpose = 'wallet_purchase', permite apenas pagamentos logados
  // para permitir pagamentos como guest, você pode omitir essa propriedade
    Purpose = "wallet_purchase",
    Items = new List<PreferenceItemRequest>
    {
        new PreferenceItemRequest
        {
            Title = "Meu produto",
            Quantity = 1,
            CurrencyId = "BRL",
            UnitPrice = 75.56,
        },
    },
};
 
// Cria a preferência usando o client
var client = new PreferenceClient();
Preference preference = await client.CreateAsync(request);

          
# Cria um item na preferência
preference_data = {
  # o "purpose": "wallet_purchase", permite apenas pagamentos logados
  # para permitir pagamentos como guest, você pode omitir essa propriedade
    "purpose": "wallet_purchase",
    "items": [
        {
            "title": "Meu Item",
            "quantity": 1,
            "unit_price": 75.76
        }
    ]
}
 
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 '{
  "purpose": "wallet_purchase",
  "items": [
      {
          "title": "Meu produto",
          "quantity": 1,
          "unit_price": 75.76
      }
  ]
}'

Importante

Para saber mais detalhes de como configurá-la, acesse a seção Preferências.

Considere que quando um usuário opta por fazer o pagamento utilizando a Conta Mercado Pago, este será redirecionado para a página do Mercado Pago para concluir o pagamento. Por isso, é necessário configurar as back_urls se você quiser retornar ao seu site ao final do pagamento. Para mais informações, visite a seção Redirecione o comprador para o seu site. .

Criar container

Client-Side

Você vai precisar criar um container para definir o local que o Brick será inserido na tela. A criação do container é feita inserindo um elemento (por exemplo, uma div) no código HTML da página no qual o Brick será renderizado (veja código abaixo).

Atenção

O valor exibido na propriedade id a seguir é apenas um exemplo, e pode ser alterado, mas deve sempre corresponder ao id indicado na renderização.

  <div id="walletBrick_container"></div>

Incluir e configurar a biblioteca MercadoPago.js

Client-Side

Utilize a nossa biblioteca oficial para acessar as funcionalidades do Mercado Pago com segurança desde seu frontend.

Atenção

O codigo JS pode ser incluido em uma tag < script > ou um arquivo JS separado.

Você precisará instalar o SDK adicionando o seguinte em seu código HTML:

<script src="https://sdk.mercadopago.com/js/v2"></script>

Em seguida, inicialize o SDK definindo sua chave pública usando código JavaScript:

const mp = new MercadoPago('YOUR_PUBLIC_KEY');

Instanciar Brick

Client-Side

Com o container criado e o SDK JS instalado, o próximo passo é instanciar o Brick builder, que permitirá gerar o Brick. Para instanciar o Brick, insira o código abaixo após a etapa anterior.

const bricksBuilder = mp.bricks();

Atenção

Durante a instanciação do Brick, é possível que apareçam diferentes erros. Para detalhamento de cada um deles, veja a seção Possíveis erros.

Renderizar Brick

Client-Side

Uma vez instanciado, o Brick pode ser renderizado e ter todas as suas configurações compiladas de modo que a estrutura final do Brick seja gerada.

Atenção

Caso seja necessário fechar e abrir o Brick novamente (quando um usuário retorna ao carrinho para alterar algum detalhe da compra, por exemplo) é necessário eliminar a instância atual do Brick e criar uma nova quando for preciso mostrar o Brick novamente. Para isso, utilize o método unmount disponível no controller do Brick, sendo neste caso: window.walletBrickController.unmount().

Para renderizar o Brick, insira o código abaixo após o passo anterior e preencha os atributos conforme os comentários destacados neste mesmo código.

const renderWalletBrick  = async (bricksBuilder) => {
 const settings = {
 initialization: {
   preferenceId: '<PREFERENCE_ID>', // preferenceId gerado no backend
 },
 callbacks: {
   onReady: () => {
      /*
        Callback chamado quando o Brick estiver pronto.
        Aqui você pode ocultar loadings do seu site, por exemplo.
      */
   },
   onSubmit: () => {
     // callback chamado ao clicar no botão de submissão dos dados
       // nesse caso, o usuário foi redirecionado para
       // a página do Mercado Pago para fazer o pagamento
   },
   onError: (error) => {
     // callback chamado para todos os casos de erro do Brick
     console.error(error);
   },
 },
};
 
 window.walletBrickController = await bricksBuilder.create(
   'wallet',
   'walletBrick_container',
   settings
 );
};
renderWalletBrick (bricksBuilder);

O resultado de renderizar o Brick deve ser como na imagem abaixo:

wallet-brick-render

Preference in onSubmit

Learn how to integrate Wallet Brick step by step in onSubmit.