Clientes e cartões armazenados - Web Tokenize Checkout (v2) - Mercado Pago Developers

Clientes e cartões armazenados

Pré-requisitos

Os clientes e cartões (customers & cards) são uma forma de armazenar os dados do cartão de maneira segura para melhorar a experiência de compra.

Isto permitirá que seus clientes finalizem suas compras de forma muito mais rápida e simples, já que não deverão informar novamente seus dados de cartão.

Os customers representam seus clientes. Os cartões que armazenar serão deste cliente específico.

Criação de um customer e card

Para criar um Customer e um Card ao mesmo tempo é necessário enviar pelo menos os campos email, payment_method_id, issuer_id e token.

O token é o que captura quando esta tratando o retorno do Web Tokenize Checkout.

Nota
Recomendamos armazenar os dados de cartão logo que seja realizado um pagamento de forma bem sucedida, para certificar-se de que os mesmos sejam corretos.
          
<?php   

  MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");

  $customer = new MercadoPago\Customer();
  $customer->email = "test@test.com";
  $customer->save();

  $card = new MercadoPago\Card();
  $card->token = "9b2d63e00d66a8c721607214cedaecda";
  $card->customer_id = $customer->id();$card->issuer = array("id" => "3245612");
  $card->payment_method = array("id" => "debit_card");
  $card->save();

?>

        
          
import com.mercadopago.*;
MercadoPago.SDK.configure("ENV_ACCESS_TOKEN");

Customer customer = new Customer();
customer.setEmail("john@yourdomain.com");
customer.save();

Issuer issuer = new Issuer();
issuer.setId("3245612");

Card card = new Card();
card.setToken("9b2d63e00d66a8c721607214cedaecda");
card.setCustomerId(customer.getId());
card.setIssuer(issuer);
card.setPaymentMethodId("debit_card");
card.save();


        
          
var mercadopago = require('mercadopago');
mercadopago.configure({
    access_token: 'ENV_ACCESS_TOKEN'
});

customer_data = { "email": "test@test.com" }

mercadopago.customers.create(customer_data).then(function (customer) {

  card_data = {
    "token": "9b2d63e00d66a8c721607214cedaecda",
    "customer_id": customer.body.id,
    "issuer_id": "2353146",
    "payment_method_id": "debit_card"
  }

  mercadopago.card.create(card_data).then(function (card) {

  }).catch(function (error) {
   // Do Stuff...
  });

}).catch(function (error) {
 // Do Stuff...
});


        
          
require 'mercadopago'
sdk = Mercadopago::SDK.new('ENV_ACCES_TOKEN')

customer_data = {
  email: 'test@test.com',
}
customer_response = sdk.customer.create(customer_data)
customer = customer_response[:response]

card_data = {
  token: '9b2d63e00d66a8c721607214cedaecda',
  customer_id: customer['id'],
  issuer_id: '2353146',
  payment_method_id: 'debit_card'
}
card_response = sdk.card.create(card_data)
card = card_response[:response]


        
          
MercadoPagoConfig.AccessToken = "YOUR_ACCESS_TOKEN";

var customerRequest = new CustomerRequest
{
    Email = "test@test.com",
};
var customerClient = new CustomerClient();
Customer customer = await customerClient.CreateAsync(customerRequest);

var cardRequest = new CustomerCardCreateRequest
{
    Token = "9b2d63e00d66a8c721607214cedaecda"
};
CustomerCard card = await customerClient.CreateCardAsync(customer.Id, cardRequest);

        
          
import mercadopago
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN")

customer_data = {
  "email": "test@test.com"
}
customer_response = sdk.customer().create(customer_data)
customer = customer_response["response"]

card_data = {
  "token": "9b2d63e00d66a8c721607214cedaecda",
  "issuer_id": "2353146",
  "payment_method_id": "debit_card"
}
card_response = sdk.card().create(customer["id"], card_data)
card = card_response["response"]

        

Retorno do Servidor:

json

{
	"id": "123456789-jxOV430go9fx2e",
	"email": "test@test.com",
	...
	"default_card": "1490022319978",
	"default_address": null,
	"cards": [{
		"id": "1490022319978",
		"expiration_month": 12,
		"expiration_year": 2020,
		"first_six_digits": "415231",
		"last_four_digits": "0001",
		...
	}],
	"addresses": [],
	"live_mode": false
}
Nota
Para os cartões master também é preciso enviar o campo issuer_id no momento de criar o cartão para um customer.
Importante
Se você receber uma mensagem de erro do tipo "invalid parameter" com código de estado HTTP 400, certifique-se de que está preenchendo corretamente os campos payment_method_id e issuer_id.

Receber pagamento de um Customer

Para que possa receber um pagamento utilizando um cartão armazenado, é necessário incluir no código de integração o ID do customer e os ID dos cartões do usuário através dos atributos customerId e cardIds no parâmetro savedCards.

Por exemplo:

html

<script>
  mp.checkout({
    tokenizer: {
        totalAmount: 4000,
        backUrl: 'https://www.minha-loja.com/process',
        savedCards: {
            cardIds: '1518023392627,1518023332143' // IDs dos cartões
            customerId: '209277402-FqRqgEc3XItrxs' // Seu customer ID
        }
    },
    render: {
        container: ‘.tokenizer-container’,
        label: ‘Pagar’
    }
  });
</script>
Nota
Os IDs dos cartões deverão ser separados por vírgula.

1. Obter os IDs dos cartões armazenados

Você pode listar os cartões armazenados no Web Tokenize Checkout para que seu cliente escolha com qual deseja pagar.

Podendo obter uma lista completa de Cards de um cliente realizando um request HTTP GET:

          
<?php
	$customer = MercadoPago\Customer::find_by_id($id);
  $cards = $customer->cards();
?>

        
          
  Customer customer = Customer.findById(customerId);
  ArrayList<Cards> cards = customer.getCards();


        
          
  var filters = {
    id: customer_id
  };

  mercadopago.customers.search({
    qs: filters
  }).then(function (customer) {
    // customer.cards ...
  }).catch(function (error) {
    // Do Stuff...
  });


        
          
cards_response = sdk.card.list(customer_id)
cards = cards_response[:response]


        
          
var customerClient = new CustomerClient();
ResourcesList<CustomerCard> customerCards = await customerClient.ListCardsAsync("CUSTOMER_ID");

        
          
cards_response = sdk.card().list_all(customer_id)
cards = cards_response["response"]

        

Dados de um cartão guardado:

json

[{
	"id": "1490022319978",
	"expiration_month": 12,
	"expiration_year": 2020,
	"first_six_digits": "415231",
	"last_four_digits": "0001",
	...
}]

2. Usar os ID do cartão no checkout

Com esta informação de cartão poderá chamar o Web Tokenize Checkout.

Por exemplo:

html

<script>
// Obtenha os IDs dos cartões obtidos ao chamar a API na etapa anterior
  const customerCardIds = cardsResponse.map(card => card.id);

// Inicializa o checkout
  mp.checkout({
    tokenizer: {
        totalAmount: 4000,
        backUrl: 'https://www.mi-sitio.com/process',
        savedCards: {
            cardIds: customerCardIds, // cardIds obtidos
            customerId: '209277402-FqRqgEc3XItrxs' // Seu customer ID
        }
    },
    render: {
        container: ‘.tokenizer-container’,
        label: ‘Pagar’
    }
  });
</script>
Esta documentação utiliza a nova versão da biblioteca. Para ver a versão anterior, vá para a seção de Clientes e cartões armazenados com MercadoPago.js V1 .

Adicione novos cartões a um Customer

É possível adicionar novos cartões ao seu Customer. Para isto deve criar um token e fazer um request HTTP POST ao Customer.

          
<?php  

  MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");

  $customer = MercadoPago\Customer::find_by_id("247711297-jxOV430go9fx2e");

  $card = new MercadoPago\Card();
  $card->token = "9b2d63e00d66a8c721607214cedaecda";
  $card->customer_id = $customer->id;
  $card->issuer = array("id" => "3245612");
  $card->payment_method = array("id" => "debit_card");
  $card->save();

  print_r($card);

?>

        
          
import com.mercadopago.*;
MercadoPago.SDK.configure("ENV_ACCESS_TOKEN");

Customer customer = Customer.findById("247711297-jxOV430go9fx2e");

Card card = new Card();
card.setToken("9b2d63e00d66a8c721607214cedaecda");
card.setCustomerId(customer.getID());
card.setIssuer(issuer);
card.setPaymentMethodId("debit_card");
card.save();

System.out.print(card.toString());


        
          
var mercadopago = require('mercadopago');
mercadopago.configure({
    access_token: 'ENV_ACCESS_TOKEN'
});

var filters = {
  id: "247711297-jxOV430go9fx2e"
};

mercadopago.customers.search({
  qs: filters
}).then(function (customer) {
  card_data = {
    "token": "9b2d63e00d66a8c721607214cedaecda",
    "customer": customer.id,
    "issuer_id": "2332451",
    "payment_method_id": "debit_card"
  }

  mercadopago.cards.create(card_data).then(function (card) {
    console.log(card);
  }).catch(function (error) {
   // Do Stuff...
  });
}).catch(function (error) {
  // Do Stuff...
});



        
          
require 'mercadopago'
sdk = Mercadopago::SDK.new('ENV_ACCES_TOKEN')

customer_response = sdk.customer.get('247711297-jxOV430go9fx2e')
customer = customer_response[:response]

card_data = {
  token: '9b2d63e00d66a8c721607214cedaecda',
  customer_id: customer['id'],
  issuer_id: '2332451',
  payment_method_id: 'debit_card'
}
card_response = sdk.card.create(card_data)
card = card_response[:response]

puts card


        
          
MercadoPagoConfig.AccessToken = "YOUR_ACCESS_TOKEN";

var customerClient = new CustomerClient();
Customer customer = await customerClient.GetAsync("247711297-jxOV430go9fx2e");

var cardRequest = new CustomerCardCreateRequest
{
    Token = "9b2d63e00d66a8c721607214cedaecda",
};
CustomerCard card = await customerClient.CreateCardAsync(customer.Id, cardRequest);

Console.WriteLine(card.Id);

        
          
import mercadopago
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN")

customer_response = sdk.customer().get("247711297-jxOV430go9fx2e")
customer = customer_response["response"]

card_data = {
  "token": "9b2d63e00d66a8c721607214cedaecda",
  "issuer_id": "2332451",
  "payment_method_id": "debit_card"
}
card_response = sdk.card().create(customer["id"], card_data)
card = card_response["response"]

print(card)

        

Retorno:

json

{
	"id": "1493990563105",
	"expiration_month": 12,
	"expiration_year": 2020,
	"first_six_digits": "503175",
	"last_four_digits": "0604",
	"payment_method": {
		"id": "master",
		"name": "master",
		"payment_type_id": "credit_card",
		"thumbnail": "http://img.mlstatic.com/org-img/MP3/API/logos/master.gif",
		"secure_thumbnail": "https://www.mercadopago.com/org-img/MP3/API/logos/master.gif"
	},
	"security_code": {
		"length": 3,
		"card_location": "back"
	},
	"issuer": {
		"id": 3,
		"name": "Mastercard"
	},
	"cardholder": {
		"name": "Card holdername",
		"identification": {
			"number": "12345678",
			"type": "DNI"
		}
	},
	"date_created": "2017-05-05T09:22:30.893-04:00",
	"date_last_updated": "2017-05-05T09:22:30.893-04:00",
	"customer_id": "255276729-yLOTNHQjpDWw1X",
	"user_id": "255276729",
	"live_mode": false
}
Importante
Se você receber uma mensagem de erro do tipo "invalid parameter" com código de estado HTTP 400, certifique-se de que está preenchendo corretamente os campos payment_method_id e issuer_id.

Buscar um Customer

No caso em que não saiba qual é o id de seu Customer, poderá utilizar a API de Customer Search realizando um request HTTP GET. O parâmetro requerido para isto é o email:

          
<?php

  $filters = array(
    "id"=>"247711297-jxOV430go9fx2e"
  );

  $customers = MercadoPago\Customer::search($filters);

?>

        
          
  Map<String, String> filters = new HashMap<>();
  filters.put("email", "test@test.com");

  ArrayList<Customer> customers = Customer.search(filters, false).resources();



        
          
  var filters = {
    email: "test@test.com"
  };

  mercadopago.customers.search({
    qs: filters
  }).then(function (customer) {
    // customer.cards ...
  }).catch(function (error) {
    // Do Stuff...
  });


        
          
customers_response = sdk.customer.search(filters: { email: 'test@test.com' })
customer = customer_response[:response]


        
          
var searchRequest = new SearchRequest
{
    Filters = new Dictionary<string, object>
    {
        ["email"] = "test@test.com",
    },
};
ResultsResourcesPage<Customer> results = await customerClient.SearchAsync(searchRequest);
IList<Customer> customers = results.Results;

        
          
filters = {
    "email": "test@test.com"
}

customers_response = sdk.customer().search(filters=filters)
customers = customers_response["response"]

        

Retorno:

json

{
    "paging": {
        "limit": 10,
        "offset": 0,
        "total": 1
    },
    "results": [
        {
            "address": {
                "id": null,
                "street_name": null,
                "street_number": null,
                "zip_code": null
            },
            "addresses": [],
            "cards": [
                {
                    ...
                }
            ],
            "date_created": "2017-05-05T00:00:00.000-04:00",
            "date_last_updated": "2017-05-05T09:23:25.021-04:00",
            "date_registered": null,
            "default_address": null,
            "default_card": "1493990563105",
            "description": null,
            "email": "test@test.com",
            "first_name": null,
            "id": "123456789-jxOV430go9fx2e",
            "identification": {
                "number": null,
                "type": null
            },
            "last_name": null,
            "live_mode": false,
            "metadata": {},
            "phone": {
                "area_code": null,
                "number": null
            }
        }
    ]
}

Obter os Cards de um Customer

Poderá obter uma lista completa de Cards de um cliente realizando um request HTTP GET:

          
<?php
	$customer = MercadoPago\Customer::find_by_id($customer_id);
  $cards = $customer->cards();
?>

        
          
  Customer customer = Customer.findById(customerId);
  ArrayList<Cards> cards = customer.getCards();


        
          
  var filters = {
    id: customer_id
  };

  mercadopago.customers.search({
    qs: filters
  }).then(function (customer) {
    // customer.cards ...
  }).catch(function (error) {
    // Do Stuff...
  });


        
          
cards_response = sdk.card.list(customer_id)
cards = cards_response[:response]


        
          
var customerClient = new CustomerClient();
ResourcesList<CustomerCard> customerCards = await customerClient.ListCardsAsync("CUSTOMER_ID");

        
          
cards_response = sdk.card().list_all(customer_id)
cards = cards_response["response"]

        

Retorno:

json

[{
	"id": "1490022319978",
	"expiration_month": 12,
	"expiration_year": 2020,
	"first_six_digits": "415231",
	"last_four_digits": "0001",
	...
}]

Modificar um cliente

Para modificar um cliente é necessário enviar o customer_id e os campos a serem atualizados em uma solicitação HTTP PUT.

Os campos que podem ser modificados de um cliente são:

AtributoDescrição
addressEndereço.
default_addressEndereço padrão.
default_cardCartão padrão.
descriptionDescrição.
emailE-mail da conta.
first_nameNome.
last_nameSobrenome.
phoneTelefone cadastrado.
identificationTipo e número do documento.
          
<?php

  MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");

  $customer = new MercadoPago\Customer();
  $customer->email = "user@user.com";
  $customer->first_name = "john";
  $customer->last_name = "wagner";
  $customer->phone = array("area_code" => "11", "number" => "001234567");
  $customer->identification = array("type" => "RUT", "number" => "12341234");
  $customer->default_address = "Casa";
  $customer->address = array("zip_code" => "52", "street_name" => "Av. Apoquindo", "street_number" => "2");
  $customer->description = "Informações do cliente";
  $customer->default_card = "None";
  $customer->update();

?>


        
          
var mercadopago = require('mercadopago');
mercadopago.configure({
    access_token: 'ENV_ACCESS_TOKEN'
});

var customer_data = { 
  "email": "test@test.com",
  "first_name": "john" ,
  "last_name": "wagner",
  "phone": {
    "area_code": "11",
    "number": "001234567"
  },
  "identification": {
    "type": "RUT",
    "number": "12341234"
  }, 
  "default_address": "Casa",
  "address": {
    "zip_code": "52",
    "street_name": "Av. Apoquindo",
    "street_number": "2"
  },
  "description": "Informações do cliente",
  "default_card": "None
 }

mercadopago.customers.update(customer_data).then(function (customer) {
 // code ...
});


        
          
import com.mercadopago.*;
MercadoPago.SDK.configure("ENV_ACCESS_TOKEN");

Phone phone = new Phone();
phone.setAreaCode("11");
phone.setNumber("001234567");

DefaultAddress defaultAddress = new DefaultAddress();
defaultAddress.setZipCode("52");
defaultAddress.setStreetName("Av. Apoquindo");
defaultAddress.setStreetNumber(2);

Identification identification = new Identification();
identification.setType("RUT");
identification.setNumber(12341234);

Customer customer = new Customer();
customer.setEmail("user@user.com");
customer.setFirstName("john");
customer.setLastName("wagner");
customer.setDefaultAddress("Casa");
customer.setPhone(phone);
customer.setIdentification(identification);
customer.setDescription("Informações do cliente");
customer.setDefaultCard("None");
cusotmer.setAddress(defaultAddress);
customer.update();


        
          
require 'mercadopago'

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

customer_request = {
  email: 'user@user.com',
  first_name: 'john',
  last_name: 'wagner',
  default_address: 'Casa',
  phone: {
    area_code: '11',
    number: '001234567'
  },
  identification: {
    type: 'RUT',
    number: '12341234'
  },
  address: {
    zip_code: '52',
    street_name: 'Av. Apoquindo',
    street_number: '2'
  },
  description: 'Informações do cliente',
  default_card: 'None'
}
customer_response = sdk.customer.update(customer_id ,customer_request)
customer = customer_response[:response]


        
          
MercadoPagoConfig.AccessToken = "ENV_ACCESS_TOKEN";
var phoneRequest = new PhoneRequest
{
  AreaCode = "11",
  Number = "001234567"
};

var identificationRequest = new IdentificationRequest
{
  Type = "RUT",
  Number = "12341234"
};

var addressRequest = new AddressRequest
{
  ZipCode = "52",
  StreetName = "Av. Apoquindo",
  StreetNumber = "2"
};

var customerRequest = new CustomerRequest
{
    Email = "test@test.com",
    FirstName = "john",
    LastName = "wagner",
    DefaultAddress = "home",
    Description = "Informações do cliente",
    DefaultCard = "None",
    Phone = phoneRequest,
    Identification = identificationRequest,
    Address = addressRequest

};
var customerClient = new CustomerClient();
Customer customer = await customerClient.Update(customerRequest);


        
          
import mercadopago
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN")

customer_data = {
  "email": 'user@user.com',
  "first_name": 'john',
  "last_name": 'wagner',
  "default_address": 'Casa',
  "phone": {
    "area_code": '11',
    "number": '001234567'
  },
  "identification": {
    "type": 'RUT',
    "number": '12341234'
  },
  "address": {
    "zip_code": '52',
    "street_name": 'Av. Apoquindo',
    "street_number": '2'
  },
  "description": 'Informações do cliente',
  "default_card": 'None'
}
customer_response = sdk.customer().update(customer_id, customer_data)
customer = customer_response["response"]


        
          
curl -X PUT \
    'https://api.mercadopago.com/v1/customers/{id}' \
    -H 'Authorization: Bearer ACCESS_TOKEN_ENV' \ 
    -d '{
  "email": "user@user.com",
  "first_name": "john",
  "last_name": "wagner",
  "address": {
    "zip_code": "52",
    "street_name": "Av. Apoquindo",
    "street_number": "2"
  },
  "phone": {
    "area_code": "11",
    "number": "001234567"
  },
  "identification": {
    "type": "RUT",
    "number": "12341234"
  },
  "description": "Informações do cliente" 
}'


        

Exemplo de resposta com o envio do customer_id:

json

{
  "id": "xxxxxxxxxxxxxxxxxxxxx",
  "email": "user@user.com",
  "first_name": "john",
  "last_name": "wagner",
  "phone": {
    "area_code": "11",
    "number": 001234567
  },
  "identification": {
    "type": "RUT",
    "number": 12341234
  },
  "address": {
    "zip_code": "52",
    "street_name": "Av. Apoquindo",
    "street_number": 2
  },
  "description": "Informações do cliente",
  "date_created": "2021-05-25T15:36:23.541Z",
  "metadata": {},
  "cards": [
    {}
  ],
  "addresses": [
    {}
  ]
}

Exemplo de resposta sem o parâmetro customers_id:

json

{
  "message": "missing customer id"
}
Nota
Se você não tiver o customer_id, verifique a API de Clientes e gere uma solicitação HTTP GET usando o parâmetro email para obtê-lo.