Store and Manage Customers and Saved Cards in Java

The Mercado Pago Customers API lets you store buyer profiles and associate saved payment cards with them, enabling a faster, frictionless checkout for returning customers. The SDK provides two purpose-built clients: CustomerClient handles the full customer lifecycle (create, get, update, delete, search) and exposes convenience methods for card operations; CustomerCardClient manages the cards directly associated with a given customer. Card data is never sent to your server — a short-lived token produced by the MercadoPago.js frontend SDK is all you need to save a card securely.

Set your access token once at application startup before using any client:

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

Customer Management (`CustomerClient`)

Create a customer

Build a CustomerRequest with at minimum the customer’s email. Additional fields like firstName, lastName, phone, and identification improve match accuracy and checkout UX.

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.customer.CustomerClient;
import com.mercadopago.client.customer.CustomerRequest;
import com.mercadopago.client.common.IdentificationRequest;
import com.mercadopago.client.common.PhoneRequest;
import com.mercadopago.resources.customer.Customer;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

CustomerClient client = new CustomerClient();

CustomerRequest request = CustomerRequest.builder()
    .email("jane.doe@example.com")
    .firstName("Jane")
    .lastName("Doe")
    .phone(PhoneRequest.builder()
        .areaCode("11")
        .number("987654321")
        .build())
    .identification(IdentificationRequest.builder()
        .type("CPF")
        .number("12345678909")
        .build())
    .description("Premium subscriber")
    .build();

Customer customer = client.create(request);
System.out.println("Customer ID:   " + customer.getId());
System.out.println("Email:         " + customer.getEmail());
System.out.println("Date created:  " + customer.getDateCreated());

`CustomerRequest` fields

Field	Type	Description
`email`	`String`	Customer’s email address — used as the unique identifier
`firstName`	`String`	Customer’s first name
`lastName`	`String`	Customer’s last name
`phone`	`PhoneRequest`	Phone details including `areaCode` and `number`
`identification`	`IdentificationRequest`	Identity document (`type` + `number`, e.g. `CPF`, `DNI`)
`defaultAddress`	`String`	ID of the customer’s default address
`address`	`CustomerAddressRequest`	Address details for registration
`defaultCard`	`String`	ID of the customer’s default saved card
`dateRegistred`	`OffsetDateTime`	Registration date in your own system
`description`	`String`	Free-text notes about the customer
`metadata`	`Map<String, Object>`	Custom key-value pairs for your system

Get a customer

CustomerClient client = new CustomerClient();

Customer customer = client.get("1234567890-jnkFaAMdRGiP");
System.out.println("Name:  " + customer.getFirstName() + " " + customer.getLastName());
System.out.println("Email: " + customer.getEmail());
System.out.println("Cards: " + customer.getCards().size());

Update a customer

CustomerClient.update() accepts the same CustomerRequest builder as create. Include only the fields you want to change — omitted fields are left untouched.

CustomerClient client = new CustomerClient();

CustomerRequest updateRequest = CustomerRequest.builder()
    .firstName("Jane")
    .lastName("Smith")
    .description("VIP customer – tier upgraded")
    .build();

Customer updated = client.update("1234567890-jnkFaAMdRGiP", updateRequest);
System.out.println("Updated last name: " + updated.getLastName());
System.out.println("Last updated:      " + updated.getDateLastUpdated());

Delete a customer

CustomerClient client = new CustomerClient();

Customer deleted = client.delete("1234567890-jnkFaAMdRGiP");
System.out.println("Deleted customer: " + deleted.getId());

Deleting a customer also removes their associated saved cards. This action cannot be undone.

Search customers

CustomerClient.search(MPSearchRequest) returns a paginated MPResultsResourcesPage<Customer> supporting filters such as email.

import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.net.MPResultsResourcesPage;
import com.mercadopago.resources.customer.Customer;
import java.util.HashMap;
import java.util.Map;

CustomerClient client = new CustomerClient();

Map<String, Object> filters = new HashMap<>();
filters.put("email", "jane.doe@example.com");

MPSearchRequest searchRequest = MPSearchRequest.builder()
    .offset(0)
    .limit(10)
    .filters(filters)
    .build();

MPResultsResourcesPage<Customer> page = client.search(searchRequest);
System.out.println("Total results: " + page.getPaging().getTotal());
page.getResults().forEach(c ->
    System.out.println(c.getId() + " – " + c.getEmail())
);

Customer Cards (`CustomerCardClient`)

Saved cards belong to a customer and are identified by their own cardId. Before saving a card you must tokenize the card number in the browser or mobile app using the MercadoPago.js SDK — your backend only ever receives the resulting short-lived token, not raw card data.

PCI compliance: Raw card numbers, CVVs, and expiry dates must never touch your server. Always collect card data through the MercadoPago.js SDK on the client side to generate a card token, then pass only that token to the Java SDK.

Add a card to a customer

Pass the token produced by MercadoPago.js along with paymentMethodId (e.g. "visa", "master", "amex") to CustomerCardCreateRequest.

Tokenize the card on the frontend

Use the MercadoPago.js SDK in your browser or mobile app to create a card token from the cardholder’s raw data. You receive a short-lived token string.

Send the token to your backend

Your frontend submits the token value (and optionally paymentMethodId) to your server via a secure API call.

Save the card with the Java SDK

import com.mercadopago.client.customer.CustomerCardClient;
import com.mercadopago.client.customer.CustomerCardCreateRequest;
import com.mercadopago.resources.customer.CustomerCard;

CustomerCardClient cardClient = new CustomerCardClient();

CustomerCardCreateRequest cardRequest = CustomerCardCreateRequest.builder()
    .token("{{CARD_TOKEN_FROM_FRONTEND}}")
    .paymentMethodId("visa")
    .build();

CustomerCard savedCard = cardClient.create("1234567890-jnkFaAMdRGiP", cardRequest);
System.out.println("Card ID:         " + savedCard.getId());
System.out.println("Last four:       " + savedCard.getLastFourDigits());
System.out.println("Payment method:  " + savedCard.getPaymentMethod().getId());
System.out.println("Expiry:          " + savedCard.getExpirationMonth()
                                       + "/" + savedCard.getExpirationYear());

You can also call the same method via the CustomerClient convenience wrapper:

CustomerClient client = new CustomerClient();

CustomerCard savedCard = client.createCard("1234567890-jnkFaAMdRGiP",
    CustomerCardCreateRequest.builder()
        .token("{{CARD_TOKEN_FROM_FRONTEND}}")
        .paymentMethodId("master")
        .build());

System.out.println("Saved card ID: " + savedCard.getId());

`CustomerCardCreateRequest` fields

Field	Type	Description
`token`	`String`	Temporary card token generated by MercadoPago.js on the frontend
`paymentMethodId`	`String`	Payment method identifier (`"visa"`, `"master"`, `"amex"`, etc.)
`issuer`	`CustomerCardIssuer`	Optional issuing bank details

Get a specific card

CustomerCardClient cardClient = new CustomerCardClient();

CustomerCard card = cardClient.get(
    "1234567890-jnkFaAMdRGiP",   // customerId
    "1234567890"                   // cardId
);
System.out.println("BIN (first six): " + card.getFirstSixDigits());
System.out.println("Last four:       " + card.getLastFourDigits());
System.out.println("Expiry:          " + card.getExpirationMonth()
                                       + "/" + card.getExpirationYear());
System.out.println("Cardholder:      " + card.getCardholder().getName());

List all cards for a customer

CustomerCardClient.listAll(customerId) returns an MPResourceList<CustomerCard> containing every saved card for the given customer.

import com.mercadopago.net.MPResourceList;
import com.mercadopago.resources.customer.CustomerCard;

CustomerCardClient cardClient = new CustomerCardClient();

MPResourceList<CustomerCard> cards = cardClient.listAll("1234567890-jnkFaAMdRGiP");
System.out.println("Saved cards: " + cards.getResults().size());
cards.getResults().forEach(c ->
    System.out.println(c.getId()
        + " – **** " + c.getLastFourDigits()
        + " (" + c.getPaymentMethod().getId() + ")")
);

The same operation is available through CustomerClient:

CustomerClient client = new CustomerClient();
MPResourceList<CustomerCard> cards = client.listCards("1234567890-jnkFaAMdRGiP");

Delete a card

CustomerCardClient cardClient = new CustomerCardClient();

CustomerCard removed = cardClient.delete(
    "1234567890-jnkFaAMdRGiP",  // customerId
    "1234567890"                  // cardId
);
System.out.println("Removed card ID: " + removed.getId());

Via CustomerClient:

CustomerClient client = new CustomerClient();
CustomerCard removed = client.deleteCard("1234567890-jnkFaAMdRGiP", "1234567890");

Error handling

Both clients throw MPException for transport errors and MPApiException when the API returns a non-2xx status.

import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;

try {
    Customer customer = client.create(request);
} catch (MPApiException e) {
    System.err.println("API error – status: " + e.getStatusCode());
    System.err.println("Message: "            + e.getMessage());
} catch (MPException e) {
    System.err.println("SDK error: " + e.getMessage());
}

Search for an existing customer by email before creating a new one to avoid duplicates. A single email address can only be registered once per Mercado Pago account.

Get Started

Guides

Store and Manage Customers and Saved Cards in Java

Customer Management (`CustomerClient`)

Create a customer

`CustomerRequest` fields

Get a customer

Update a customer

Delete a customer

Search customers

Customer Cards (`CustomerCardClient`)

Add a card to a customer

`CustomerCardCreateRequest` fields

Get a specific card

List all cards for a customer

Delete a card

Error handling

Build docs developers (and LLMs) love

Get Started

Guides

Documentation Index

​Customer Management (CustomerClient)

​Create a customer

​CustomerRequest fields

​Get a customer

​Update a customer

​Delete a customer

​Search customers

​Customer Cards (CustomerCardClient)

​Add a card to a customer

​CustomerCardCreateRequest fields

​Get a specific card

​List all cards for a customer

​Delete a card

​Error handling

Build docs developers (and LLMs) love

Customer Management (`CustomerClient`)

Create a customer

`CustomerRequest` fields

Get a customer

Update a customer

Delete a customer

Search customers

Customer Cards (`CustomerCardClient`)

Add a card to a customer

`CustomerCardCreateRequest` fields

Get a specific card

List all cards for a customer

Delete a card

Error handling