Customers and stored cards
Prerequisites
- Have the tool to collect card information implemented.
Customers and cards allow you to securely store your customers’ card information to enhance their shopping experience.
This allows your customers to complete their purchases much faster, since they will not have to re-enter their card information again.
Customers represent, as the name implies, your customer. The cards you store will be for this specific customer.
Create a customer and a card
To create a Customer
and a Card
simultaneously it is necessary to submit, at least, the email and token fields.
The token
is captured during the collection of card information.
Note
We recommend storing the card data after a payment has been successfully made, in order to make sure that they are correct.
<?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->save();
?>
import com.mercadopago.*;
MercadoPago.SDK.configure("ENV_ACCESS_TOKEN");
Customer customer = new Customer();
customer.setEmail("alda@yahoo.com");
customer.save();
Card card = new Card();
card.setToken("9b2d63e00d66a8c721607214cedaecda");
card.setCustomerId(customer.getId());
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": customer.id
}
mercadopago.cards.create(card_data).then(function (card) {
}).catch(function (error) {
// Do Stuff...
});
}).catch(function (error) {
// Do Stuff...
});
require 'mercadopago'
MercadoPago::SDK.configure(ACCESS_TOKEN: ENV_ACCESS_TOKEN)
customer = MercadoPago::Customer.new()
customer.email = "test@test.com"
customer.save
card = MercadoPago::Card.new()
card.token = "9b2d63e00d66a8c721607214cedaecda"
card.customer_id = customer.id
card.save
MercadoPago.SDK.SetAccessToken = "ENV_ACCESS_TOKEN";
Customer customer = new Customer()
{
Email = "test@test.com"
};
customer.Save();
Card card = new Card()
{
Token = "9b2d63e00d66a8c721607214cedaecda",
CustomerId = customer.Id
};
card.Save();
Expected response:
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
}
Receive a payment from a Customer
In order to receive a payment using a stored card, it is necessary to re-capture the security code because for security reasons, Mercado Pago cannot store this information.
1. Show stored cards
List the stored cards to allow your customer to select which one to use.
You can get the complete list of Cards
of a customer by making an HTTP GET
request:
<?php
$customer = MercadoPago\Customer::find_by_id($customer_id);
$cards = $customer->cards();
?>
Customer customer = Customer.load(customerId)
ArrayList<Cards> cards = customer.getCards();
var filters = {
id: customer_id
};
mercadopago.searchCustomer({
qs: filters
}).then(function (customer) {
// customer.cards ...
}).catch(function (error) {
// Do Stuff...
});
customer = MercadoPago::Customer.load(customer_id);
cards = customer.cards;
customer = Customer.FindById("customer.Id");
List<Card> cards = customer.Cards;
Response:
Json
[{
"id": "1490022319978",
"expiration_month": 12,
"expiration_year": 2020,
"first_six_digits": "415231",
"last_four_digits": "0001",
...
}]
With this response we recommend making a form:
Html
<li>
<label>Payment Method:</label>
<select id="cardId" name="cardId" data-checkout='cardId'>
<?php foreach ($cards["response"] as $card) { ?>
<option value="<?php echo $card["id"]; ?>"
first_six_digits="<?php echo $card["first_six_digits"]; ?>"
security_code_length="<?php echo $card["security_code"]["length"]; ?>">
<?php echo $card["payment_method"]["name"]; ?> ended in <?php echo $card["last_four_digits"]; ?>
</option>
<?php } ?>
</select>
</li>
<li id="cvv">
<label for="cvv">Security code:</label>
<input type="text" id="cvv" data-checkout="securityCode" placeholder="123" />
</li>
2. Get the security code
The process is similar to the collection of card information. You must create a card token
by sending the $form
with the cardId
and the securityCode
:
Javascript
doSubmit = false;
addEvent(document.querySelector('#pay'),'submit', doPay);
function doPay(event){
event.preventDefault();
if(!doSubmit){
var $form = document.querySelector('#pay');
Mercadopago.createToken($form, sdkResponseHandler); // The function "sdkResponseHandler" is defined below
return false;
}
};
The createToken
method will return a card_token
(the secure representation of the card):
Json
{
"id": "ff8080814cbd77a8014cc",
...
}
3. Create a payment
As soon as you get the token described in the previous step, you can generate the payment for the corresponding amount.
Since it is a payment with a stored card, you must send the customer id together with the token.
<?php
require ('mercadopago.php');
MercadoPago\SDK::configure(['ACCESS_TOKEN' => 'ENV_ACCESS_TOKEN']);
$payment = new MercadoPago\Payment();
$payment->transaction_amount = 100;
$payment->token = "ff8080814c11e237014c1ff593b57b4d";
$payment->payer = array(
"type" => "customer",
"id" => "123456789-jxOV430go9fx2e"
);
$payment->save();
?>
import com.mercadopago.*;
MercadoPago.SDK.configure("ENV_ACCESS_TOKEN");
Payer payer = new Payer();
payer.type = "customer";
payer.id = "123456789-jxOV430go9fx2e";
Payment payment = new Payment();
payment.setTransactionAmount(100);
payment.setToken('ff8080814c11e237014c1ff593b57b4d');
payment.setPayer(payer);
payment.save();
var mercadopago = require('mercadopago');
mercadopago.configurations.setAccessToken(config.access_token);
var payment_data = {
transaction_amount: 100,
token: 'ff8080814c11e237014c1ff593b57b4d'
payer: {
type: "customer"
id: "123456789-jxOV430go9fx2e"
}
};
mercadopago.payment.create(payment_data).then(function (data) {
// Do Stuff...
}).catch(function (error) {
// Do Stuff...
});
require 'mercadopago'
MercadoPago::SDK.configure(ACCESS_TOKEN: ENV_ACCESS_TOKEN)
payment = MercadoPago::Payment.new()
payment.transaction_amount = 100
payment.token = 'ff8080814c11e237014c1ff593b57b4d'
payment.payer = {
type: "customer"
id: "123456789-jxOV430go9fx2e"
}
payment.save()
That's all, the response will indicate the payment status (approved
, rejected
or in_process
).
See more information about response handling.
Add new cards to a Customer
It is possible to add new cards to a Customer
. To do this, you must create a token
and make an HTTP POST
request to the Customer
.
<?php
MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");
$customer = MercadoPago\Customer::load("247711297-jxOV430go9fx2e");
$card = new MercadoPago\Card();
$card->token = "9b2d63e00d66a8c721607214cedaecda";
$card->customerId = $customer->getId;
$card->save();
print_r($card);
?>
import com.mercadopago.*;
MercadoPago.SDK.configure("ENV_ACCESS_TOKEN");
Customer customer = Customer.load("247711297-jxOV430go9fx2e")
Card card = new Card();
card.setToken("9b2d63e00d66a8c721607214cedaecda");
card.setCustomerId(customer.getID());
card.save();
System.out.print(card.toString());
var mercadopago = require('mercadopago');
mercadopago.configure({
access_token: 'ENV_ACCESS_TOKEN'
});
var filters = {
id: "247711297-jxOV430go9fx2e"
};
mercadopago.searchCustomer({
qs: filters
}).then(function (customer) {
card_data = {
"token": "9b2d63e00d66a8c721607214cedaecda",
"customer": customer.id
}
mercadopago.cards.create(card_data).then(function (card) {
console.log(card);
}).catch(function (error) {
// Do Stuff...
});
}).catch(function (error) {
// Do Stuff...
});
require 'mercadopago'
MercadoPago::SDK.configure(ACCESS_TOKEN: ENV_ACCESS_TOKEN)
customer = MercadoPago::Customer.load("247711297-jxOV430go9fx2e")
card = MercadoPago::Card.new()
card.token = "9b2d63e00d66a8c721607214cedaecda"
card.customer_id = customer.id
card.save
puts card
Response:
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
}
Search a Customer
In case you do not know your Customer’s id
, you can use the Customer Search
API by making an HTTP GET
request. The required parameter for this is 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 = MercadoPago\Customer::search(filters).resources();
var filters = {
email: "test@test.com"
};
mercadopago.searchCustomer({
qs: filters
}).then(function (customer) {
// customer.cards ...
}).catch(function (error) {
// Do Stuff...
});
customers = MercadoPago::Customer.search(email: "test@test.com");
Response:
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
}
}
]
}
Get the Customer’s Cards
You can get the complete list of Cards
of a customer by making an HTTP GET
request:
<?php
$customer = MercadoPago\Customer::find_by_id($customer_id);
$cards = $customer->cards();
?>
Customer customer = Customer.load(customerId)
ArrayList<Cards> cards = customer.getCards();
var filters = {
id: customer_id
};
mercadopago.searchCustomer({
qs: filters
}).then(function (customer) {
// customer.cards ...
}).catch(function (error) {
// Do Stuff...
});
customer = MercadoPago::Customer.load(customer_id);
cards = customer.cards;
Response:
Json
[{
"id": "1490022319978",
"expiration_month": 12,
"expiration_year": 2020,
"first_six_digits": "415231",
"last_four_digits": "0001",
...
}]