Advanced Integration
Remember your customers and cards
Use our APIs to save your customer's card references and offer them a better experience. This way, your customers won't need to fill out their data every time and their payments will be completed faster.
Create customers and cards
To create customers and cards, submit the e-mail field and generated token.
You will add every customer using the customer
value, and cards as card
.
<?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();
?>
var mercadopago = require('mercadopago');
mercadopago.configure({
access_token: 'ENV_ACCESS_TOKEN'
});
var customer_data = { "email": "test@test.com" }
mercadopago.customers.create(customer_data).then(function (customer) {
var card_data = {
"token": "9b2d63e00d66a8c721607214cedaecda",
"customer": customer.id
}
mercadopago.cards.create(card_data).then(function (card) {
console.log(card);
});
});
import com.mercadopago.*;
MercadoPago.SDK.configure("ENV_ACCESS_TOKEN");
Customer customer = new Customer();
customer.setEmail("john@yourdomain.com");
customer.save();
Card card = new Card();
card.setToken("9b2d63e00d66a8c721607214cedaecda");
card.setCustomerId(customer.getId());
card.save();
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();
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
-d '{"token": "9b2d63e00d66a8c721607214cedaecda"}'
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
}
Add new cards to a customer
To add new cards to a customer, create a token and make a HTTP POST
to the 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->save();
print_r($card);
?>
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
}
mercadopago.cards.create(card_data).then(function (card) {
console.log(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());
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
MercadoPago.SDK.AccessToken = "ENV_ACCESS_TOKEN";
Customer customer = Customer.FindById("247711297-jxOV430go9fx2e");
Card card = new Card()
{
Token = "9b2d63e00d66a8c721607214cedaecda",
CustomerId = customer.Id
};
card.Save();
Console.WriteLine(card.Id);
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers' \
-d '{"email": "test@test.com"}'
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
-d '{"token": "9b2d63e00d66a8c721607214cedaecda"}'
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
}
Use saved cards for payments
For customers to make payments with their saved data, you need to capture the security code again. For security reasons, Mercado Pago can't save that information.
1. Display saved cards to your customer
First, get the saved card list so that your customer can choose one to make the payment:
<?php
$customer = MercadoPago\Customer::find_by_id($id);
$cards = $customer->cards();
?>
var filters = {
id: customer_id
};
mercadopago.customers.search({
qs: filters
}).then(function (customer) {
console.log(customer);
});
Customer customer = Customer.load(customerId)
ArrayList<Cards> cards = customer.getCards();
customer = MercadoPago::Customer.load(customer_id);
cards = customer.cards;
customer = Customer.FindById("customer.Id");
List<Card> cards = customer.Cards;
curl -X GET \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
Saved card data response:
json
[{
"id": "1490022319978",
"expiration_month": 12,
"expiration_year": 2020,
"first_six_digits": "415231",
"last_four_digits": "0001",
...
}]
And you can prepare the form like this:
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. Capture security code
The customer needs to enter the security code in a flow similar to card data capture. You need to create a token by submitting the form with card ID and security code.
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);
return false;
}
};
3. Create payment
Once you get the token, you can generate the payment for the relevant amount. As the payment is made using saved card data, you need to send the customer ID along with the token.
<?php
MercadoPago\SDK::setAccessToken("ENV_ACCESS_TOKEN");
$payment = new MercadoPago\Payment();
$payment->transaction_amount = 100;
$payment->token = "ff8080814c11e237014c1ff593b57b4d";
$payment->installments = 1;
$payment->payer = array(
"type" => "customer",
"id" => "123456789-jxOV430go9fx2e"
);
$payment->save();
?>
var mercadopago = require('mercadopago');
mercadopago.configurations.setAccessToken(config.access_token);
var payment_data = {
transaction_amount: 100,
token: 'ff8080814c11e237014c1ff593b57b4d',
installments: 1,
payer: {
type: "customer"
id: "123456789-jxOV430go9fx2e"
}
};
mercadopago.payment.create(payment_data).then(function (data) {
console.log(data);
});
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(100f);
payment.setInstallments(1);
payment.setToken('ff8080814c11e237014c1ff593b57b4d');
payment.setPayer(payer);
payment.save();
require 'mercadopago'
MercadoPago::SDK.configure(ACCESS_TOKEN: ENV_ACCESS_TOKEN)
payment = MercadoPago::Payment.new()
payment.transaction_amount = 100
payment.token = 'ff8080814c11e237014c1ff593b57b4d'
payment.installments = 1
payment.payer = {
type: "customer"
id: "123456789-jxOV430go9fx2e"
}
payment.save()
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/payments' \
-d '{
transaction_amount: 100,
token: "ff8080814c11e237014c1ff593b57b4d",
installments: 1,
payer: {
type: "customer",
id: "123456789-jxOV430go9fx2e"
}
}'
Search for an existing customer
You can search for customer information, if needed; for example, when you don't know the assigned ID. The e-mail is the required parameter to get it.
<?php
$filters = array(
"id"=>"247711297-jxOV430go9fx2e"
);
$customers = MercadoPago\Customer::search($filters);
?>
var filters = {
email: "test@test.com"
};
mercadopago.customers.search({
qs: filters
}).then(function (customer) {
console.log(customer);
});
Map<String, String> filters = new HashMap<>();
filters.put("email", "test@test.com");
ArrayList<Customer> customers = MercadoPago\Customer::search(filters).resources();
customers = MercadoPago::Customer.search(email: "test@test.com");
curl -X GET \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers/search' \
-d '{
"email": "test_user_19653727@testuser.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
}
}
]
}
Check customer's card list
<?php
$customer = MercadoPago\Customer::find_by_id($customer_id);
$cards = $customer->cards();
?>
var filters = {
id: customer_id
};
mercadopago.customers.search({
qs: filters
}).then(function (customer) {
console.log(customer);
});
Customer customer = Customer.load(customerId)
ArrayList<Cards> cards = customer.getCards();
customer = MercadoPago::Customer.load(customer_id);
cards = customer.cards;
curl -X GET \
-H 'Authorization: Bearer ENV_ACCESS_TOKEN' \
'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
Response
json
[{
"id": "1490022319978",
"expiration_month": 12,
"expiration_year": 2020,
"first_six_digits": "415231",
"last_four_digits": "0001",
...
}]
Cancellations and refunds
Cancellations occur when a cash payment is not completed before the expiration date, and the seller decides to cancel it. And refunds occur when the payment is made, but the seller decides to cancel it, partially or entirely.
For more information, check the Refunds and Cancellations section.