Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mercadopago/sdk-java/llms.txt

Use this file to discover all available pages before exploring further.

CustomerClient and CustomerCardClient are the two classes in the com.mercadopago.client.customer package that manage customer profiles and their associated saved payment cards. CustomerClient handles full CRUD operations on customer records and exposes convenience methods that delegate card operations to an internal CustomerCardClient instance. You can also instantiate CustomerCardClient directly if you only need card-level operations.

​
CustomerClient

Package: com.mercadopago.client.customer

​
Constructors

// Uses the default HTTP client configured in MercadoPagoConfig
CustomerClient()

// Supply a custom MPHttpClient (useful for testing or proxy scenarios)
CustomerClient(MPHttpClient httpClient)

​
Methods

​
get

Retrieves a customer by their unique identifier. 
Customer get(String customerId) throws MPException, MPApiException
Customer get(String customerId, MPRequestOptions requestOptions) throws MPException, MPApiException
​
customerId
String
required
Unique identifier of the customer to retrieve.
​
requestOptions
MPRequestOptions
Optional per-request overrides for access token, headers, or timeouts. Pass null to use defaults.
Returns: Customer

​
create

Creates a new customer record. 
Customer create(CustomerRequest request) throws MPException, MPApiException
Customer create(CustomerRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException
​
request
CustomerRequest
required
Customer details to create. See CustomerRequest fields.
​
requestOptions
MPRequestOptions
Optional per-request overrides for access token, headers, or timeouts.
Returns: Customer

​
update

Updates an existing customer’s details. 
Customer update(String customerId, CustomerRequest request) throws MPException, MPApiException
Customer update(String customerId, CustomerRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException
​
customerId
String
required
Unique identifier of the customer to update.
​
request
CustomerRequest
required
Updated customer fields. Only the fields you include will be modified.
​
requestOptions
MPRequestOptions
Optional per-request overrides.
Returns: Customer

​
delete

Deletes a customer by their unique identifier. 
Customer delete(String customerId) throws MPException, MPApiException
Customer delete(String customerId, MPRequestOptions requestOptions) throws MPException, MPApiException
​
customerId
String
required
Unique identifier of the customer to delete.
​
requestOptions
MPRequestOptions
Optional per-request overrides.
Returns: Customer — the deleted customer object as returned by the API.
Searches for customers matching the specified criteria with pagination. 
MPResultsResourcesPage<Customer> search(MPSearchRequest request) throws MPException, MPApiException
MPResultsResourcesPage<Customer> search(MPSearchRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException
​
request
MPSearchRequest
required
Search filters and pagination parameters (e.g., email, offset, limit).
​
requestOptions
MPRequestOptions
Optional per-request overrides.
Returns: MPResultsResourcesPage<Customer> — paginated list of matching customers.

​
Card convenience methods

CustomerClient exposes card operations as convenience wrappers that delegate to the internal CustomerCardClient: 
CustomerCard getCard(String customerId, String cardId) throws MPException, MPApiException
CustomerCard getCard(String customerId, String cardId, MPRequestOptions requestOptions) throws MPException, MPApiException

CustomerCard createCard(String customerId, CustomerCardCreateRequest request) throws MPException, MPApiException
CustomerCard createCard(String customerId, CustomerCardCreateRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

CustomerCard deleteCard(String customerId, String cardId) throws MPException, MPApiException
CustomerCard deleteCard(String customerId, String cardId, MPRequestOptions requestOptions) throws MPException, MPApiException

MPResourceList<CustomerCard> listCards(String customerId) throws MPException, MPApiException
MPResourceList<CustomerCard> listCards(String customerId, MPRequestOptions requestOptions) throws MPException, MPApiException

​
CustomerRequest fields

CustomerRequest is a Lombok @Builder class with the following fields:
​
email
String
Customer’s email address. Used as a unique identifier for the customer.
​
firstName
String
Customer’s first name.
​
lastName
String
Customer’s last name.
​
phone
PhoneRequest
Phone details including area code and number.
​
identification
IdentificationRequest
Identification document details (e.g., CPF, DNI, type and number).
​
defaultAddress
String
ID of the customer’s default address from their saved address list.
​
address
CustomerAddressRequest
Address details including zipCode, streetName, and streetNumber.
​
defaultCard
String
ID of the customer’s default saved card.
​
dateRegistred
OffsetDateTime
Date when the customer was registered in the merchant’s own system.
​
description
String
Free-text notes about the customer.
​
metadata
Map<String, Object>
Custom key-value metadata attached to the customer record.

​
CustomerCardClient

Package: com.mercadopago.client.customer CustomerCardClient manages saved payment cards for a given customer. It is instantiated automatically by CustomerClient, but can also be used independently.

​
Constructors

CustomerCardClient()
CustomerCardClient(MPHttpClient httpClient)

​
Methods

​
get

Retrieves a specific saved card belonging to a customer. 
CustomerCard get(String customerId, String cardId) throws MPException, MPApiException
CustomerCard get(String customerId, String cardId, MPRequestOptions requestOptions) throws MPException, MPApiException
​
customerId
String
required
Unique identifier of the customer.
​
cardId
String
required
Unique identifier of the saved card.
​
requestOptions
MPRequestOptions
Optional per-request overrides.
Returns: CustomerCard

​
create

Associates a new card with a customer using a card token generated by MercadoPago.js. 
CustomerCard create(String customerId, CustomerCardCreateRequest request) throws MPException, MPApiException
CustomerCard create(String customerId, CustomerCardCreateRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException
​
customerId
String
required
Unique identifier of the customer.
​
request
CustomerCardCreateRequest
required
Card token and payment method details. Fields:
  • token (String) — card token from MercadoPago.js
  • paymentMethodId (String) — e.g., "visa", "master", "amex"
  • issuer (CustomerCardIssuer) — issuing bank information
​
requestOptions
MPRequestOptions
Optional per-request overrides.
Returns: CustomerCard

​
delete

Removes a saved card from a customer. 
CustomerCard delete(String customerId, String cardId) throws MPException, MPApiException
CustomerCard delete(String customerId, String cardId, MPRequestOptions requestOptions) throws MPException, MPApiException
​
customerId
String
required
Unique identifier of the customer.
​
cardId
String
required
Unique identifier of the card to remove.
​
requestOptions
MPRequestOptions
Optional per-request overrides.
Returns: CustomerCard — the removed card as returned by the API.

​
listAll

Lists all saved cards belonging to a customer. 
MPResourceList<CustomerCard> listAll(String customerId) throws MPException, MPApiException
MPResourceList<CustomerCard> listAll(String customerId, MPRequestOptions requestOptions) throws MPException, MPApiException
​
customerId
String
required
Unique identifier of the customer.
​
requestOptions
MPRequestOptions
Optional per-request overrides.
Returns: MPResourceList<CustomerCard>

​
Code Example

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.customer.CustomerCardCreateRequest;
import com.mercadopago.client.customer.CustomerClient;
import com.mercadopago.client.customer.CustomerRequest;
import com.mercadopago.net.MPResourceList;
import com.mercadopago.net.MPResultsResourcesPage;
import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.resources.customer.Customer;
import com.mercadopago.resources.customer.CustomerCard;

import java.util.HashMap;
import java.util.Map;

// Configure your access token once at application startup
MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

CustomerClient client = new CustomerClient();

// Create a customer
CustomerRequest createRequest = CustomerRequest.builder()
    .email("jane.doe@example.com")
    .firstName("Jane")
    .lastName("Doe")
    .build();
Customer customer = client.create(createRequest);
System.out.println("Created customer: " + customer.getId());

// Retrieve the customer
Customer retrieved = client.get(customer.getId());

// Update the customer
CustomerRequest updateRequest = CustomerRequest.builder()
    .description("VIP customer")
    .build();
Customer updated = client.update(customer.getId(), updateRequest);

// Search customers by email
Map<String, Object> filters = new HashMap<>();
filters.put("email", "jane.doe@example.com");
MPSearchRequest searchRequest = MPSearchRequest.builder()
    .filters(filters)
    .limit(10)
    .offset(0)
    .build();
MPResultsResourcesPage<Customer> results = client.search(searchRequest);

// Associate a card (token produced by MercadoPago.js on the frontend)
CustomerCardCreateRequest cardRequest = CustomerCardCreateRequest.builder()
    .token("card_token_from_frontend")
    .paymentMethodId("visa")
    .build();
CustomerCard card = client.createCard(customer.getId(), cardRequest);

// List all saved cards
MPResourceList<CustomerCard> cards = client.listCards(customer.getId());
cards.getResults().forEach(c -> System.out.println("Card: " + c.getId()));

// Delete a card
client.deleteCard(customer.getId(), card.getId());

// Delete the customer
client.delete(customer.getId());

Build docs developers (and LLMs) love

Get started for freeTalk to us