This class holds all SDK-wide settings such as the OAuth access token, HTTP timeouts, * connection pool limits, proxy configuration, logging behavior, and tracking identifiers. * All fields are static and thread-safe (declared {@code volatile} or synchronized), so a * single configuration applies across the entire application. * *
Per-request overrides (e.g., a different access token or timeout for one call) can be * specified via {@link com.mercadopago.core.MPRequestOptions}; any field left at its * zero/null default in that object will fall back to the values defined here. * *
Usage example: *
{@code
* MercadoPagoConfig.setAccessToken("APP_USR-...");
* MercadoPagoConfig.setConnectionTimeout(30000);
* }
*
* @see com.mercadopago.core.MPRequestOptions
* @see com.mercadopago.net.MPDefaultHttpClient
*/
public class MercadoPagoConfig {
public static final String CURRENT_VERSION = "3.1.0";
/** Internal MercadoPago product identifier sent in every API request for analytics. */
public static final String PRODUCT_ID = "BC32A7VTRPP001U8NHJ0";
/**
* Tracking header value sent with every API request. Encodes the Java runtime version
* and SDK version so the MercadoPago platform can identify the client environment.
*/
public static final String TRACKING_ID = String.format(
"platform:%s,type:SDK%s,so;",
MercadoPagoConfig.getJavaVersion(), MercadoPagoConfig.CURRENT_VERSION);
/** Base URL for all MercadoPago REST API calls. */
public static final String BASE_URL = "https://api.mercadopago.com";
/** Default maximum number of concurrent HTTP connections in the connection pool. Value: 10. */
private static final int DEFAULT_MAX_CONNECTIONS = 10;
/** Default timeout in milliseconds for establishing an HTTP connection. Value: 20 000 ms. */
private static final int DEFAULT_CONNECTION_TIMEOUT_MS = 20000;
/** Default timeout in milliseconds for obtaining a connection from the pool. Value: 20 000 ms. */
private static final int DEFAULT_CONNECTION_REQUEST_TIMEOUT_MS = 20000;
/** Default socket (read) timeout in milliseconds for waiting for response data. Value: 20 000 ms. */
private static final int DEFAULT_SOCKET_TIMEOUT_MS = 20000;
/** Default scope label used when reporting SDK metrics. Value: {@code "prod"}. */
private static final String DEFAULT_METRICS_SCOPE = "prod";
/** Default logging level for the SDK logger. Value: {@link Level#OFF} (logging disabled). */
private static final Level DEFAULT_LOGGING_LEVEL = Level.OFF;
/** OAuth access token used to authenticate API requests when no per-request token is provided. */
@Getter
@Setter
private static volatile String accessToken;
/** Platform identifier header sent with API requests for tracking and analytics. */
@Getter
@Setter
private static volatile String platformId;
/** Corporation identifier header sent with API requests for multi-entity tracking. */
@Getter
@Setter
private static volatile String corporationId;
/** Integrator identifier header sent with API requests to attribute traffic to a specific integrator. */
@Getter
@Setter
private static volatile String integratorId;
/**
* Custom {@link StreamHandler} for SDK log output. When {@code null}, a default
* {@link ConsoleHandler} is used instead.
*
* @see #getStreamHandler()
*/
@Getter
@Setter
private static volatile StreamHandler loggingHandler;
/** Scope label used when reporting SDK metrics. Defaults to {@code "prod"}. */
@Getter
@Setter
private static volatile String metricsScope = DEFAULT_METRICS_SCOPE;
/**
* Java {@link Level} controlling the verbosity of SDK log output. Defaults to
* {@link Level#OFF} (no logging).
*/
@Getter
@Setter
private static volatile Level loggingLevel = DEFAULT_LOGGING_LEVEL;
/** Maximum number of concurrent HTTP connections maintained in the connection pool. Defaults to 10. */
@Getter
@Setter
private static volatile int maxConnections = DEFAULT_MAX_CONNECTIONS;
/** Timeout in milliseconds for establishing a new HTTP connection. Defaults to 20 000 ms. */
@Getter
@Setter
private static volatile int connectionTimeout = DEFAULT_CONNECTION_TIMEOUT_MS;
/** Timeout in milliseconds for obtaining a connection from the pool. Defaults to 20 000 ms. */
@Getter
@Setter
private static volatile int connectionRequestTimeout = DEFAULT_CONNECTION_REQUEST_TIMEOUT_MS;
/** Timeout in milliseconds for waiting for response data on an open socket. Defaults to 20 000 ms. */
@Getter
@Setter
private static volatile int socketTimeout = DEFAULT_SOCKET_TIMEOUT_MS;
/**
* HTTP client implementation used for all API calls. Lazily initialized to
* {@link MPDefaultHttpClient} on first access via {@link #getHttpClient()}.
*/
@Setter
private static volatile MPHttpClient httpClient;
/**
* HTTP proxy host through which all API requests are routed. When {@code null},
* requests are made directly without a proxy.
*/
@Getter(onMethod_ = { @Synchronized })
@Setter(onMethod_ = { @Synchronized })
private static HttpHost proxy;
/**
* Custom retry handler for HTTP requests. When set, the underlying Apache HTTP client
* will delegate retry decisions to this handler instead of using its default strategy.
*/
@Getter
@Setter
private static HttpRequestRetryHandler retryHandler;
/**
* Returns the HTTP client used for API communication, creating a default
* {@link MPDefaultHttpClient} instance on first invocation (lazy initialization).
*
* The returned client is a singleton shared across all SDK calls. To replace it * with a custom implementation, use {@link #setHttpClient(MPHttpClient)} before making * any API requests. * * @return the current {@link MPHttpClient} instance, never {@code null} * @see MPDefaultHttpClient */ public static synchronized MPHttpClient getHttpClient() { if (Objects.isNull(httpClient)) { httpClient = new MPDefaultHttpClient(); } return httpClient; } /** * Returns the Java runtime version formatted as {@code "major|full"}. * *
For example, on Java 11.0.12+7, this method returns {@code "11|11.0.12+7"}. * The value is used in the {@link #TRACKING_ID} header sent with every API request. * * @return a string in the format {@code "majorVersion|fullVersion"}, or {@code null} * if the {@code java.runtime.version} system property is unavailable */ public static synchronized String getJavaVersion() { String version = System.getProperty("java.runtime.version"); if (Objects.isNull(version)) { return null; } String major = version.replaceAll("^1\\.", ""); int dotIndex = major.indexOf('.'); if (dotIndex != -1) { major = major.substring(0, dotIndex); } return major + "|" + version; } /** * Returns the active {@link StreamHandler} for SDK logging. If a custom handler has been * set via {@link #setLoggingHandler(StreamHandler)}, it is returned; otherwise a new * {@link ConsoleHandler} is created as a fallback. * * @return the configured {@link StreamHandler}, or a default {@link ConsoleHandler} */ public static StreamHandler getStreamHandler() { return Objects.nonNull(loggingHandler) ? loggingHandler : new ConsoleHandler(); } } ================================================ FILE: src/main/java/com/mercadopago/client/MercadoPagoClient.java ================================================ package com.mercadopago.client; import static java.util.Objects.nonNull; import static org.apache.commons.collections4.MapUtils.isNotEmpty; import static org.apache.commons.lang3.StringUtils.isNotBlank; import com.google.gson.JsonObject; import com.mercadopago.MercadoPagoConfig; import com.mercadopago.core.MPRequestOptions; import com.mercadopago.exceptions.MPApiException; import com.mercadopago.exceptions.MPException; import com.mercadopago.net.Headers; import com.mercadopago.net.HttpMethod; import com.mercadopago.net.MPHttpClient; import com.mercadopago.net.MPRequest; import com.mercadopago.net.MPResponse; import com.mercadopago.net.MPSearchRequest; import com.mercadopago.net.UrlFormatter; import java.util.HashMap; import java.util.Map; /** * Abstract base client for all MercadoPago API interactions. * *
This class provides the foundation for every specialized API client in the SDK. It handles * HTTP request execution, default and custom header management (including authorization via Bearer * tokens), timeout resolution with a three-level priority (request options, request object, global * config), and automatic idempotency key generation for {@code POST}, {@code PUT}, and * {@code PATCH} requests. * *
Subclasses should use the protected {@code send()}, {@code search()}, and {@code list()}
* helper methods to communicate with the MercadoPago REST API.
*
* @see com.mercadopago.MercadoPagoConfig
* @see MPHttpClient
* @see MPRequestOptions
*/
public abstract class MercadoPagoClient {
/** Default value for the {@code Accept} HTTP header. */
private static final String ACCEPT_HEADER_VALUE = "application/json";
/** Default value for the {@code Content-Type} HTTP header, including UTF-8 charset. */
private static final String CONTENT_TYPE_HEADER_VALUE = "application/json; charset=UTF-8";
/** Format string used to build the {@code Authorization: Bearer} header value. */
private static final String BEARER = "Bearer %s";
/** Path segment used to detect OAuth token requests and skip the Bearer header. */
private static final String OAUTH_TOKEN = "/oauth/token";
/** HTTP client used to execute every request dispatched by this client instance. */
protected final MPHttpClient httpClient;
/**
* Default HTTP headers sent with every request. Populated during construction with
* {@code Accept}, {@code Content-Type}, {@code User-Agent}, {@code Product-Id}, and
* {@code Tracking-Id}.
*/
protected Map Initialises the default headers map with {@code Accept}, {@code Content-Type},
* {@code User-Agent}, {@code Product-Id}, and {@code Tracking-Id} values taken from
* {@link MercadoPagoConfig}.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public MercadoPagoClient(MPHttpClient httpClient) {
this.httpClient = httpClient;
this.defaultHeaders = new HashMap<>();
defaultHeaders.put(Headers.ACCEPT, ACCEPT_HEADER_VALUE);
defaultHeaders.put(Headers.PRODUCT_ID, MercadoPagoConfig.PRODUCT_ID);
defaultHeaders.put(
Headers.USER_AGENT,
String.format("MercadoPago Java SDK/%s", MercadoPagoConfig.CURRENT_VERSION));
defaultHeaders.put(Headers.TRACKING_ID, MercadoPagoConfig.TRACKING_ID);
defaultHeaders.put(Headers.CONTENT_TYPE, CONTENT_TYPE_HEADER_VALUE);
}
/**
* Sends an HTTP request using the pre-built {@link MPRequest} object with default configuration.
*
* This is a convenience overload that delegates to {@link #send(MPRequest, MPRequestOptions)}
* with {@code null} request options, meaning global configuration from
* {@link MercadoPagoConfig} is used for timeouts and access tokens.
*
* @param request the {@link MPRequest} containing URI, HTTP method, payload, and query parameters
* @return the {@link MPResponse} with status code, headers, and body returned by the API
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
protected MPResponse send(MPRequest request) throws MPException, MPApiException {
return this.send(request, null);
}
/**
* Sends an HTTP request using the pre-built {@link MPRequest} object, applying optional
* per-request overrides.
*
* This method resolves the final URL (formatting query parameters), selects the access token
* (preferring {@code requestOptions} over global config), merges default and custom headers,
* and resolves timeouts with a three-level priority: request options > request object >
* {@link MercadoPagoConfig} defaults. An idempotency key is automatically generated for
* {@code POST}, {@code PUT}, and {@code PATCH} methods unless one is already present.
*
* @param request the {@link MPRequest} containing URI, HTTP method, payload, and query parameters
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link MPResponse} with status code, headers, and body returned by the API
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
protected MPResponse send(MPRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
String uri = UrlFormatter.format(request.getUri(), request.getQueryParams());
return httpClient.send(
MPRequest.builder()
.uri(uri)
.accessToken(getAccessToken(requestOptions))
.method(request.getMethod())
.headers(addRequestHeaders(request, requestOptions))
.payload(request.getPayload())
.connectionRequestTimeout(addConnectionRequestTimeout(request, requestOptions))
.connectionTimeout(addConnectionTimeout(request, requestOptions))
.socketTimeout(addSocketTimeout(request, requestOptions))
.build());
}
/**
* Builds and sends an HTTP request from individual components with default configuration.
*
* This is a convenience overload that delegates to
* {@link #send(String, HttpMethod, JsonObject, Map, MPRequestOptions)} with {@code null}
* request options.
*
* @param path the relative API path (e.g. {@code "/v1/payments"})
* @param method the {@link HttpMethod} to use (GET, POST, PUT, DELETE, PATCH)
* @param payload the JSON request body, or {@code null} for body-less requests
* @param queryParams a map of query-string parameters, or {@code null} if none
* @return the {@link MPResponse} with status code, headers, and body returned by the API
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
protected MPResponse send(
String path, HttpMethod method, JsonObject payload, Map Internally constructs an {@link MPRequest} via {@code buildRequest()}, then delegates to
* {@link #send(MPRequest)}. This is the most flexible {@code send()} variant and is the
* ultimate target of all other convenience overloads.
*
* @param path the relative API path (e.g. {@code "/v1/payments"})
* @param method the {@link HttpMethod} to use (GET, POST, PUT, DELETE, PATCH)
* @param payload the JSON request body, or {@code null} for body-less requests
* @param queryParams a map of query-string parameters, or {@code null} if none
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link MPResponse} with status code, headers, and body returned by the API
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
protected MPResponse send(
String path,
HttpMethod method,
JsonObject payload,
Map Delegates to {@link #search(String, MPSearchRequest, MPRequestOptions)} with {@code null}
* request options.
*
* @param path the relative API path for the search endpoint (e.g. {@code "/v1/payments/search"})
* @param request the {@link MPSearchRequest} containing search/filter/pagination parameters, or
* {@code null} for an unfiltered search
* @return the {@link MPResponse} with the search results returned by the API
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
protected MPResponse search(String path, MPSearchRequest request)
throws MPException, MPApiException {
return this.search(path, request, null);
}
/**
* Performs a search request against the given API path, applying optional per-request overrides.
*
* Extracts query parameters from the {@link MPSearchRequest} and issues an HTTP {@code GET}
* via the underlying {@code send()} method. If {@code searchRequest} is {@code null}, no
* query parameters are appended.
*
* @param path the relative API path for the search endpoint (e.g. {@code "/v1/payments/search"})
* @param searchRequest the {@link MPSearchRequest} containing search/filter/pagination
* parameters, or {@code null} for an unfiltered search
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link MPResponse} with the search results returned by the API
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
protected MPResponse search(
String path, MPSearchRequest searchRequest, MPRequestOptions requestOptions)
throws MPException, MPApiException {
Map This is a convenience overload that delegates to
* {@link #list(String, HttpMethod, JsonObject, Map, MPRequestOptions)} using {@code GET} with
* no payload or query parameters.
*
* @param path the relative API path for the list endpoint
* (e.g. {@code "/v1/customers/123/cards"})
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link MPResponse} containing the list of resources returned by the API
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
protected MPResponse list(String path, MPRequestOptions requestOptions)
throws MPException, MPApiException {
return this.list(path, HttpMethod.GET, null, null, requestOptions);
}
/**
* Performs an HTTP request that returns a list of resources, with full control over all request
* parameters.
*
* This method is functionally identical to
* {@link #send(String, HttpMethod, JsonObject, Map, MPRequestOptions)} and exists as a
* semantic alias to improve readability in subclasses that list resources.
*
* @param path the relative API path for the list endpoint
* @param method the {@link HttpMethod} to use (typically {@code GET})
* @param payload the JSON request body, or {@code null} for body-less requests
* @param queryParams a map of query-string parameters, or {@code null} if none
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link MPResponse} containing the list of resources returned by the API
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
protected MPResponse list(
String path,
HttpMethod method,
JsonObject payload,
Map Provides PCI-compliant card tokenization operations. Tokens represent card data securely
* and are used when creating payments or saving cards to a customer profile.
*
* Usage example:
* Provides operations to get, create, delete, and list cards associated with a customer.
* Cards are stored securely and can be reused for future payments without requiring the payer
* to re-enter card details.
*
* This client is typically used internally by {@link CustomerClient}, but can also be
* instantiated directly.
*
* @see CustomerClient
* @see
* Customer Cards API reference
*/
public class CustomerCardClient extends MercadoPagoClient {
/** Class-level logger for customer card operations. */
private static final Logger LOGGER = Logger.getLogger(CustomerCardClient.class.getName());
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public CustomerCardClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code CustomerCardClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public CustomerCardClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Retrieves a specific card belonging to a customer.
*
* @param customerId the unique identifier of the customer who owns the card
* @param cardId the unique identifier of the card to retrieve
* @return the requested {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public CustomerCard get(String customerId, String cardId) throws MPException, MPApiException {
return this.get(customerId, cardId, null);
}
/**
* Retrieves a specific card belonging to a customer with custom request options.
*
* @param customerId the unique identifier of the customer who owns the card
* @param cardId the unique identifier of the card to retrieve
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public CustomerCard get(String customerId, String cardId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
MPResponse response =
send(
String.format("/v1/customers/%s/cards/%s", customerId, cardId),
HttpMethod.GET,
null,
null,
requestOptions);
CustomerCard card = Serializer.deserializeFromJson(CustomerCard.class, response.getContent());
card.setResponse(response);
return card;
}
/**
* Creates and associates a new card with a customer.
*
* @param customerId the unique identifier of the customer
* @param request the {@link CustomerCardCreateRequest} with the card token and other details
* @return the newly created {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public CustomerCard create(String customerId, CustomerCardCreateRequest request)
throws MPException, MPApiException {
return this.create(customerId, request, null);
}
/**
* Creates and associates a new card with a customer with custom request options.
*
* @param customerId the unique identifier of the customer
* @param request the {@link CustomerCardCreateRequest} with the card token and other details
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the newly created {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public CustomerCard create(
String customerId, CustomerCardCreateRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending create customer card request");
JsonObject payload = Serializer.serializeToJson(request);
MPRequest mpRequest =
MPRequest.buildRequest(
String.format("/v1/customers/%s/cards", customerId),
HttpMethod.POST,
payload,
null,
requestOptions);
MPResponse response = send(mpRequest);
CustomerCard card = Serializer.deserializeFromJson(CustomerCard.class, response.getContent());
card.setResponse(response);
return card;
}
/**
* Removes a card from a customer.
*
* @param customerId the unique identifier of the customer
* @param cardId the unique identifier of the card to remove
* @return the removed {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public CustomerCard delete(String customerId, String cardId) throws MPException, MPApiException {
return this.delete(customerId, cardId, null);
}
/**
* Removes a card from a customer with custom request options.
*
* @param customerId the unique identifier of the customer
* @param cardId the unique identifier of the card to remove
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the removed {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public CustomerCard delete(String customerId, String cardId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending delete customer card request");
MPResponse response =
send(
String.format("/v1/customers/%s/cards/%s", customerId, cardId),
HttpMethod.DELETE,
null,
null,
requestOptions);
CustomerCard card = Serializer.deserializeFromJson(CustomerCard.class, response.getContent());
card.setResponse(response);
return card;
}
/**
* Lists all cards belonging to a customer.
*
* @param customerId the unique identifier of the customer
* @return an {@link MPResourceList} of {@link CustomerCard} for the given customer
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public MPResourceList Provides CRUD operations for customers (create, get, update, delete) and search with
* pagination. Card operations (get, create, delete, list) are delegated to an internal
* {@link CustomerCardClient} and exposed via convenience methods on this class.
*
* Usage example:
* Also initialises the internal {@link CustomerCardClient} with the same HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public CustomerClient(MPHttpClient httpClient) {
super(httpClient);
cardClient = new CustomerCardClient(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Retrieves a customer by its unique identifier.
*
* @param customerId the unique identifier of the customer
* @return the requested {@link Customer}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Customer get(String customerId) throws MPException, MPApiException {
return this.get(customerId, null);
}
/**
* Retrieves a customer by its unique identifier with custom request options.
*
* @param customerId the unique identifier of the customer
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link Customer}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Customer get(String customerId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending get customer request");
MPResponse response =
send(
String.format("/v1/customers/%s", customerId),
HttpMethod.GET,
null,
null,
requestOptions);
Customer customer = Serializer.deserializeFromJson(Customer.class, response.getContent());
customer.setResponse(response);
return customer;
}
/**
* Creates a new customer.
*
* @param request the {@link CustomerRequest} with customer details (email, identification, etc.)
* @return the newly created {@link Customer}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Customer create(CustomerRequest request) throws MPException, MPApiException {
return this.create(request, null);
}
/**
* Creates a new customer with custom request options.
*
* @param request the {@link CustomerRequest} with customer details (email, identification, etc.)
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the newly created {@link Customer}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Customer create(CustomerRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending create customer request");
JsonObject payload = Serializer.serializeToJson(request);
MPRequest mpRequest =
MPRequest.buildRequest("/v1/customers", HttpMethod.POST, payload, null, requestOptions);
MPResponse response = send(mpRequest);
Customer customer = Serializer.deserializeFromJson(Customer.class, response.getContent());
customer.setResponse(response);
return customer;
}
/**
* Updates an existing customer.
*
* @param customerId the unique identifier of the customer to update
* @param request the {@link CustomerRequest} with the updated customer details
* @return the updated {@link Customer}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Customer update(String customerId, CustomerRequest request)
throws MPException, MPApiException {
return this.update(customerId, request, null);
}
/**
* Updates an existing customer with custom request options.
*
* @param customerId the unique identifier of the customer to update
* @param request the {@link CustomerRequest} with the updated customer details
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the updated {@link Customer}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Customer update(
String customerId, CustomerRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending update customer request");
JsonObject payload = Serializer.serializeToJson(request);
MPRequest mpRequest =
MPRequest.buildRequest(
String.format("/v1/customers/%s", customerId),
HttpMethod.PUT,
payload,
null,
requestOptions);
MPResponse response = send(mpRequest);
Customer customer = Serializer.deserializeFromJson(Customer.class, response.getContent());
customer.setResponse(response);
return customer;
}
/**
* Deletes a customer by its unique identifier.
*
* @param customerId the unique identifier of the customer to delete
* @return the deleted {@link Customer}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Customer delete(String customerId) throws MPException, MPApiException {
return this.delete(customerId, null);
}
/**
* Deletes a customer by its unique identifier with custom request options.
*
* @param customerId the unique identifier of the customer to delete
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the deleted {@link Customer}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Customer delete(String customerId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending delete customer request");
MPRequest mpRequest =
MPRequest.buildRequest(
String.format("/v1/customers/%s", customerId),
HttpMethod.DELETE,
null,
null,
requestOptions);
MPResponse response = send(mpRequest);
Customer customer = Serializer.deserializeFromJson(Customer.class, response.getContent());
customer.setResponse(response);
return customer;
}
/**
* Searches for customers matching the specified criteria.
*
* @param request the {@link MPSearchRequest} containing search filters and pagination parameters
* @return an {@link MPResultsResourcesPage} of {@link Customer} with matching results and
* pagination metadata
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MPResultsResourcesPage Delegates to the internal {@link CustomerCardClient}.
*
* @param customerId the unique identifier of the customer
* @param cardId the unique identifier of the card
* @return the requested {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public CustomerCard getCard(String customerId, String cardId) throws MPException, MPApiException {
return this.getCard(customerId, cardId, null);
}
/**
* Retrieves a specific card associated with a customer with custom request options.
*
* Delegates to the internal {@link CustomerCardClient}.
*
* @param customerId the unique identifier of the customer
* @param cardId the unique identifier of the card
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public CustomerCard getCard(String customerId, String cardId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
return cardClient.get(customerId, cardId, requestOptions);
}
/**
* Associates a new card with a customer.
*
* Delegates to the internal {@link CustomerCardClient}.
*
* @param customerId the unique identifier of the customer
* @param request the {@link CustomerCardCreateRequest} with the card token and other details
* @return the newly created {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public CustomerCard createCard(String customerId, CustomerCardCreateRequest request)
throws MPException, MPApiException {
return this.createCard(customerId, request, null);
}
/**
* Associates a new card with a customer with custom request options.
*
* Delegates to the internal {@link CustomerCardClient}.
*
* @param customerId the unique identifier of the customer
* @param request the {@link CustomerCardCreateRequest} with the card token and other details
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the newly created {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public CustomerCard createCard(
String customerId, CustomerCardCreateRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
return cardClient.create(customerId, request, requestOptions);
}
/**
* Removes a card from a customer.
*
* Delegates to the internal {@link CustomerCardClient}.
*
* @param customerId the unique identifier of the customer
* @param cardId the unique identifier of the card to remove
* @return the removed {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public CustomerCard deleteCard(String customerId, String cardId)
throws MPException, MPApiException {
return this.deleteCard(customerId, cardId, null);
}
/**
* Removes a card from a customer with custom request options.
*
* Delegates to the internal {@link CustomerCardClient}.
*
* @param customerId the unique identifier of the customer
* @param cardId the unique identifier of the card to remove
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the removed {@link CustomerCard}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public CustomerCard deleteCard(String customerId, String cardId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
return cardClient.delete(customerId, cardId, requestOptions);
}
/**
* Lists all cards associated with a customer.
*
* Delegates to the internal {@link CustomerCardClient}.
*
* @param customerId the unique identifier of the customer
* @return an {@link MPResourceList} of {@link CustomerCard} for the given customer
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MPResourceList Delegates to the internal {@link CustomerCardClient}.
*
* @param customerId the unique identifier of the customer
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return an {@link MPResourceList} of {@link CustomerCard} for the given customer
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MPResourceList Retrieves the list of identification document types available for the country associated
* with the authenticated user's credentials (e.g., CPF for Brazil, DNI for Argentina).
*
* Usage example:
* Provides operations to create, retrieve, update, and search merchant orders. Merchant orders
* group one or more payments and can be associated with preferences, shipments, or external
* references.
*
* Usage example:
* Provides operations for the OAuth authorization flow used in marketplace and platform
* integrations: generating authorization URLs, creating credentials from authorization codes,
* and refreshing expired tokens.
*
* Usage example:
* Also initialises the internal {@link UserClient} with the same HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public OauthClient(MPHttpClient httpClient) {
super(httpClient);
userClient = new UserClient(httpClient);
}
/**
* Builds the OAuth authorization URL that the seller must visit to grant access.
*
* Internally fetches the authenticated user's country to construct the correct
* country-specific authorization host.
*
* @param appId the application ID (client_id) registered in MercadoPago
* @param redirectUri the URL to which the user is redirected after authorizing
* @return the full authorization URL, or {@code null} if the user's country cannot be determined
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public String getAuthorizationURL(String appId, String redirectUri)
throws MPException, MPApiException {
return this.getAuthorizationURL(appId, redirectUri, null);
}
/**
* Builds the OAuth authorization URL with custom request options.
*
* Internally fetches the authenticated user's country to construct the correct
* country-specific authorization host.
*
* @param appId the application ID (client_id) registered in MercadoPago
* @param redirectUri the URL to which the user is redirected after authorizing
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the full authorization URL, or {@code null} if the user's country cannot be determined
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public String getAuthorizationURL(
String appId, String redirectUri, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending get oauth authorization url request");
User user = userClient.get(requestOptions);
if (Objects.isNull(user) || user.getCountryId().isEmpty()) {
return null;
}
HashMap Used in the marketplace authorization flow to operate on behalf of a seller. See the
* OAuth guide
* for more details.
*
* @param authorizationCode the authorization code received after the seller grants access via the
* authorization URL
* @param redirectUri the same redirect URI used when generating the authorization URL
* @return the {@link CreateOauthCredential} containing access token, refresh token, and
* expiration
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public CreateOauthCredential createCredential(String authorizationCode, String redirectUri)
throws MPException, MPApiException {
return this.createCredential(authorizationCode, redirectUri, null);
}
/**
* Creates OAuth credentials with custom request options by exchanging an authorization code.
*
* Used in the marketplace authorization flow to operate on behalf of a seller. See the
* OAuth guide
* for more details.
*
* @param authorizationCode the authorization code received after the seller grants access via the
* authorization URL
* @param redirectUri the same redirect URI used when generating the authorization URL
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link CreateOauthCredential} containing access token, refresh token, and
* expiration
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public CreateOauthCredential createCredential(
String authorizationCode, String redirectUri, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending create oauth credential request");
CreateOauthCredentialRequest request =
CreateOauthCredentialRequest.builder()
.clientSecret(getAccessToken(requestOptions))
.code(authorizationCode)
.redirectUri(redirectUri)
.build();
MPRequest mpRequest =
MPRequest.buildRequest(
path, HttpMethod.POST, Serializer.serializeToJson(request), null, requestOptions);
MPResponse response = send(mpRequest);
CreateOauthCredential credential =
Serializer.deserializeFromJson(CreateOauthCredential.class, response.getContent());
credential.setResponse(response);
return credential;
}
/**
* Refreshes OAuth credentials using a previously obtained refresh token.
*
* @param refreshToken the refresh token received during credential creation
* @return a new {@link RefreshOauthCredential} containing a fresh access token and refresh token
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public RefreshOauthCredential refreshCredential(String refreshToken)
throws MPException, MPApiException {
return this.refreshCredential(refreshToken, null);
}
/**
* Refreshes OAuth credentials with custom request options.
*
* @param refreshToken the refresh token received during credential creation
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return a new {@link RefreshOauthCredential} containing a fresh access token and refresh token
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public RefreshOauthCredential refreshCredential(
String refreshToken, MPRequestOptions requestOptions) throws MPException, MPApiException {
LOGGER.info("Sending refresh oauth credential request");
RefreshOauthCredentialRequest request =
RefreshOauthCredentialRequest.builder()
.clientSecret(getAccessToken(requestOptions))
.refreshToken(refreshToken)
.build();
MPRequest mpRequest =
MPRequest.buildRequest(
path, HttpMethod.POST, Serializer.serializeToJson(request), null, requestOptions);
MPResponse response = send(mpRequest);
RefreshOauthCredential credential =
Serializer.deserializeFromJson(RefreshOauthCredential.class, response.getContent());
credential.setResponse(response);
return credential;
}
private String getAccessToken(MPRequestOptions requestOptions) {
return Objects.isNull(requestOptions)
? MercadoPagoConfig.getAccessToken()
: requestOptions.getAccessToken();
}
}
================================================
FILE: src/main/java/com/mercadopago/client/oauth/RefreshOauthCredentialRequest.java
================================================
package com.mercadopago.client.oauth;
import lombok.Builder;
import lombok.Getter;
/**
* Request DTO used to refresh an expired OAuth access token using a previously obtained refresh
* token. This avoids requiring the seller to re-authorize the application and ensures
* uninterrupted API access.
*
* @see OAuth Guide
*/
@Getter
@Builder
public class RefreshOauthCredentialRequest {
/**
* Grant type for the OAuth token request. Fixed as {@code "refresh_token"} for the token
* refresh flow.
*/
private final String grantType = "refresh_token";
/**
* Application secret key (client_secret) used to authenticate the refresh request. Obtained
* from the Mercado Pago developer credentials panel.
*/
private final String clientSecret;
/**
* Application ID (client_id) that uniquely identifies your integration in Mercado Pago.
*/
private final String clientId;
/** Refresh token obtained from the initial OAuth authorization code exchange. */
private final String refreshToken;
}
================================================
FILE: src/main/java/com/mercadopago/client/order/AdditionalInfoRequest.java
================================================
package com.mercadopago.client.order;
import lombok.Builder;
import lombok.Getter;
/**
* Request object containing supplementary information for an order. Provides extra context
* about the payer, shipment, platform, and travel details to improve fraud prevention
* and payment approval rates.
*/
@Getter
@Builder
public class AdditionalInfoRequest {
/** Additional payer details such as authentication type and registration date. */
private final PayerInfo payer;
/** Additional shipment details such as express shipping and local pickup flags. */
private final ShipmentInfo shipment;
/** Platform-level information including seller data and shipment tracking. */
private final PlatformInfo platform;
/** Travel-related information including passenger and route details. */
private final TravelInfo travel;
}
================================================
FILE: src/main/java/com/mercadopago/client/order/OrderAutomaticPaymentsRequest.java
================================================
package com.mercadopago.client.order;
import lombok.Builder;
import lombok.Getter;
// API version: 1ff4822a-2dfd-4393-800e-a562edb3fe32
/**
* Request object for configuring automatic recurring payments within an order. Defines the
* payment profile, retry policy, and scheduling dates for automated charge processing.
*/
@Getter
@Builder
public class OrderAutomaticPaymentsRequest {
/** Identifier of the payment profile used for automatic charges. */
private String paymentProfileId;
/** Number of retry attempts if the automatic payment fails. */
private Integer retries;
/** Scheduled date for the automatic payment, in ISO 8601 format. */
private String scheduleDate;
/** Due date for the payment, in ISO 8601 format. */
private String dueDate;
}
================================================
FILE: src/main/java/com/mercadopago/client/order/OrderClient.java
================================================
package com.mercadopago.client.order;
import static com.mercadopago.MercadoPagoConfig.getStreamHandler;
import static com.mercadopago.serialization.Serializer.deserializeFromJson;
import com.google.gson.JsonObject;
import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.MercadoPagoClient;
import com.mercadopago.core.MPRequestOptions;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;
import com.mercadopago.net.HttpMethod;
import com.mercadopago.net.MPHttpClient;
import com.mercadopago.net.MPRequest;
import com.mercadopago.net.MPResponse;
import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.resources.order.Order;
import com.mercadopago.resources.order.OrderSearchResponse;
import com.mercadopago.resources.order.OrderTransaction;
import com.mercadopago.resources.order.UpdateOrderTransaction;
import com.mercadopago.serialization.Serializer;
import java.util.logging.Logger;
import java.util.logging.StreamHandler;
import org.apache.commons.lang3.StringUtils;
/**
* Client for the MercadoPago Orders API (v1).
*
* Provides the full order lifecycle: creation, retrieval, processing, cancellation, capture,
* and refund. Also supports transaction management (create, update, delete) and order search with
* pagination.
*
* Usage example:
* If {@code request} is {@code null}, a total refund is performed. Otherwise the refund
* amount and transaction details are taken from the provided {@link OrderRefundRequest}.
*
* @param orderId the unique identifier of the order to refund
* @param request the {@link OrderRefundRequest} containing refund details, or {@code null} for a
* total refund
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the refunded {@link Order} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @throws IllegalArgumentException if {@code orderId} is blank or {@code null}
*/
public Order refund(String orderId, OrderRefundRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending order refund request");
validateOrderID(orderId);
JsonObject payload = request != null ? Serializer.serializeToJson(request) : null;
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(URL_REFUND, orderId))
.method(HttpMethod.POST)
.payload(payload)
.build();
MPResponse response = send(mpRequest, requestOptions);
Order result = deserializeFromJson(Order.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Searches for orders matching the specified criteria.
*
* @param request the {@link MPSearchRequest} containing search filters and pagination parameters
* @return an {@link OrderSearchResponse} with the matching orders and pagination metadata
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public OrderSearchResponse search(MPSearchRequest request)
throws MPException, MPApiException {
return this.search(request, null);
}
/**
* Searches for orders matching the specified criteria with custom request options.
*
* @param request the {@link MPSearchRequest} containing search filters and pagination parameters
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return an {@link OrderSearchResponse} with the matching orders and pagination metadata
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public OrderSearchResponse search(MPSearchRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending order search request");
MPResponse response = search("/v1/orders", request, requestOptions);
OrderSearchResponse result =
deserializeFromJson(OrderSearchResponse.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Validates that the given order ID is not blank or {@code null}.
*
* @param id the order identifier to validate
* @throws IllegalArgumentException if {@code id} is blank or {@code null}
*/
void validateOrderID(String id) {
if (StringUtils.isBlank(id)) {
throw new IllegalArgumentException("Order id cannot be null or empty");
}
}
/**
* Validates that the given transaction ID is not blank or {@code null}.
*
* @param id the transaction identifier to validate
* @throws IllegalArgumentException if {@code id} is blank or {@code null}
*/
void validateTransactionID(String id) {
if (StringUtils.isBlank(id)) {
throw new IllegalArgumentException("Transaction id cannot be null or empty");
}
}
}
================================================
FILE: src/main/java/com/mercadopago/client/order/OrderConfigRequest.java
================================================
package com.mercadopago.client.order;
import lombok.Builder;
import lombok.Getter;
// API version: 1ff4822a-2dfd-4393-800e-a562edb3fe32
/**
* Request object for configuring an order's behavior. Groups payment method restrictions,
* online checkout settings (URLs, 3DS, differential pricing), and Point-of-Sale terminal options.
*/
@Getter
@Builder
public class OrderConfigRequest {
/** Payment method configuration including allowed types, installment limits, and defaults. */
private OrderPaymentMethodConfig paymentMethod;
/** Online checkout configuration with callback URLs and security settings. */
private OrderOnlineConfig online;
/** Point-of-Sale terminal configuration for in-person payments. */
private OrderPointConfig point;
}
================================================
FILE: src/main/java/com/mercadopago/client/order/OrderCreateRequest.java
================================================
package com.mercadopago.client.order;
import com.mercadopago.net.MPResource;
import lombok.Builder;
import lombok.Getter;
import java.util.List;
import java.util.Map;
// API version: acd67b14-97c4-4a4a-840d-0a018c09654f
/**
* Request object for creating a new order in the MercadoPago Orders API. Contains all the
* information needed to create an order, including payer details, transaction data, items,
* shipping, and configuration options.
*
* @see Orders API
*/
@Builder
@Getter
public class OrderCreateRequest extends MPResource {
/** Type of the order (e.g. "online", "point"). */
private String type;
/** External reference that can be synchronized with your own payment system. */
private String externalReference;
/** Transaction information associated with this order, including payments. */
private OrderTransactionRequest transactions;
/** Payer information for the order. */
private OrderPayerRequest payer;
/** Total amount of the order as a decimal string. */
private String totalAmount;
/** Capture mode for the payment (e.g. "automatic", "manual"). */
private String captureMode;
/** Processing mode that defines how the payment is processed (e.g. "aggregator", "gateway"). */
private String processingMode;
/** Short description of the order. */
private String description;
/** Origin of the payment, used in marketplace scenarios. */
private String marketplace;
/** Fee collected by a marketplace or MercadoPago application as a decimal string. */
private String marketplaceFee;
/** List of items included in the order. */
private List Supports the full payment lifecycle: creation, retrieval, cancellation, capture (full and
* partial amounts), and search with pagination. Refund operations are delegated to an internal
* {@link PaymentRefundClient} and exposed via convenience methods on this class.
*
* Usage example:
* Also initialises the internal {@link PaymentRefundClient} with the same HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public PaymentClient(MPHttpClient httpClient) {
super(httpClient);
refundClient = new PaymentRefundClient(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Retrieves a payment by its unique identifier.
*
* @param id the unique identifier of the payment
* @return the requested {@link Payment}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Payment get(Long id) throws MPException, MPApiException {
return this.get(id, null);
}
/**
* Retrieves a payment by its unique identifier with custom request options.
*
* @param id the unique identifier of the payment
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link Payment}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Payment get(Long id, MPRequestOptions requestOptions) throws MPException, MPApiException {
LOGGER.info("Sending get payment request");
MPResponse response =
send(String.format(URL_WITH_ID, id.toString()), HttpMethod.GET, null, null, requestOptions);
Payment result = deserializeFromJson(Payment.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Creates a new payment.
*
* @param request the {@link PaymentCreateRequest} with payment details (amount, payer, method,
* etc.)
* @return the created {@link Payment}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Payment create(PaymentCreateRequest request) throws MPException, MPApiException {
return this.create(request, null);
}
/**
* Creates a new payment with custom request options.
*
* @param request the {@link PaymentCreateRequest} with payment details (amount, payer, method,
* etc.)
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the created {@link Payment}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Payment create(PaymentCreateRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending create payment request");
MPRequest mpRequest =
MPRequest.builder()
.uri("/v1/payments")
.method(HttpMethod.POST)
.payload(Serializer.serializeToJson(request))
.build();
MPResponse response = send(mpRequest, requestOptions);
Payment result = deserializeFromJson(Payment.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Cancels a pending payment by setting its status to {@code cancelled}.
*
* @param id the unique identifier of the payment to cancel
* @return the cancelled {@link Payment} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Payment cancel(Long id) throws MPException, MPApiException {
return this.cancel(id, null);
}
/**
* Cancels a pending payment with custom request options.
*
* @param id the unique identifier of the payment to cancel
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the cancelled {@link Payment} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Payment cancel(Long id, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending cancel payment request");
PaymentCancelRequest payload = new PaymentCancelRequest();
MPResponse response =
send(
String.format(URL_WITH_ID, id.toString()),
HttpMethod.PUT,
Serializer.serializeToJson(payload),
new HashMap<>(),
requestOptions);
Payment result = deserializeFromJson(Payment.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Captures a previously authorized payment for its full amount.
*
* @param id the unique identifier of the payment to capture
* @return the captured {@link Payment} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Payment capture(Long id) throws MPException, MPApiException {
return this.capture(id, null, null);
}
/**
* Captures a previously authorized payment for its full amount with custom request options.
*
* @param id the unique identifier of the payment to capture
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the captured {@link Payment} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Payment capture(Long id, MPRequestOptions requestOptions)
throws MPException, MPApiException {
return this.capture(id, null, requestOptions);
}
/**
* Captures a previously authorized payment for the specified amount (partial capture).
*
* @param id the unique identifier of the payment to capture
* @param amount the amount to capture; if {@code null}, the full authorized amount is captured
* @return the captured {@link Payment} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Payment capture(Long id, BigDecimal amount) throws MPException, MPApiException {
return this.capture(id, amount, null);
}
/**
* Captures a previously authorized payment for the specified amount with custom request options.
*
* If {@code amount} is {@code null}, the full authorized amount is captured (full capture).
* Otherwise, a partial capture is performed for the given amount.
*
* @param id the unique identifier of the payment to capture
* @param amount the amount to capture, or {@code null} for the full authorized amount
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the captured {@link Payment} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Payment capture(Long id, BigDecimal amount, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending capture payment request");
PaymentCaptureRequest payload =
PaymentCaptureRequest.builder().transactionAmount(amount).build();
MPResponse response =
send(
String.format(URL_WITH_ID, id.toString()),
HttpMethod.PUT,
Serializer.serializeToJson(payload),
new HashMap<>(),
requestOptions);
Payment result = deserializeFromJson(Payment.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Searches for payments matching the specified criteria.
*
* @param request the {@link MPSearchRequest} containing search filters and pagination parameters
* @return an {@link MPResultsResourcesPage} of {@link Payment} with the matching results and
* pagination metadata
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public MPResultsResourcesPage Delegates to the internal {@link PaymentRefundClient}.
*
* @param paymentId the unique identifier of the payment to refund
* @return the {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public PaymentRefund refund(Long paymentId) throws MPException, MPApiException {
return this.refund(paymentId, null, null);
}
/**
* Creates a total refund for a payment with custom request options.
*
* Delegates to the internal {@link PaymentRefundClient}.
*
* @param paymentId the unique identifier of the payment to refund
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public PaymentRefund refund(Long paymentId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
return this.refund(paymentId, null, requestOptions);
}
/**
* Creates a partial refund for a payment, returning the specified amount to the payer.
*
* Delegates to the internal {@link PaymentRefundClient}.
*
* @param paymentId the unique identifier of the payment to refund
* @param amount the amount to refund; if {@code null}, a total refund is performed
* @return the {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public PaymentRefund refund(Long paymentId, BigDecimal amount)
throws MPException, MPApiException {
return this.refund(paymentId, amount, null);
}
/**
* Creates a total or partial refund for a payment with custom request options.
*
* If {@code amount} is {@code null}, a total refund is performed. Otherwise, the specified
* amount is refunded (partial refund). Delegates to the internal {@link PaymentRefundClient}.
*
* @param paymentId the unique identifier of the payment to refund
* @param amount the amount to refund, or {@code null} for a total refund
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public PaymentRefund refund(Long paymentId, BigDecimal amount, MPRequestOptions requestOptions)
throws MPException, MPApiException {
return refundClient.refund(paymentId, amount, requestOptions);
}
/**
* Retrieves a specific refund associated with a payment.
*
* Delegates to the internal {@link PaymentRefundClient}.
*
* @param paymentId the unique identifier of the payment
* @param refundId the unique identifier of the refund
* @return the {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public PaymentRefund getRefund(Long paymentId, Long refundId) throws MPException, MPApiException {
return this.getRefund(paymentId, refundId, null);
}
/**
* Retrieves a specific refund associated with a payment with custom request options.
*
* Delegates to the internal {@link PaymentRefundClient}.
*
* @param paymentId the unique identifier of the payment
* @param refundId the unique identifier of the refund
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public PaymentRefund getRefund(Long paymentId, Long refundId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
return refundClient.get(paymentId, refundId, requestOptions);
}
/**
* Lists all refunds associated with a payment.
*
* Delegates to the internal {@link PaymentRefundClient}.
*
* @param paymentId the unique identifier of the payment
* @return an {@link MPResourceList} of {@link PaymentRefund} for the given payment
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public MPResourceList Delegates to the internal {@link PaymentRefundClient}.
*
* @param paymentId the unique identifier of the payment
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return an {@link MPResourceList} of {@link PaymentRefund} for the given payment
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public MPResourceList Provides operations to create total or partial refunds for a payment, retrieve a specific
* refund by its identifier, and list all refunds associated with a payment.
*
* This client is typically used internally by {@link PaymentClient}, but can also be
* instantiated directly for standalone refund management.
*
* @see PaymentClient
* @see
* Payment Refunds API reference
*/
public class PaymentRefundClient extends MercadoPagoClient {
/** Class-level logger for refund operations. */
private static final Logger LOGGER = Logger.getLogger(PaymentRefundClient.class.getName());
/** URL template for refund endpoints scoped to a payment (e.g. {@code /v1/payments/{id}/refunds}). */
private static final String URL_WITH_PAYMENT_ID = "/v1/payments/%s/refunds";
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public PaymentRefundClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code PaymentRefundClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public PaymentRefundClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Creates a total refund for a payment, returning the full amount to the payer.
*
* @param paymentId the unique identifier of the payment to refund
* @return the created {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PaymentRefund refund(Long paymentId) throws MPException, MPApiException {
return this.refund(paymentId, null, null);
}
/**
* Creates a total refund for a payment with custom request options.
*
* @param paymentId the unique identifier of the payment to refund
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the created {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PaymentRefund refund(Long paymentId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
return this.refund(paymentId, null, requestOptions);
}
/**
* Creates a partial refund for a payment, returning the specified amount to the payer.
*
* @param paymentId the unique identifier of the payment to refund
* @param amount the amount to refund; if {@code null}, a total refund is performed
* @return the created {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PaymentRefund refund(Long paymentId, BigDecimal amount)
throws MPException, MPApiException {
return this.refund(paymentId, amount, null);
}
/**
* Creates a total or partial refund for a payment with custom request options.
*
* If {@code amount} is {@code null}, a total refund is performed. Otherwise, the specified
* amount is refunded (partial refund).
*
* @param paymentId the unique identifier of the payment to refund
* @param amount the amount to refund, or {@code null} for a total refund
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the created {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PaymentRefund refund(Long paymentId, BigDecimal amount, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending refund payment request");
PaymentRefundCreateRequest request =
PaymentRefundCreateRequest.builder().amount(amount).build();
MPResponse response =
send(
String.format(URL_WITH_PAYMENT_ID, paymentId),
HttpMethod.POST,
serializeToJson(request),
null,
requestOptions);
PaymentRefund result = deserializeFromJson(PaymentRefund.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Retrieves a specific refund by its identifier from a payment.
*
* @param paymentId the unique identifier of the payment
* @param refundId the unique identifier of the refund to retrieve
* @return the requested {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PaymentRefund get(Long paymentId, Long refundId) throws MPException, MPApiException {
return this.get(paymentId, refundId, null);
}
/**
* Retrieves a specific refund by its identifier from a payment with custom request options.
*
* @param paymentId the unique identifier of the payment
* @param refundId the unique identifier of the refund to retrieve
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link PaymentRefund} with refund details
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PaymentRefund get(Long paymentId, Long refundId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending get refund payment request");
MPResponse response =
send(
String.format("/v1/payments/%s/refunds/%s", paymentId, refundId),
HttpMethod.GET,
null,
null,
requestOptions);
PaymentRefund result = deserializeFromJson(PaymentRefund.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Lists all refunds associated with a payment.
*
* @param paymentId the unique identifier of the payment
* @return an {@link MPResourceList} of {@link PaymentRefund} for the given payment
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MPResourceList Retrieves the list of payment methods available for the country associated with the
* authenticated user's credentials (e.g., credit cards, debit cards, bank transfers, cash).
*
* Usage example:
* Provides operations for in-person payments via MercadoPago Point card readers, including
* creating, searching, cancelling, and tracking payment intents, as well as managing Point
* devices and their operating modes.
*
* Usage example:
* Provides operations to create, retrieve, update, and search preapprovals (subscriptions).
* A preapproval authorises recurring charges against a payer's payment method over a defined
* billing period.
*
* Usage example:
* Provides operations to create, retrieve, update, and search checkout preferences. A
* preference defines the payment experience for the buyer, including items, payment methods,
* redirect URLs, and expiration settings.
*
* Usage example:
* Retrieves information about the authenticated MercadoPago user, including country, site,
* and account details. This client is used internally by {@link
* com.mercadopago.client.oauth.OauthClient} to build country-specific authorization URLs.
*
* Usage example:
* Instances of this class allow callers to override global settings defined in
* {@link com.mercadopago.MercadoPagoConfig} on a request-by-request basis. Any field
* left at its default value ({@code null} for objects, {@code 0} for primitives) will
* fall back to the corresponding global configuration value at execution time.
*
* Use the Lombok-generated builder for fluent construction:
* PSE is Colombia's standard online bank-transfer payment method. The integrator initiates
* the transaction with {@code payment_method.id = "pse"} and {@code type = "bank_transfer"},
* and must specify the buyer's bank via {@code financial_institution}.
*
* Required PSE-specific fields:
* Most-used PSE bank codes (full catalog via MP API):
* Unlike {@link MPException}, which covers client-side failures (network errors,
* serialization issues), this exception specifically represents a successfully received
* API response that indicates a business or validation error. It carries the HTTP status
* code and the full {@link MPResponse} so callers can inspect headers, body, and status
* for error-handling logic.
*
* Usage example:
* This exception represents failures that occur on the client side before or after
* an API call, such as network errors, serialization failures, or invalid request
* construction. It is not used for API-level error responses (HTTP 4xx/5xx);
* those are represented by {@link MPApiException}.
*
* Concrete subclasses provide more specific error categories:
* The exception carries enough context to support structured logging without
* exposing internal details in the HTTP response. The {@link #getReason()}
* indicates why validation failed, while {@link #getRequestId()} and
* {@link #getTimestamp()} echo the inputs that were available at the point of
* failure (when applicable) to correlate against MercadoPago's notifications
* dashboard.
*/
@Getter
public class MPInvalidWebhookSignatureException extends MPException {
private static final long serialVersionUID = 1L;
private final SignatureFailureReason reason;
private final String requestId;
private final String timestamp;
/**
* Creates a new {@code MPInvalidWebhookSignatureException}.
*
* @param reason the specific failure mode that triggered the exception
* @param requestId the {@code x-request-id} header value, when available; may be {@code null}
* @param timestamp the {@code ts} value extracted from the signature header, when
* parsing reached that point; may be {@code null}
*/
public MPInvalidWebhookSignatureException(
SignatureFailureReason reason, String requestId, String timestamp) {
super("Invalid webhook signature: " + reason);
this.reason = reason;
this.requestId = requestId;
this.timestamp = timestamp;
}
}
================================================
FILE: src/main/java/com/mercadopago/exceptions/MPJsonParseException.java
================================================
package com.mercadopago.exceptions;
/**
* Exception thrown when JSON serialization or deserialization fails within the SDK.
*
* This exception is raised by {@link com.mercadopago.serialization.Serializer} when a
* JSON string cannot be parsed into the expected resource type, or when an object cannot
* be converted to its JSON representation. Common causes include malformed JSON, unexpected
* field types, or missing required properties.
*
* @see MPException
* @see com.mercadopago.serialization.Serializer
*/
public class MPJsonParseException extends MPException {
/**
* Constructs a new JSON parse exception with the specified detail message.
*
* @param message a human-readable description of the parsing error
*/
public MPJsonParseException(String message) {
super(message);
}
/**
* Constructs a new JSON parse exception with the specified detail message and underlying cause.
*
* @param message a human-readable description of the parsing error
* @param throwable the underlying throwable (e.g., a Gson or IO exception) that caused the failure
*/
public MPJsonParseException(String message, Throwable throwable) {
super(message, throwable);
}
}
================================================
FILE: src/main/java/com/mercadopago/exceptions/MPMalformedRequestException.java
================================================
package com.mercadopago.exceptions;
/**
* Exception thrown when an API request cannot be constructed due to invalid or
* incomplete input.
*
* This exception is raised before any network call is made, indicating that
* the request object is structurally invalid (e.g., missing required fields, malformed
* URLs, or encoding failures). It signals a programming error on the caller's side
* rather than an API-level or network-level failure.
*
* @see MPException
* @see MPApiException
*/
public class MPMalformedRequestException extends MPException {
/**
* Constructs a new malformed request exception with the specified detail message.
*
* @param message a human-readable description of the request construction error
*/
public MPMalformedRequestException(String message) {
super(message);
}
/**
* Constructs a new malformed request exception wrapping an underlying cause.
*
* @param cause the underlying throwable that prevented request construction
*/
public MPMalformedRequestException(Throwable cause) {
super(cause);
}
}
================================================
FILE: src/main/java/com/mercadopago/exceptions/SignatureFailureReason.java
================================================
package com.mercadopago.exceptions;
/**
* Enumerates the reasons why
* {@link com.mercadopago.webhook.WebhookSignatureValidator} may reject a
* MercadoPago webhook notification.
*
* Integrators are encouraged to log this value alongside the {@code x-request-id}
* for correlation against the MercadoPago notifications dashboard.
*/
public enum SignatureFailureReason {
/** The {@code x-signature} header was missing, empty, or whitespace. */
MISSING_SIGNATURE_HEADER,
/** The header did not match the expected {@code ts=...,vN=...} format. */
MALFORMED_SIGNATURE_HEADER,
/** The header parsed correctly but no {@code ts=} component was present. */
MISSING_TIMESTAMP,
/**
* No hash was found in the header for any of the supported versions. Typically
* indicates MercadoPago has migrated to a new signature version and the SDK
* needs to be upgraded.
*/
MISSING_HASH,
/**
* The computed HMAC did not match the value in the header. Most often caused by
* an incorrect secret signature or a forged request.
*/
SIGNATURE_MISMATCH,
/**
* The header timestamp fell outside the configured tolerance window against the
* current clock. May indicate clock drift on the integrator's server or a replay
* attack.
*/
TIMESTAMP_OUT_OF_TOLERANCE,
}
================================================
FILE: src/main/java/com/mercadopago/net/Headers.java
================================================
package com.mercadopago.net;
/**
* Defines standard HTTP header name constants used throughout the MercadoPago SDK.
*
* This class contains both standard HTTP headers (such as {@code Authorization} and
* {@code Content-Type}) and MercadoPago-specific custom headers (prefixed with {@code X-}) used
* for request identification, idempotency, and partner tracking.
*
* These constants are used by {@link MPRequest} and {@link MPDefaultHttpClient} when
* constructing and sending HTTP requests to the MercadoPago API.
*
* @see MPRequest
* @see MPDefaultHttpClient
*/
public class Headers {
/**
* Standard HTTP {@code Authorization} header, used to carry the OAuth access token
* (Bearer token) for authenticating requests against the MercadoPago API.
*/
public static final String AUTHORIZATION = "Authorization";
/**
* Standard HTTP {@code Content-Type} header, indicating the media type of the request body.
* Typically set to {@code application/json} for MercadoPago API requests.
*/
public static final String CONTENT_TYPE = "Content-Type";
/**
* Standard HTTP {@code Accept} header, indicating the media types the client is willing to
* receive in the response. Typically set to {@code application/json}.
*/
public static final String ACCEPT = "Accept";
/**
* Standard HTTP {@code User-Agent} header, identifying the client software originating the
* request. The SDK sets this to a value containing the SDK version and Java runtime information.
*/
public static final String USER_AGENT = "User-Agent";
/**
* MercadoPago custom header {@code X-Idempotency-Key}, used to ensure that POST requests are
* idempotent. Sending the same idempotency key on repeated requests prevents duplicate resource
* creation on the server side.
*
* @see MPRequest#createIdempotencyKey()
*/
public static final String IDEMPOTENCY_KEY = "X-Idempotency-Key";
/**
* MercadoPago custom header {@code X-Product-Id}, used internally to identify the SDK product.
* The value is set from {@link com.mercadopago.MercadoPagoConfig#PRODUCT_ID}.
*/
public static final String PRODUCT_ID = "X-Product-Id";
/**
* MercadoPago custom header {@code X-Tracking-Id}, used internally for request tracking and
* telemetry. Contains platform and SDK version metadata.
*
* @see com.mercadopago.MercadoPagoConfig#TRACKING_ID
*/
public static final String TRACKING_ID = "X-Tracking-Id";
/**
* MercadoPago custom header {@code X-Corporation-Id}, used to identify the corporation
* associated with the API request. Set via
* {@link com.mercadopago.MercadoPagoConfig#setCorporationId(String)}.
*/
public static final String CORPORATION_ID = "X-Corporation-Id";
/**
* MercadoPago custom header {@code X-Integrator-Id}, used to identify the integrator (partner)
* making the API request. Set via
* {@link com.mercadopago.MercadoPagoConfig#setIntegratorId(String)}.
*/
public static final String INTEGRATOR_ID = "X-Integrator-Id";
/**
* MercadoPago custom header {@code X-Platform-Id}, used to identify the e-commerce platform
* through which the API request originates. Set via
* {@link com.mercadopago.MercadoPagoConfig#setPlatformId(String)}.
*/
public static final String PLATFORM_ID = "X-Platform-Id";
}
================================================
FILE: src/main/java/com/mercadopago/net/HttpMethod.java
================================================
package com.mercadopago.net;
/**
* Enumerates the HTTP methods supported by the MercadoPago SDK for communicating with the
* MercadoPago API.
*
* Each constant corresponds to a standard HTTP verb. The SDK uses this enum in {@link MPRequest}
* to indicate which HTTP method should be used when sending a request through
* {@link MPHttpClient#send(MPRequest)}.
*
* @see MPRequest
* @see MPDefaultHttpClient
*/
public enum HttpMethod {
/** HTTP GET method, used to retrieve resources without side effects. */
GET,
/** HTTP POST method, used to create new resources. */
POST,
/** HTTP PUT method, used to fully replace an existing resource. */
PUT,
/** HTTP PATCH method, used to partially update an existing resource. */
PATCH,
/** HTTP DELETE method, used to remove an existing resource. */
DELETE
}
================================================
FILE: src/main/java/com/mercadopago/net/HttpStatus.java
================================================
package com.mercadopago.net;
/**
* Defines commonly used HTTP status code constants for the MercadoPago SDK.
*
* These constants are used internally by {@link MPDefaultHttpClient} to evaluate API responses
* and to map low-level HTTP exceptions (such as protocol or SSL errors) to appropriate status
* codes.
*
* @see MPDefaultHttpClient
* @see MPResponse
*/
public class HttpStatus {
/**
* HTTP 200 OK. Indicates that the request has succeeded and the response body contains the
* requested resource.
*/
public static final int OK = 200;
/**
* HTTP 201 Created. Indicates that a new resource has been successfully created as a result of
* the request (typically returned for POST operations).
*/
public static final int CREATED = 201;
/**
* HTTP 204 No Content. Indicates that the request has succeeded but the response body is empty
* (typically returned for DELETE or update operations that produce no content).
*/
public static final int NO_CONTENT = 204;
/**
* HTTP 400 Bad Request. Indicates that the server could not understand the request due to
* invalid syntax or malformed parameters. Also used internally when a
* {@link org.apache.http.client.ClientProtocolException} occurs.
*/
public static final int BAD_REQUEST = 400;
/**
* HTTP 403 Forbidden. Indicates that the server understood the request but refuses to
* authorize it. Also used internally when an
* {@link javax.net.ssl.SSLPeerUnverifiedException} occurs during TLS verification.
*/
public static final int FORBIDDEN = 403;
/**
* HTTP 500 Internal Server Error. Indicates an unexpected condition on the server side. Also
* used internally when a generic {@link java.io.IOException} occurs during request execution.
*/
public static final int INTERNAL_SERVER_ERROR = 500;
}
================================================
FILE: src/main/java/com/mercadopago/net/KeepAliveStrategy.java
================================================
package com.mercadopago.net;
import org.apache.http.HeaderElement;
import org.apache.http.HeaderElementIterator;
import org.apache.http.HttpResponse;
import org.apache.http.conn.ConnectionKeepAliveStrategy;
import org.apache.http.message.BasicHeaderElementIterator;
import org.apache.http.protocol.HTTP;
import org.apache.http.protocol.HttpContext;
/**
* Custom connection keep-alive strategy for the MercadoPago SDK's HTTP client.
*
* Implements Apache HttpClient's {@link ConnectionKeepAliveStrategy} to determine how long
* idle connections should be kept alive in the connection pool. The strategy works as follows:
* Inspects the {@code Keep-Alive} response header for a {@code timeout} parameter. If
* found, the value (in seconds) is converted to milliseconds. Otherwise, the default timeout
* of {@value #DEFAULT_KEEP_ALIVE_TIMEOUT_MS} ms is returned.
*
* @param response the HTTP response from which the {@code Keep-Alive} header is read
* @param context the HTTP execution context (unused by this implementation)
* @return the keep-alive duration in milliseconds
*/
@Override
public long getKeepAliveDuration(HttpResponse response, HttpContext context) {
HeaderElementIterator it =
new BasicHeaderElementIterator(response.headerIterator(HTTP.CONN_KEEP_ALIVE));
while (it.hasNext()) {
HeaderElement he = it.nextElement();
String param = he.getName();
String value = he.getValue();
if (value != null && param.equalsIgnoreCase(KEEP_ALIVE_TIMEOUT_PARAM_NAME)) {
return Long.parseLong(value) * 1000;
}
}
return DEFAULT_KEEP_ALIVE_TIMEOUT_MS;
}
}
================================================
FILE: src/main/java/com/mercadopago/net/MPDefaultHttpClient.java
================================================
package com.mercadopago.net;
import static com.mercadopago.MercadoPagoConfig.getStreamHandler;
import static com.mercadopago.net.HttpStatus.BAD_REQUEST;
import static com.mercadopago.net.HttpStatus.FORBIDDEN;
import static com.mercadopago.net.HttpStatus.INTERNAL_SERVER_ERROR;
import com.google.gson.JsonObject;
import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;
import com.mercadopago.exceptions.MPMalformedRequestException;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.logging.Logger;
import java.util.logging.StreamHandler;
import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLPeerUnverifiedException;
import org.apache.commons.lang3.StringUtils;
import org.apache.http.Header;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.config.RequestConfig;
import org.apache.http.client.methods.HttpDelete;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPatch;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.client.methods.HttpRequestBase;
import org.apache.http.client.protocol.HttpClientContext;
import org.apache.http.config.Registry;
import org.apache.http.config.RegistryBuilder;
import org.apache.http.conn.socket.ConnectionSocketFactory;
import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.DefaultHttpRequestRetryHandler;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
import org.apache.http.message.BasicHeader;
import org.apache.http.message.BasicHttpResponse;
import org.apache.http.message.BasicStatusLine;
import org.apache.http.ssl.SSLContexts;
import org.apache.http.util.EntityUtils;
/**
* Default {@link MPHttpClient} implementation backed by Apache HttpClient 4.x.
*
* This client is configured with the following defaults:
* Cookies and automatic redirects are disabled.
*
* @see MPHttpClient
* @see KeepAliveStrategy
* @see MercadoPagoConfig
*/
public class MPDefaultHttpClient implements MPHttpClient {
/**
* Interval in milliseconds after which idle connections are validated before reuse.
* Value: {@value} ms.
*/
private static final int VALIDATE_INACTIVITY_INTERVAL_MS = 30000;
/**
* Default number of automatic retries for failed HTTP requests.
* Value: {@value}.
*/
private static final int DEFAULT_RETRIES = 3;
/** Character encoding used for request and response bodies. */
private static final String UTF_8 = "UTF-8";
/** Error message returned when a payload is attached to a GET or DELETE request. */
private static final String PAYLOAD_NOT_SUPPORTED_MESSAGE =
"Payload not supported for this method.";
/** Log format pattern for HTTP header key-value pairs. */
private static final String HEADER_LOG_FORMAT = "%s: %s%s";
/** Logger instance for this class. */
private static final Logger LOGGER = Logger.getLogger(MPDefaultHttpClient.class.getName());
/** The underlying Apache {@link HttpClient} used to execute HTTP requests. */
private final HttpClient httpClient;
/**
* Constructs a new {@code MPDefaultHttpClient} with default settings.
*
* Internally creates an Apache {@link HttpClient} configured with TLS 1.2, connection
* pooling, keep-alive strategy, retry handling, and optional proxy support as described in the
* class-level documentation.
*/
public MPDefaultHttpClient() {
this(null);
}
/**
* Constructs an {@code MPDefaultHttpClient} using the provided Apache {@link HttpClient}.
*
* This constructor is intended for testing purposes. If the given {@code httpClient} is
* {@code null}, a default client is created via {@link #createHttpClient()}.
*
* @param httpClient the Apache {@link HttpClient} to use, or {@code null} to create a default
* client
*/
protected MPDefaultHttpClient(HttpClient httpClient) {
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
if (Objects.isNull(httpClient)) {
this.httpClient = createHttpClient();
} else {
this.httpClient = httpClient;
}
}
private HttpClient createHttpClient() {
SSLContext sslContext = SSLContexts.createDefault();
SSLConnectionSocketFactory sslConnectionSocketFactory =
new SSLConnectionSocketFactory(
sslContext,
new String[] {"TLSv1.2"},
null,
SSLConnectionSocketFactory.getDefaultHostnameVerifier());
Registry Translates the given {@link MPRequest} into an Apache {@link HttpRequestBase}, executes it,
* and converts the raw response into an {@link MPResponse}. If the response status code is
* greater than 299, an {@link MPApiException} is thrown containing the full response details.
*
* Transport-level exceptions are mapped as follows:
* Some MercadoPago endpoints use this envelope instead of the
* {@link MPResultsResourcesPage} format. The {@link #total} field indicates the overall number
* of matching items, {@link #nextOffset} provides the offset for retrieving the next page, and
* {@link #elements} contains the deserialized resource objects for the current page.
*
* To fetch subsequent pages, create a new request with an offset equal to
* {@link #nextOffset} until all items have been retrieved.
*
* @param Implementations of this interface are responsible for the full HTTP lifecycle: building the
* underlying HTTP request from an {@link MPRequest}, executing it, and wrapping the raw response
* into an {@link MPResponse}.
*
* The default implementation is {@link MPDefaultHttpClient}. A custom implementation can be
* provided via {@link com.mercadopago.MercadoPagoConfig#setHttpClient(MPHttpClient)}.
*
* @see MPDefaultHttpClient
* @see MPRequest
* @see MPResponse
*/
public interface MPHttpClient {
/**
* Sends the given HTTP request to the MercadoPago API and returns the response.
*
* If the API responds with a status code greater than 299, the implementation should throw
* an {@link MPApiException} containing the full {@link MPResponse} for inspection.
*
* @param request the {@link MPRequest} describing the URI, HTTP method, headers, payload, and
* timeout configuration for the request
* @return an {@link MPResponse} containing the status code, response headers, and body content
* @throws MPException if a transport-level error occurs (e.g., I/O failure, connection
* timeout) preventing the request from completing
* @throws MPApiException if the API returns a non-success HTTP status code (greater than 299)
*/
MPResponse send(MPRequest request) throws MPException, MPApiException;
}
================================================
FILE: src/main/java/com/mercadopago/net/MPRequest.java
================================================
package com.mercadopago.net;
import com.google.gson.JsonObject;
import com.mercadopago.core.MPRequestOptions;
import java.util.Map;
import java.util.Objects;
import java.util.UUID;
import lombok.Builder;
import lombok.Getter;
/**
* Immutable value object representing an HTTP request to be sent to the MercadoPago API.
*
* Instances are created via the Lombok-generated builder or through the
* {@link #buildRequest(String, HttpMethod, JsonObject, Map, MPRequestOptions)} factory method,
* which merges per-request options (custom headers, access token, timeouts) from
* {@link MPRequestOptions} into the request.
*
* When a timeout value is {@code 0} (the default), the corresponding global timeout from
* {@link com.mercadopago.MercadoPagoConfig} is used at execution time.
*
* @see MPRequestOptions
* @see MPHttpClient#send(MPRequest)
* @see MPDefaultHttpClient
*/
@Getter
@Builder
public class MPRequest {
/** The fully-qualified URI (or relative path) for the API endpoint. */
private final String uri;
/** The HTTP method to use for this request. */
private final HttpMethod method;
/** Custom HTTP headers to include in this request, keyed by header name. */
private final Map When {@code requestOptions} is not {@code null}, its custom headers, access token, and
* timeout values are applied to the resulting request. When {@code requestOptions} is
* {@code null}, only the path, method, and payload are set.
*
* @param path the API endpoint path (relative or absolute URL)
* @param method the {@link HttpMethod} to use
* @param payload the JSON body for the request, or {@code null} if none
* @param queryParams a map of query parameter names to values, or {@code null} if none
* @param requestOptions per-request options including custom headers, access token, and
* timeouts; may be {@code null} for defaults
* @return a fully constructed {@link MPRequest} ready to be sent via
* {@link MPHttpClient#send(MPRequest)}
*/
public static MPRequest buildRequest(
String path,
HttpMethod method,
JsonObject payload,
Map The returned value is suitable for use as the {@link Headers#IDEMPOTENCY_KEY} header to
* ensure that a POST request can be safely retried without creating duplicate resources.
*
* @return a random UUID string to be used as an idempotency key
* @see Headers#IDEMPOTENCY_KEY
*/
public String createIdempotencyKey() {
return UUID.randomUUID().toString();
}
}
================================================
FILE: src/main/java/com/mercadopago/net/MPResource.java
================================================
package com.mercadopago.net;
import lombok.Data;
/**
* Base class for all MercadoPago API resource objects.
*
* Every domain model returned by the SDK (e.g., Payment, Preference, Customer) extends this
* class. It carries a reference to the raw {@link MPResponse} from which the resource was
* deserialized, allowing callers to access the original HTTP status code, response headers, and
* body content when needed.
*
* Subclasses are typically populated via Gson deserialization and have their {@code response}
* field set by the SDK's internal request pipeline.
*
* @see MPResponse
* @see MPResourceList
* @see MPResultsResourcesPage
* @see MPElementsResourcesPage
*/
@Data
public class MPResource {
/**
* The raw HTTP response from which this resource was deserialized. Provides access to the
* status code, headers, and body content of the original API response.
*/
private MPResponse response;
}
================================================
FILE: src/main/java/com/mercadopago/net/MPResourceList.java
================================================
package com.mercadopago.net;
import java.util.List;
import lombok.Getter;
import lombok.Setter;
/**
* Represents a list-style response from the MercadoPago API where the JSON body is a flat array
* of resources (i.e., not wrapped in a pagination envelope).
*
* Use this class for endpoints that return a simple JSON array such as
* {@code [{"id": 1, ...}, {"id": 2, ...}]}. For paginated responses that include metadata
* (total, limit, offset), use {@link MPResultsResourcesPage} or
* {@link MPElementsResourcesPage} instead.
*
* @param Instances are created by {@link MPDefaultHttpClient} after executing a request. The response
* carries the HTTP status code, all response headers (with multi-value support), and the raw
* response body as a string.
*
* This object is also attached to {@link MPResource} subclasses so that callers can inspect
* the underlying HTTP response metadata even after deserialization.
*
* @see MPHttpClient#send(MPRequest)
* @see MPResource#getResponse()
*/
@Getter
@AllArgsConstructor
public class MPResponse {
/**
* The HTTP status code of the response (e.g., 200, 201, 400).
*
* @see HttpStatus
*/
private final Integer statusCode;
/**
* A map of response header names to their values. Each header name may map to multiple values
* because HTTP allows repeated headers with the same name.
*/
private final Map Many MercadoPago search/list endpoints return results wrapped in this envelope. The
* {@link #paging} field carries pagination metadata (total count, limit, and offset), while the
* {@link #results} field contains the deserialized resource objects for the current page.
*
* For endpoints that use the alternative {@code {"total", "next_offset", "elements"}} structure,
* see {@link MPElementsResourcesPage}.
*
* @param Instances are created via the Lombok-generated builder:
* The {@link #getParameters()} method merges the pagination fields ({@code limit},
* {@code offset}) with any custom filters into a single map of query parameters. If a filter
* already defines a {@code limit} or {@code offset} key, the explicit filter value takes
* precedence over the dedicated fields.
*
* @see MPRequest
*/
@Getter
@Builder
public class MPSearchRequest {
/** Query parameter name used for the page size limit. */
private final String limitParam = "limit";
/** Query parameter name used for the page offset. */
private final String offsetParam = "offset";
/**
* Maximum number of results to return per page. Passed as the {@code limit} query parameter
* unless the {@link #filters} map already contains a {@code limit} key.
*/
private final Integer limit;
/**
* Zero-based offset indicating the starting position within the full result set. Passed as
* the {@code offset} query parameter unless the {@link #filters} map already contains an
* {@code offset} key.
*/
private final Integer offset;
/**
* Additional search filters to include as query parameters. Each entry's key is the parameter
* name and its value is the parameter value.
*/
private final Map If the filters already contain a key named {@code "limit"} or {@code "offset"}, the
* value from the filters map is preserved (i.e., it is not overwritten by the dedicated
* {@link #limit} or {@link #offset} fields).
*
* @return a new mutable {@link Map} containing all query parameters ready to be appended to
* the request URL
*/
public Map Handles two key responsibilities:
* If the path already starts with {@code "https"}, it is treated as an absolute URL and the
* base URL is not prepended. Query parameters are only appended if the resulting URL does not
* already contain a query string.
*
* @param path the API endpoint path (e.g., {@code "/v1/payments"}) or a fully-qualified
* URL
* @param queryParams a map of query parameter names to values to append, or {@code null} if
* no parameters are needed
* @return the fully-formatted URL string with base URL and encoded query parameters
* @throws MPException if the URL is malformed or if UTF-8 encoding is not supported
*/
public static String format(String path, Map Card tokens are generated by sending card data to the MercadoPago server, which returns a
* token that can be used to complete payment transactions without exposing sensitive card details.
* This resource is intended for testing purposes in sandbox environments.
*
* @see
* Card Token API Reference
*/
@Getter
@EqualsAndHashCode(callSuper = true)
public class CardToken extends MPResource {
/** Unique identifier of the card token. */
private String id;
/** Identifier of the associated card. */
private String cardId;
/** First six digits of the card number (BIN). */
private String firstSixDigits;
/** Expiration month of the card (1-12). */
private Integer expirationMonth;
/** Expiration year of the card (four-digit format). */
private Integer expirationYear;
/** Last four digits of the card number. */
private String lastFourDigits;
/** Information about the cardholder (name and identification). */
private CustomerCardCardholder cardholder;
/** Current status of the card token (e.g., active). */
private String status;
/** Date and time when the card token was created. */
private OffsetDateTime dateCreated;
/** Date and time when the card token was last updated. */
private OffsetDateTime dateLastUpdated;
/** Date and time when the card token expires. */
private OffsetDateTime dateDue;
/** Whether the Luhn algorithm validation is applied to the card number. */
private Boolean luhnValidation;
/** Whether the token was created in production (live) mode. */
private Boolean liveMode;
/** Whether the token requires ESC (Electronic Security Code). */
private Boolean requireEsc;
/** Total length of the card number. */
private Integer cardNumberLength;
/** Length of the card's security code (CVV). */
private Integer securityCodeLength;
}
================================================
FILE: src/main/java/com/mercadopago/resources/ResultsPaging.java
================================================
package com.mercadopago.resources;
import lombok.Getter;
/**
* Pagination metadata returned by MercadoPago API endpoints that use the
* {@code {"paging": {"total": N, "limit": M, "offset": O}, "results": [...]}} response envelope.
*
* This class is deserialized from the {@code paging} object within an
* {@link com.mercadopago.net.MPResultsResourcesPage} and provides the information needed to
* iterate through pages of results:
* Contains basic address information such as street name, street number, and zip code. This
* class is used as a shared component in resources like payments, preferences, and customers.
*
* @see MercadoPago API Reference
*/
@Getter
public class Address {
/** Street name of the address. */
private String streetName;
/** Street number of the address. */
private String streetNumber;
/** Postal zip code of the address. */
private String zipCode;
}
================================================
FILE: src/main/java/com/mercadopago/resources/common/Identification.java
================================================
package com.mercadopago.resources.common;
import lombok.Getter;
/**
* Represents an identification document used across the MercadoPago API.
*
* This base type holds document data such as type (e.g., CPF, DNI, CNPJ) and document number.
* It is commonly used in payer, customer, and cardholder contexts to identify individuals.
*
* @see MercadoPago API Reference
*/
@Getter
public class Identification {
/** Type of identification document (e.g., CPF, DNI, CNPJ). */
private String type;
/** Unique number of the identification document. */
private String number;
}
================================================
FILE: src/main/java/com/mercadopago/resources/common/Phone.java
================================================
package com.mercadopago.resources.common;
import lombok.Getter;
/**
* Represents a phone number used across the MercadoPago API.
*
* Holds the area code and the phone number, typically associated with payers, customers, or
* other contact information within the MercadoPago ecosystem.
*
* @see MercadoPago API Reference
*/
@Getter
public class Phone {
/** Area code of the phone number (e.g., country or region prefix). */
private String areaCode;
/** Phone number without the area code. */
private String number;
}
================================================
FILE: src/main/java/com/mercadopago/resources/common/Source.java
================================================
package com.mercadopago.resources.common;
import lombok.Getter;
/**
* Represents the source or origin of an action in the MercadoPago API.
*
* Identifies the entity that initiated an operation, such as a refund or chargeback. It
* includes the source identifier, name, and type to trace the originating party.
*
* @see MercadoPago API Reference
*/
@Getter
public class Source {
/** Unique identifier of the source. */
public String id;
/** Name of the source entity. */
public String name;
/** Type of the source (e.g., collector, operator). */
public String type;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/Customer.java
================================================
package com.mercadopago.resources.customer;
import com.mercadopago.resources.common.Identification;
import com.mercadopago.resources.common.Phone;
import com.mercadopago.net.MPResource;
import java.time.OffsetDateTime;
import java.util.List;
import java.util.Map;
import lombok.Getter;
/**
* Represents a customer resource in the MercadoPago API.
*
* Stores customer data such as email, name, phone, identification, addresses, and saved cards
* to improve the shopping experience. When used with the Cards resource, customers can complete
* purchases faster without re-entering payment information.
*
* @see
* Customer API Reference
*/
@Getter
public class Customer extends MPResource {
/** Unique identifier of the customer. */
private String id;
/** Email address of the customer. */
private String email;
/** First name of the customer. */
private String firstName;
/** Last name of the customer. */
private String lastName;
/** Phone information of the customer. */
private Phone phone;
/** Identification document information of the customer. */
private Identification identification;
/** Identifier of the customer's default address. */
private String defaultAddress;
/** Default address details of the customer. */
private CustomerDefaultAddress address;
/** Date when the customer registered on the merchant's site. */
private OffsetDateTime dateRegistered;
/** Free-text description or notes about the customer. */
private String description;
/** Date and time when the customer record was created in MercadoPago. */
private OffsetDateTime dateCreated;
/** Date and time when the customer record was last updated. */
private OffsetDateTime dateLastUpdated;
/** Custom metadata as key-value pairs associated with the customer. */
private Map Contains full address information including street, apartment, floor, city, state, country,
* neighborhood, and municipality. A customer may have multiple addresses on file.
*
* @see Customer
* @see
* Customer API Reference
*/
@Getter
public class CustomerAddress {
/** Unique identifier of the address. */
private String id;
/** Contact phone number associated with this address. */
private String phone;
/** Descriptive name or label for this address (e.g., "Home", "Work"). */
private String name;
/** Floor number within the building. */
private String floor;
/** Apartment or unit number. */
private String apartment;
/** Street name of the address. */
private String streetName;
/** Street number of the address. */
private String streetNumber;
/** Postal or zip code of the address. */
private String zipCode;
/** City information of the address. */
private CustomerAddressCity city;
/** State or province information of the address. */
private CustomerAddressState state;
/** Country information of the address. */
private CustomerAddressCountry country;
/** Neighborhood information of the address. */
private CustomerAddressNeighborhood neighborhood;
/** Municipality information of the address. */
private CustomerAddressMunicipality municipality;
/** Additional comments or instructions about the address. */
private String comments;
/** Date and time when the address was created. */
private OffsetDateTime dateCreated;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerAddressCity.java
================================================
package com.mercadopago.resources.customer;
import lombok.Getter;
/**
* Represents city information within a customer's address in the MercadoPago API.
*
* Contains the city identifier and name as part of the geographic breakdown of a customer
* address.
*
* @see CustomerAddress
*/
@Getter
public class CustomerAddressCity {
/** Unique identifier of the city. */
private String id;
/** Name of the city. */
private String name;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerAddressCountry.java
================================================
package com.mercadopago.resources.customer;
import lombok.Getter;
/**
* Represents country information within a customer's address in the MercadoPago API.
*
* Contains the country identifier and name as part of the geographic breakdown of a customer
* address.
*
* @see CustomerAddress
*/
@Getter
public class CustomerAddressCountry {
/** Unique identifier of the country. */
private String id;
/** Name of the country. */
private String name;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerAddressMunicipality.java
================================================
package com.mercadopago.resources.customer;
import lombok.Getter;
/**
* Represents municipality information within a customer's address in the MercadoPago API.
*
* Contains the municipality identifier and name as part of the geographic breakdown of a
* customer address. Applicable in countries where municipalities are an administrative division.
*
* @see CustomerAddress
*/
@Getter
public class CustomerAddressMunicipality {
/** Unique identifier of the municipality. */
private String id;
/** Name of the municipality. */
private String name;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerAddressNeighborhood.java
================================================
package com.mercadopago.resources.customer;
import lombok.Getter;
/**
* Represents neighborhood information within a customer's address in the MercadoPago API.
*
* Contains the neighborhood identifier and name as part of the geographic breakdown of a
* customer address.
*
* @see CustomerAddress
*/
@Getter
public class CustomerAddressNeighborhood {
/** Unique identifier of the neighborhood. */
private String id;
/** Name of the neighborhood. */
private String name;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerAddressState.java
================================================
package com.mercadopago.resources.customer;
import lombok.Getter;
/**
* Represents state or province information within a customer's address in the MercadoPago API.
*
* Contains the state identifier and name as part of the geographic breakdown of a customer
* address.
*
* @see CustomerAddress
*/
@Getter
public class CustomerAddressState {
/** Unique identifier of the state or province. */
private String id;
/** Name of the state or province. */
private String name;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerCard.java
================================================
package com.mercadopago.resources.customer;
import com.mercadopago.net.MPResource;
import java.time.OffsetDateTime;
import lombok.EqualsAndHashCode;
import lombok.Getter;
/**
* Represents a saved card associated with a customer in the MercadoPago API.
*
* Contains card details such as expiration date, first/last digits, payment method, issuer,
* cardholder information, and security code metadata. Saved cards enable returning customers to
* complete payments without re-entering their card data.
*
* @see Customer
* @see
* Customer Cards API Reference
*/
@Getter
@EqualsAndHashCode(callSuper = true)
public class CustomerCard extends MPResource {
/** Unique identifier of the card. */
private String id;
/** Identifier of the customer who owns this card. */
private String customerId;
/** Expiration month of the card (1-12). */
private Integer expirationMonth;
/** Expiration year of the card (four-digit format). */
private Integer expirationYear;
/** First six digits of the card number (BIN). */
private String firstSixDigits;
/** Last four digits of the card number. */
private String lastFourDigits;
/** Payment method information associated with this card. */
private CustomerCardPaymentMethod paymentMethod;
/** Security code metadata of the card (length and location). */
private CustomerCardSecurityCode securityCode;
/** Issuer (financial institution) of the card. */
private CustomerCardIssuer issuer;
/** Cardholder information including name and identification. */
private CustomerCardCardholder cardholder;
/** Date and time when the card record was created. */
private OffsetDateTime dateCreated;
/** Date and time when the card record was last updated. */
private OffsetDateTime dateLastUpdated;
/** Identifier of the user associated with this card. */
private String userId;
/** Whether this card was saved in production (live) mode. */
private boolean liveMode;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerCardCardholder.java
================================================
package com.mercadopago.resources.customer;
import lombok.Getter;
/**
* Represents the cardholder information for a saved customer card in the MercadoPago API.
*
* Contains the cardholder's name and identification document, which are used to validate card
* ownership during payment processing.
*
* @see CustomerCard
*/
@Getter
public class CustomerCardCardholder {
/** Full name of the cardholder as printed on the card. */
private String name;
/** Identification document of the cardholder. */
private CustomerCardCardholderIdentification identification;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerCardCardholderIdentification.java
================================================
package com.mercadopago.resources.customer;
import com.mercadopago.resources.common.Identification;
import lombok.EqualsAndHashCode;
import lombok.Getter;
/**
* Represents the identification document of a cardholder in the MercadoPago API.
*
* Extends the common {@link Identification} class to provide document type and number for
* cardholder verification purposes. Inherits fields such as type (e.g., CPF, DNI) and number.
*
* @see Identification
* @see CustomerCardCardholder
*/
@Getter
@EqualsAndHashCode(callSuper = true)
public class CustomerCardCardholderIdentification extends Identification {}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerCardIssuer.java
================================================
package com.mercadopago.resources.customer;
import lombok.Builder;
import lombok.Getter;
/**
* Represents the issuer (financial institution) of a customer's saved card in the MercadoPago API.
*
* Contains the issuer identifier and name, which identify the bank or financial institution
* that issued the card.
*
* @see CustomerCard
*/
@Getter
@Builder
public class CustomerCardIssuer {
/** Unique identifier of the card issuer. */
private final String id;
/** Name of the card issuer (e.g., bank name). */
private final String name;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerCardPaymentMethod.java
================================================
package com.mercadopago.resources.customer;
import lombok.Getter;
/**
* Represents the payment method associated with a customer's saved card in the MercadoPago API.
*
* Contains details about the payment method type, name, and thumbnail images that correspond
* to the card brand (e.g., Visa, Mastercard).
*
* @see CustomerCard
*/
@Getter
public class CustomerCardPaymentMethod {
/** Unique identifier of the payment method. */
private String id;
/** Display name of the payment method (e.g., Visa, Mastercard). */
private String name;
/** Type identifier of the payment method (e.g., credit_card, debit_card). */
private String paymentTypeId;
/** URL of the payment method thumbnail image. */
private String thumbnail;
/** URL of the payment method thumbnail image served over HTTPS. */
private String secureThumbnail;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerCardSecurityCode.java
================================================
package com.mercadopago.resources.customer;
import lombok.Getter;
/**
* Represents security code (CVV) metadata for a customer's saved card in the MercadoPago API.
*
* Describes the expected length of the security code and its physical location on the card
* (e.g., front or back), used for validation and UI rendering purposes.
*
* @see CustomerCard
*/
@Getter
public class CustomerCardSecurityCode {
/** Expected length of the security code (e.g., 3 or 4 digits). */
private Integer length;
/** Physical location of the security code on the card (e.g., "back", "front"). */
private String cardLocation;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/CustomerDefaultAddress.java
================================================
package com.mercadopago.resources.customer;
import lombok.Getter;
/**
* Represents the default address of a customer in the MercadoPago API.
*
* Contains a simplified set of address fields (zip code, street name, and street number) used
* as the customer's primary address for shipping and billing purposes.
*
* @see Customer
*/
@Getter
public class CustomerDefaultAddress {
/** Unique identifier of the default address. */
private String id;
/** Postal or zip code of the address. */
private String zipCode;
/** Street name of the address. */
private String streetName;
/** Street number of the address. */
private Integer streetNumber;
}
================================================
FILE: src/main/java/com/mercadopago/resources/customer/Identification.java
================================================
package com.mercadopago.resources.customer;
import lombok.Getter;
/**
* Represents a customer's identification document in the MercadoPago API.
*
* Holds the document type (e.g., CPF, DNI, CNPJ) and the document number, used for identity
* verification in customer-related operations.
*
* @see Customer
*/
@Getter
public class Identification {
/** Type of identification document (e.g., CPF, DNI, CNPJ). */
private String type;
/** Number of the identification document. */
private String number;
}
================================================
FILE: src/main/java/com/mercadopago/resources/identificationtype/IdentificationType.java
================================================
package com.mercadopago.resources.identificationtype;
import com.mercadopago.net.MPResource;
import lombok.Getter;
/**
* Represents a type of identification document available in the MercadoPago API.
*
* Describes the accepted identification document types for a given country (e.g., CPF, DNI,
* CNPJ), including validation constraints such as minimum and maximum character lengths.
*
* @see
* Identification Types API Reference
*/
@Getter
public class IdentificationType extends MPResource {
/** Unique identifier of the identification type. */
private String id;
/** Display name of the identification type (e.g., CPF, DNI). */
private String name;
/** Data type of the identification number (e.g., "number", "string"). */
private String type;
/** Minimum allowed length for the identification number. */
private Integer minLength;
/** Maximum allowed length for the identification number. */
private Integer maxLength;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrder.java
================================================
package com.mercadopago.resources.merchantorder;
import com.mercadopago.net.MPResource;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.util.List;
import lombok.Getter;
/**
* Represents a merchant order resource in the MercadoPago API.
*
* A merchant order groups one or more payments, items, and shipments into a single commercial
* transaction. It tracks the overall status, amounts, and logistics of an order placed through
* MercadoPago payment preferences.
*
* @see
* Merchant Order API Reference
*/
@Getter
public class MerchantOrder extends MPResource {
/** Unique identifier of the merchant order. */
private Long id;
/** Payment preference identifier associated with this merchant order. */
private String preferenceId;
/** Application identifier that created the order. */
private String applicationId;
/** Current status of the merchant order (e.g., opened, closed). */
private String status;
/** Country site identifier where the merchant order was created (e.g., MLA, MLB). */
private String siteId;
/** Payer (buyer) information for this order. */
private MerchantOrderPayer payer;
/** Collector (seller) information for this order. */
private MerchantOrderCollector collector;
/** Identifier of the sponsor associated with the order. */
private String sponsorId;
/** List of payments associated with this merchant order. */
private List Contains the seller's identifier and nickname, identifying the merchant who will receive
* the payment for the order.
*
* @see MerchantOrder
*/
@Getter
public class MerchantOrderCollector {
/** Unique identifier of the collector (seller). */
private Long id;
/** Display nickname of the collector (seller). */
private String nickname;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrderItem.java
================================================
package com.mercadopago.resources.merchantorder;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Represents an item within a merchant order in the MercadoPago API.
*
* Contains product information such as title, description, image, category, quantity, and
* unit price. A merchant order may contain one or more items.
*
* @see MerchantOrder
*/
@Getter
public class MerchantOrderItem {
/** Unique identifier (code) of the item. */
private String id;
/** Title or name of the item. */
private String title;
/** Detailed description of the item. */
private String description;
/** URL of the item's image. */
private String pictureUrl;
/** Category identifier for the item. */
private String categoryId;
/** Quantity of this item in the order. */
private int quantity;
/** Unit price of the item. */
private BigDecimal unitPrice;
/** Currency identifier in ISO 4217 format (e.g., BRL, ARS, USD). */
private String currencyId;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrderPayer.java
================================================
package com.mercadopago.resources.merchantorder;
import lombok.Getter;
/**
* Represents the payer (buyer) of a merchant order in the MercadoPago API.
*
* Contains the buyer's identifier and nickname, identifying the customer who placed the order.
*
* @see MerchantOrder
*/
@Getter
public class MerchantOrderPayer {
/** Unique identifier of the payer (buyer). */
private Long id;
/** Display nickname of the payer (buyer). */
private String nickname;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrderPayment.java
================================================
package com.mercadopago.resources.merchantorder;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import lombok.Getter;
/**
* Represents a payment associated with a merchant order in the MercadoPago API.
*
* Contains payment details such as transaction amount, status, currency, approval date, and
* refund information. A merchant order may have multiple payments.
*
* @see MerchantOrder
*/
@Getter
public class MerchantOrderPayment {
/** Unique identifier of the payment. */
private Long id;
/** Transaction amount (product cost) of the payment. */
private BigDecimal transactionAmount;
/** Total amount paid including shipping and other charges. */
private BigDecimal totalPaidAmount;
/** Shipping cost included in the payment. */
private BigDecimal shippingCost;
/** Currency identifier in ISO 4217 format (e.g., BRL, ARS, USD). */
private String currencyId;
/** Current status of the payment (e.g., approved, pending, rejected). */
private String status;
/** Detailed information about the payment status or rejection cause. */
private String statusDetails;
/** Type of operation (e.g., regular_payment, money_transfer). */
private String operationType;
/** Date and time when the payment was approved. */
private OffsetDateTime dateApproved;
/** Date and time when the payment was created. */
private OffsetDateTime dateCreated;
/** Date and time when the payment was last modified. */
private OffsetDateTime lastModified;
/** Total amount refunded from this payment. */
private BigDecimal amountRefunded;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrderReceiverAddress.java
================================================
package com.mercadopago.resources.merchantorder;
import lombok.Getter;
/**
* Represents the receiver's shipping address for a merchant order in the MercadoPago API.
*
* Contains the full destination address for shipment delivery, including street details,
* apartment, floor, geographic coordinates, and hierarchical geographic data (city, state,
* country).
*
* @see MerchantOrderShipment
*/
@Getter
public class MerchantOrderReceiverAddress {
/** Unique identifier of the receiver address. */
private Long id;
/** Full address line (street name and number combined). */
private String addressLine;
/** Apartment or unit number. */
private String apartment;
/** City information of the receiver address. */
private MerchantOrderReceiverAddressCity city;
/** State or province information of the receiver address. */
private MerchantOrderReceiverAddressState state;
/** Country information of the receiver address. */
private MerchantOrderReceiverAddressCountry country;
/** Additional comments or delivery instructions. */
private String comment;
/** Contact name or information for the receiver. */
private String contact;
/** Postal or zip code of the receiver address. */
private String zipCode;
/** Street name of the receiver address. */
private String streetName;
/** Street number of the receiver address. */
private String streetNumber;
/** Floor number within the building. */
private String floor;
/** Contact phone number at the receiver address. */
private String phone;
/** Geographic latitude coordinate of the address. */
private String latitude;
/** Geographic longitude coordinate of the address. */
private String longitude;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrderReceiverAddressCity.java
================================================
package com.mercadopago.resources.merchantorder;
import lombok.Getter;
/**
* Represents city information within a merchant order receiver address in the MercadoPago API.
*
* Contains the city identifier and name as part of the shipping destination address.
*
* @see MerchantOrderReceiverAddress
*/
@Getter
public class MerchantOrderReceiverAddressCity {
/** Unique identifier of the city. */
private String id;
/** Name of the city. */
private String name;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrderReceiverAddressCountry.java
================================================
package com.mercadopago.resources.merchantorder;
import lombok.Getter;
/**
* Represents country information within a merchant order receiver address in the MercadoPago API.
*
* Contains the country identifier and name as part of the shipping destination address.
*
* @see MerchantOrderReceiverAddress
*/
@Getter
public class MerchantOrderReceiverAddressCountry {
/** Unique identifier of the country. */
private String id;
/** Name of the country. */
private String name;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrderReceiverAddressState.java
================================================
package com.mercadopago.resources.merchantorder;
import lombok.Getter;
/**
* Represents state or province information within a merchant order receiver address in the
* MercadoPago API.
*
* Contains the state identifier and name as part of the shipping destination address.
*
* @see MerchantOrderReceiverAddress
*/
@Getter
public class MerchantOrderReceiverAddressState {
/** Unique identifier of the state or province. */
private String id;
/** Name of the state or province. */
private String name;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrderShipment.java
================================================
package com.mercadopago.resources.merchantorder;
import java.time.OffsetDateTime;
import java.util.List;
import java.util.Map;
import lombok.Getter;
/**
* Represents a shipment associated with a merchant order in the MercadoPago API.
*
* Contains shipping logistics information including type, mode, status, items being shipped,
* sender/receiver details, delivery address, and selected shipping option.
*
* @see MerchantOrder
*/
@Getter
public class MerchantOrderShipment {
/** Unique identifier of the shipment. */
private Long id;
/** Type of shipping (e.g., custom, mercadoenvios). */
private String shippingType;
/** Shipping mode (e.g., me1, me2, not_specified). */
private String shippingMode;
/** Picking type for the shipment (e.g., fulfillment, cross_docking). */
private String pickingType;
/** Current status of the shipment (e.g., pending, shipped, delivered). */
private String status;
/** Sub-status providing additional detail about the shipment status. */
private String shippingSubstatus;
/** List of items included in this shipment as key-value maps. */
private List Provides the estimated delivery date and a time window (from/to) within which the shipment
* is expected to arrive.
*
* @see MerchantOrderShippingOption
*/
@Getter
public class MerchantOrderShippingEstimatedDelivery {
/** Estimated date of delivery. */
private OffsetDateTime date;
/** Start of the estimated delivery time window. */
private String timeFrom;
/** End of the estimated delivery time window. */
private String timeTo;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrderShippingOption.java
================================================
package com.mercadopago.resources.merchantorder;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Represents a shipping option available for a merchant order shipment in the MercadoPago API.
*
* Contains cost, currency, estimated delivery, shipping method, and speed information for a
* specific shipping option that can be selected for order fulfillment.
*
* @see MerchantOrderShipment
*/
@Getter
public class MerchantOrderShippingOption {
/** Unique identifier of the shipping option. */
private Long id;
/** Net cost absorbed by the receiver (buyer). */
private BigDecimal cost;
/** Currency identifier in ISO 4217 format (e.g., BRL, ARS, USD). */
private String currencyId;
/** Estimated delivery date and time window. */
private MerchantOrderShippingEstimatedDelivery estimatedDelivery;
/** Listed (original) cost of the shipping before discounts. */
private BigDecimal listCost;
/** Display name of the shipping option. */
private String name;
/** Identifier of the shipping method. */
private Long shippingMethodId;
/** Speed details including handling and shipping times. */
private MerchantOrderShippingSpeed speed;
}
================================================
FILE: src/main/java/com/mercadopago/resources/merchantorder/MerchantOrderShippingSpeed.java
================================================
package com.mercadopago.resources.merchantorder;
import lombok.Getter;
/**
* Represents shipping speed details for a shipping option in the MercadoPago API.
*
* Contains the handling time (preparation before dispatch) and shipping time (transit duration)
* in hours, used to calculate total estimated delivery time.
*
* @see MerchantOrderShippingOption
*/
@Getter
public class MerchantOrderShippingSpeed {
/** Handling time in hours before the package is dispatched. */
private Long handling;
/** Transit time in hours from dispatch to delivery. */
private Long shipping;
}
================================================
FILE: src/main/java/com/mercadopago/resources/oauth/CreateOauthCredential.java
================================================
package com.mercadopago.resources.oauth;
import lombok.EqualsAndHashCode;
import lombok.Getter;
/**
* Resource representing the credential returned when creating a new OAuth authorization.
* Extends {@link OauthCredential} with additional fields that indicate the public key
* associated with the application and whether the credential operates in live (production) mode.
*
* @see OauthCredential
*/
@Getter
@EqualsAndHashCode(callSuper = true)
public class CreateOauthCredential extends OauthCredential {
/** Public key associated with the MercadoPago application for this credential. */
private String publicKey;
/** Whether this credential is configured for live (production) mode rather than sandbox. */
private boolean liveMode;
}
================================================
FILE: src/main/java/com/mercadopago/resources/oauth/OauthCredential.java
================================================
package com.mercadopago.resources.oauth;
import com.mercadopago.net.MPResource;
import lombok.Getter;
/**
* Base resource representing credential information obtained from an OAuth authorization flow.
* Contains the access token, its type and expiration, the granted scope, and a refresh token
* that can be used to renew the credential without repeating the authorization process.
*
* @see OAuth API reference
*/
@Getter
public class OauthCredential extends MPResource {
/** OAuth access token used to authenticate API requests on behalf of the user. */
private String accessToken;
/** Token type indicating the authentication scheme, typically "Bearer". */
private String tokenType;
/** Number of seconds until the access token expires. */
private Long expiresIn;
/** OAuth scope that defines the permissions granted by this credential. */
private String scope;
/** Refresh token used to obtain a new access token when the current one expires. */
private String refreshToken;
}
================================================
FILE: src/main/java/com/mercadopago/resources/oauth/RefreshOauthCredential.java
================================================
package com.mercadopago.resources.oauth;
import lombok.EqualsAndHashCode;
import lombok.Getter;
/**
* Resource representing the credential returned when refreshing an existing OAuth token.
* Inherits all fields from {@link OauthCredential} including the new access token,
* its expiration, scope, and a potentially rotated refresh token.
*
* @see OauthCredential
*/
@Getter
@EqualsAndHashCode(callSuper = true)
public class RefreshOauthCredential extends OauthCredential {}
================================================
FILE: src/main/java/com/mercadopago/resources/order/Order.java
================================================
package com.mercadopago.resources.order;
import com.mercadopago.net.MPResource;
import lombok.Getter;
import java.util.List;
import java.util.Map;
/* API version: acd67b14-97c4-4a4a-840d-0a018c09654f */
/**
* Resource representing a MercadoPago Order.
* An Order is the top-level entity that groups one or more payment transactions, line items,
* payer information, and configuration options for online or point-of-sale checkout flows.
*
* @see Order API reference
*/
@Getter
public class Order extends MPResource {
/** Unique identifier of the order. */
private String id;
/** Type of the order (e.g., "online", "point"). */
private String type;
/** External reference used to correlate this order with an identifier in the integrator's system. */
private String externalReference;
/** Total amount of the order expressed as a decimal string. */
private String totalAmount;
/** Total amount already paid on this order expressed as a decimal string. */
private String totalPaidAmount;
/** Country code of the site to which the MercadoPago application that created the order belongs. */
private String countryCode;
/** Identifier of the user (seller) who will receive the payment for this order. */
private String userId;
/** Current status of the order (e.g., "created", "processed", "expired"). */
private String status;
/** Detailed sub-status providing additional context about the current order status. */
private String statusDetail;
/** Capture mode for the order's payments (e.g., "automatic", "manual"). */
private String captureMode;
/** ISO 8601 date-time when the order was created. */
private String createdDate;
/** ISO 8601 date-time when the order was last updated. */
private String lastUpdatedDate;
/** Integration data containing identifiers for correlating the order with external systems. */
private OrderIntegrationData integrationData;
/** Processing mode that controls how payments are executed (e.g., "aggregator", "gateway"). */
private String processingMode;
/** Free-text description of the order visible to the payer. */
private String description;
/** Marketplace identifier indicating the origin of the order. */
private String marketplace;
/** Fee collected by the marketplace or MercadoPago application, expressed as a decimal string. */
private String marketplaceFee;
/** Transaction details including payments, refunds, and chargebacks associated with this order. */
private OrderTransaction transactions;
/** ISO 8601 date-time from which the checkout becomes available for the payer. */
private String checkoutAvailableAt;
/** ISO 8601 date-time when the order expires if not completed. */
private String expirationTime;
/** Unique client token that identifies the integrator's credentials for this order. */
private String clientToken;
/** List of line items included in this order. */
private List This is the core resource of the Payments API. It contains all information related to a
* payment transaction, including the payer, the amount, the payment method, status, fees,
* refunds, and metadata. Payments can be created, searched, captured, cancelled, and refunded
* through the {@link com.mercadopago.client.payment.PaymentClient}.
*
* @see Payments API reference
*/
@Getter
@EqualsAndHashCode(callSuper = true)
public class Payment extends MPResource {
/** Unique payment identifier assigned by MercadoPago. */
private Long id;
/** Date and time when the payment was created. */
private OffsetDateTime dateCreated;
/** Date and time when the payment was approved. */
private OffsetDateTime dateApproved;
/** Date and time of the last status change. */
private OffsetDateTime dateLastUpdated;
/** Expiration date for the payment, after which it can no longer be approved. */
private OffsetDateTime dateOfExpiration;
/** Date and time when the funds become available to the collector. */
private OffsetDateTime moneyReleaseDate;
/** Schema that defines how and when the funds are released to the collector. */
private String moneyReleaseSchema;
/** Type of operation, such as regular_payment, money_transfer, or recurring_payment. */
private String operationType;
/** Identifier of the issuer of the payment method (e.g. a specific bank). */
private String issuerId;
/** Identifier of the payment method chosen to process the payment (e.g. visa, master, pix). */
private String paymentMethodId;
/** Type of the payment method (e.g. credit_card, debit_card, ticket, bank_transfer). */
private String paymentTypeId;
/** Current status of the payment (e.g. approved, pending, rejected, cancelled). */
private String status;
/** Detailed explanation of the current payment status or rejection cause. */
private String statusDetail;
/** Currency identifier using ISO 4217 code (e.g. BRL, ARS, MXN). */
private String currencyId;
/** Short description of the payment reason, typically the item or service title. */
private String description;
/** Whether the payment was created in production mode ({@code true}) or sandbox mode ({@code false}). */
private boolean liveMode;
/** Identifier of the sponsor that originated the payment through the MercadoPago platform. */
private Long sponsorId;
/** Authorization code returned by the card issuer. */
private String authorizationCode;
/** Identifier of the integrator who processes the payment through the platform. */
private String integratorId;
/** Identifier of the platform that originated the payment. */
private String platformId;
/** Identifier of the corporation associated with the payment. */
private String corporationId;
/** Identifier of the collector (seller) who receives the payment. */
private Long collectorId;
/** Information about the payer who is making the payment. */
private PaymentPayer payer;
/**
* Custom key-value metadata attached to the payment to record additional merchant-defined
* attributes.
*/
private Map Provides supplementary data that can improve fraud analysis and increase conversion rates.
* Includes item details, extended payer information, shipping data, and the origin IP address.
* Sending as much information as possible is recommended.
*
* @see Payment#getAdditionalInfo()
*/
@Getter
public class PaymentAdditionalInfo {
/** IP address from which the payment request originated (required for bank transfer payments). */
private String ipAddress;
/** List of items being purchased in this payment. */
private List Provides the payer's name, phone, address, and registration date on the merchant's platform.
* This data supplements the primary {@link PaymentPayer} and helps improve fraud detection.
*
* @see PaymentAdditionalInfo#getPayer()
*/
@Getter
public class PaymentAdditionalInfoPayer {
/** First name of the payer as registered on the merchant's platform. */
private String firstName;
/** Last name of the payer as registered on the merchant's platform. */
private String lastName;
/** Phone contact information of the payer. */
private PaymentPhone phone;
/** Residential or billing address of the payer. */
private Address address;
/** Date and time when the payer registered on the merchant's site. */
private OffsetDateTime registrationDate;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentAmounts.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that holds the amount breakdown for both the payer and collector in a MercadoPago payment.
*
* Provides currency-specific transaction and net amounts from the perspective of each party
* involved in the payment, useful for cross-currency and marketplace scenarios.
*
* @see Payment#getAmounts()
*/
@Getter
public class PaymentAmounts {
/** Amount details from the payer's perspective, including total paid and currency. */
private PaymentUsersAmountPayer payer;
/** Amount details from the collector's perspective, including net received and currency. */
private PaymentUsersAmountCollector collector;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentApplicationData.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that identifies the application that originated a MercadoPago payment.
*
* Contains the name and version of the client application used at the point of
* interaction to create the payment.
*
* @see PaymentPointOfInteraction#getApplicationData()
*/
@Getter
public class PaymentApplicationData {
/** Name of the application that created the payment. */
private String name;
/** Version of the application that created the payment. */
private String version;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentBankInfo.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that holds banking information for both parties involved in a MercadoPago payment.
*
* Contains the bank account details of the payer and the collector (seller), and indicates
* whether both accounts belong to the same owner. Used primarily for bank transfer and
* Pix payment methods.
*
* @see PaymentTransactionData#getBankInfo()
*/
@Getter
public class PaymentBankInfo {
/** Bank account information of the payer. */
private PaymentBankInfoPayer payer;
/** Bank account information of the collector (seller). */
private PaymentBankInfoCollector collector;
/** Indicates whether the payer and collector share the same bank account owner. */
private String isSameBankAccountOwner;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentBankInfoCollector.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigInteger;
import lombok.Getter;
/**
* Resource that holds the bank account information of the collector (seller) in a MercadoPago payment.
*
* Identifies the collector's bank account used to receive funds from bank transfer or
* Pix-based payments.
*
* @see PaymentBankInfo#getCollector()
*/
@Getter
public class PaymentBankInfoCollector {
/** Unique identifier of the collector's bank account. */
private BigInteger accountId;
/** Full display name of the collector's bank account. */
private String longName;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentBankInfoPayer.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigInteger;
import lombok.Getter;
/**
* Resource that holds the bank account information of the payer in a MercadoPago payment.
*
* Identifies the payer's bank account used to send funds via bank transfer or Pix.
* Includes the email associated with the account for notification purposes.
*
* @see PaymentBankInfo#getPayer()
*/
@Getter
public class PaymentBankInfoPayer {
/** Email address associated with the payer's bank account. */
private String email;
/** Unique identifier of the payer's bank account. */
private BigInteger accountId;
/** Full display name of the payer's bank account. */
private String longName;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentBarcode.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that represents barcode data for a ticket or boleto-based MercadoPago payment.
*
* Contains the raw barcode content that can be used to generate a scannable barcode
* image for offline payment methods.
*
* @see PaymentTransactionDetails#getBarcode()
*/
@Getter
public class PaymentBarcode {
/** Raw barcode string content used to generate the scannable barcode. */
private String content;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentCard.java
================================================
package com.mercadopago.resources.payment;
import java.time.OffsetDateTime;
import lombok.Getter;
/**
* Resource that represents the card used to process a MercadoPago payment.
*
* Contains masked card details (first six and last four digits), expiration information,
* and the cardholder data. Full card numbers are never stored or returned for security
* compliance.
*
* @see Payment
* @see PaymentCardholder
*/
@Getter
public class PaymentCard {
/** Unique identifier of the stored card in MercadoPago's vault. */
private String id;
/** Last four digits of the card number for display purposes. */
private String lastFourDigits;
/** First six digits (BIN) of the card number, used to identify the issuer and card type. */
private String firstSixDigits;
/** Year in which the card expires. */
private int expirationYear;
/** Month in which the card expires (1-12). */
private int expirationMonth;
/** Date and time when the card was first registered. */
private OffsetDateTime dateCreated;
/** Date and time of the most recent update to the card data. */
private OffsetDateTime dateLastUpdated;
/** Information about the cardholder (name and identification). */
private PaymentCardholder cardholder;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentCardholder.java
================================================
package com.mercadopago.resources.payment;
import com.mercadopago.resources.common.Identification;
import lombok.Getter;
/**
* Resource that represents the holder of the card used in a MercadoPago payment.
*
* Contains the name printed on the card and the cardholder's identification document,
* which may be required for certain payment methods or regions.
*
* @see PaymentCard
*/
@Getter
public class PaymentCardholder {
/** Full name of the cardholder as printed on the card. */
private String name;
/** Identification document of the cardholder (e.g. CPF, DNI). */
private Identification identification;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentCounterCurrency.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource that holds counter-currency conversion details for a MercadoPago payment.
*
* When the payment currency differs from the collector's settlement currency, this resource
* provides the exchange rate, converted amount, and any refunded amount in the counter currency.
*
* @see Payment#getCounterCurrency()
*/
@Getter
public class PaymentCounterCurrency {
/** ISO 4217 currency code of the counter currency (e.g. USD, EUR). */
private String currencyId;
/** Exchange rate applied to convert from the payment currency to the counter currency. */
private BigDecimal rate;
/** Payment amount expressed in the counter currency. */
private BigDecimal amount;
/** Refunded amount expressed in the counter currency. */
private BigDecimal amountRefunded;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentData.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that holds payment method data including rules, references, and external resource URLs.
*
* Contains the configuration rules (discounts, fines, interest) applicable to the
* payment method, along with internal and external reference identifiers.
*
* @see PaymentMethod#getData()
*/
@Getter
public class PaymentData {
/** Rules defining discounts, fines, and interest for this payment method. */
private PaymentRules rules;
/** Internal reference identifier for the payment data. */
private String referenceId;
/** External reference identifier linking to the merchant's system. */
private String externalReferenceId;
/** URL of the external resource associated with the payment method (e.g. ticket page). */
private String externalResourceUrl;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentDiscount.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigDecimal;
import java.time.LocalDate;
import lombok.Getter;
/**
* Resource that represents a discount applied to a MercadoPago payment method.
*
* Defines the type of discount, its monetary value, and an optional limit date
* after which the discount is no longer applicable.
*
* @see PaymentRules#getDiscounts()
*/
@Getter
public class PaymentDiscount {
/** Type of discount (e.g. fixed, percentage). */
private String type;
/** Monetary value of the discount. */
private BigDecimal value;
/** Date after which this discount is no longer valid. */
private LocalDate limitDate;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentExpanded.java
================================================
package com.mercadopago.resources.payment;
import com.mercadopago.client.payment.PaymentNetworkTransactionDataRequest;
import lombok.Getter;
/**
* Resource that holds expanded response data for a MercadoPago payment.
*
* Returned only when the {@code X-Expand-Response-Nodes} header is used in the API request.
* Contains gateway-level details such as network transaction references, which are useful
* for reconciliation and advanced payment processing scenarios.
*
* @see Payment#getExpanded()
*/
@Getter
public class PaymentExpanded {
/** Gateway-level expanded information including network transaction references. */
private Gateway gateway;
/**
* Inner resource representing gateway-specific expanded data.
*
* Contains the network transaction reference returned by the payment gateway.
*/
@Getter
public static class Gateway {
/** Network transaction data reference from the payment gateway. */
private PaymentNetworkTransactionDataRequest reference;
}
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentFee.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource that represents a fee or financial charge rule applied to a MercadoPago payment.
*
* Used within {@link PaymentRules} to define fines and interest charges associated
* with late or deferred payments.
*
* @see PaymentRules#getFine()
* @see PaymentRules#getInterest()
*/
@Getter
public class PaymentFee {
/** Type of the fee (e.g. percentage, fixed). */
private String type;
/** Monetary or percentage value of the fee. */
private BigDecimal value;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentFeeDetail.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource that represents a single fee charged on a MercadoPago payment.
*
* Each payment may have multiple fee details, such as the MercadoPago marketplace fee,
* financing costs, or shipping fees. This resource identifies the type, who absorbs the
* cost, and the monetary amount of each fee.
*
* @see Payment#getFeeDetails()
*/
@Getter
public class PaymentFeeDetail {
/** Type of fee (e.g. mercadopago_fee, coupon_fee, financing_fee). */
private String type;
/** Party that absorbs this fee cost (e.g. collector, payer). */
private String feePayer;
/** Monetary amount of the fee. */
private BigDecimal amount;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentInvoicePeriod.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that represents the invoice period for a subscription-based MercadoPago payment.
*
* Defines the billing cycle length and type for recurring or subscription payments,
* indicating how frequently invoices are generated.
*
* @see PaymentTransactionData#getInvoicePeriod()
*/
@Getter
public class PaymentInvoicePeriod {
/** Number representing the billing cycle length (e.g. 1, 3, 12). */
private int period;
/** Unit of the billing period (e.g. monthly, yearly, daily). */
private String type;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentItem.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource that represents a single item being purchased in a MercadoPago payment.
*
* Contains details about the product or service such as title, description, quantity,
* unit price, and category. Item information is included in the additional info and helps
* with fraud prevention and purchase tracking.
*
* @see PaymentAdditionalInfo#getItems()
*/
@Getter
public class PaymentItem {
/** Unique item code or SKU provided by the merchant. */
private String id;
/** Display name of the item. */
private String title;
/** Type classification of the item. */
private String type;
/** Detailed description of the item. */
private String description;
/** URL of the item's image for display purposes. */
private String pictureUrl;
/** Category identifier that classifies the item (e.g. electronics, clothing). */
private String categoryId;
/** ISO 4217 currency code of the unit price. */
private String currencyId;
/** Number of units of this item being purchased. */
private Integer quantity;
/** Price per unit of the item. */
private BigDecimal unitPrice;
/** Whether the item includes a warranty ({@code true}) or not ({@code false}). */
private boolean warranty;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentMethod.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that represents the payment method details associated with a MercadoPago payment.
*
* Contains the data structure that holds payment rules, reference identifiers, and
* external resource URLs specific to the payment method used in the transaction.
*
* @see Payment
* @see PaymentData
*/
@Getter
public class PaymentMethod {
/** Data containing rules, references, and external resource URLs for this payment method. */
private PaymentData data;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentOrder.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that represents the purchase order associated with a MercadoPago payment.
*
* Links the payment to an order in the MercadoPago or MercadoLibre ecosystem,
* allowing tracking and reconciliation between payments and orders.
*
* @see Payment#getOrder()
*/
@Getter
public class PaymentOrder {
/** Unique identifier of the associated purchase order. */
private Long id;
/** Type of the order (e.g. mercadolibre, mercadopago). */
private String type;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentPayer.java
================================================
package com.mercadopago.resources.payment;
import com.mercadopago.resources.common.Identification;
import lombok.Getter;
import java.time.OffsetDateTime;
import java.util.Date;
/**
* Resource that represents the payer associated with a MercadoPago payment.
*
* Contains personal information about the buyer including identification, contact details,
* authentication type, and registration data. This information is used for fraud prevention
* and to process the payment correctly.
*
* @see Payment
*/
@Getter
public class PaymentPayer {
/** Payer type, mandatory when the payer is a registered Customer (e.g. customer, guest). */
private String type;
/** Unique identifier of the payer in the MercadoPago platform. */
private String id;
/** Email address of the payer. */
private String email;
/** Personal identification document of the payer (e.g. CPF, DNI, CURP). */
private Identification identification;
/** First name of the payer. */
private String firstName;
/** Last name of the payer. */
private String lastName;
/** Entity type of the payer, applicable only for bank transfer payments (e.g. individual, association). */
private String entityType;
/** Authentication type used to verify the payer's identity. */
private String authenticationType;
/** Whether the payer is a MercadoLibre Loyalty (prime/level 6) subscriber. */
private boolean isPrimeUser;
/** Whether this is the payer's first online purchase. */
private boolean isFirstPurchaseOnline;
/** Date and time when the payer registered on the merchant's platform. */
private OffsetDateTime registrationDate;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentPaymentReference.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that holds a reference to a related MercadoPago payment.
*
* Used in recurring or linked payment contexts to point back to the original or
* previous payment in a sequence.
*
* @see PaymentTransactionData#getPaymentReference()
*/
@Getter
public class PaymentPaymentReference {
/** Unique identifier of the referenced payment. */
private String id;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentPhone.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that represents a phone number associated with a MercadoPago payment payer.
*
* Contains the area code and phone number, used for contact and fraud prevention purposes.
*
* @see PaymentAdditionalInfoPayer#getPhone()
*/
@Getter
public class PaymentPhone {
/** Area code of the phone number (e.g. 11, 21, 55). */
private String areaCode;
/** Phone number without the area code. */
private String number;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentPointOfInteraction.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that describes the point of interaction where a MercadoPago payment was initiated.
*
* Identifies how and where the payment originated, such as through a QR code, deep link,
* IVR system, or checkout flow. Includes the application that created the payment and
* the transaction data associated with the interaction channel.
*
* @see Payment#getPointOfInteraction()
*/
@Getter
public class PaymentPointOfInteraction {
/** Type of the point of interaction (e.g. QR, DEEP_LINK, IVR). */
private String type;
/** Sub-type further specifying the interaction channel. */
private String subType;
/** Identifier indicating the entity or flow this interaction is linked to. */
private String linkedTo;
/** Information about the application that originated the payment. */
private PaymentApplicationData applicationData;
/** Transaction-level data from the interaction channel (e.g. QR code, ticket URL). */
private PaymentTransactionData transactionData;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentReceiverAddress.java
================================================
package com.mercadopago.resources.payment;
import com.mercadopago.resources.common.Address;
import lombok.EqualsAndHashCode;
import lombok.Getter;
/**
* Resource that represents the shipping receiver's address for a MercadoPago payment.
*
* Extends the base {@link Address} with additional fields for state, city, floor, and
* apartment details, providing a complete delivery address.
*
* @see PaymentShipments#getReceiverAddress()
*/
@EqualsAndHashCode(callSuper = true)
@Getter
public class PaymentReceiverAddress extends Address {
/** Name of the state or province. */
private String stateName;
/** Name of the city. */
private String cityName;
/** Floor number or identifier within the building. */
private String floor;
/** Apartment or unit number within the floor. */
private String apartment;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentRefund.java
================================================
package com.mercadopago.resources.payment;
import com.mercadopago.resources.common.Source;
import com.mercadopago.net.MPResource;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import lombok.Getter;
/**
* Resource that represents a refund applied to a MercadoPago payment.
*
* A refund can be total or partial, allowing the merchant to return funds to the payer.
* Each refund is linked to the original payment and tracks its own status, amount, and
* creation date.
*
* @see Payment
* @see Refunds API reference
*/
@Getter
public class PaymentRefund extends MPResource {
/** Unique identifier of this refund. */
private Long id;
/** Identifier of the original payment that was refunded. */
private Long paymentId;
/** Amount that was refunded to the payer. */
private BigDecimal amount;
/** Adjustment amount applied to the refund (e.g. rounding differences). */
private BigDecimal adjustmentAmount;
/** Current status of the refund (e.g. approved, in_process). */
private String status;
/** Mode of the refund indicating how it was processed. */
private String refundMode;
/** Date and time when the refund was created. */
private OffsetDateTime dateCreated;
/** Reason provided by the merchant for issuing this refund. */
private String reason;
/** Unique sequence number that identifies this refund transaction. */
private String uniqueSequenceNumber;
/** Source that originated the refund (e.g. collector, admin). */
private Source source;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentRules.java
================================================
package com.mercadopago.resources.payment;
import java.util.List;
import lombok.Getter;
/**
* Resource that defines the financial rules applied to a MercadoPago payment method.
*
* Contains discount, fine, and interest configurations that affect the final payment
* amount. These rules are typically set by the collector and applied at payment creation.
*
* @see PaymentData#getRules()
*/
@Getter
public class PaymentRules {
/** List of discounts applicable to the payment (e.g. early payment discounts). */
private List Contains the delivery address where the purchased items should be shipped.
* This information is part of the additional info sent with the payment.
*
* @see PaymentAdditionalInfo#getShipments()
*/
@Getter
public class PaymentShipments {
/** Full address of the shipment receiver, including state, city, floor, and apartment. */
private PaymentReceiverAddress receiverAddress;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentStatus.java
================================================
package com.mercadopago.resources.payment;
/**
* Constants representing all possible statuses of a MercadoPago payment.
*
* Use these constants to compare against the {@code status} field of a {@link Payment}
* resource instead of hard-coding string values. Each constant corresponds to a stage
* in the payment lifecycle.
*
* @see Payment#getStatus()
*/
public class PaymentStatus {
/** The payment has been approved and the funds have been accredited to the collector. */
public static final String APPROVED = "approved";
/** The user has not yet completed the payment process (e.g. waiting for bank transfer or ticket payment). */
public static final String PENDING = "pending";
/** The payment has been authorized by the card issuer but the funds have not yet been captured. */
public static final String AUTHORIZED = "authorized";
/** The payment is being reviewed by MercadoPago’s fraud prevention system. */
public static final String IN_PROCESS = "in_process";
/** A dispute has been initiated by the buyer and the payment is under mediation. */
public static final String IN_MEDIATION = "in_mediation";
/** The payment was rejected by the payment processor or issuer. The buyer may retry. */
public static final String REJECTED = "rejected";
/** The payment was cancelled by one of the parties or because the expiration time elapsed. */
public static final String CANCELLED = "cancelled";
/** The payment was fully refunded to the buyer. */
public static final String REFUNDED = "refunded";
/** A chargeback was initiated on the buyer’s credit card by the issuing bank. */
public static final String CHARGED_BACK = "charged_back";
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentSubscriptionSequence.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that represents the sequence position of a subscription-based MercadoPago payment.
*
* Tracks the current installment number within the total number of scheduled payments
* for a recurring subscription.
*
* @see PaymentTransactionData#getSubscriptionSequence()
*/
@Getter
public class PaymentSubscriptionSequence {
/** Current sequence number of this payment within the subscription (e.g. 3 of 12). */
private int number;
/** Total number of payments expected in the subscription. */
private int total;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentTax.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource that represents a tax applied to a MercadoPago payment.
*
* Defines the type and value of a tax charge included in the payment, such as
* IVA, ICMS, or other regional tax obligations.
*
* @see Payment#getTaxes()
*/
@Getter
public class PaymentTax {
/** Type of tax applied (e.g. IVA, ICMS, ISS). */
private String type;
/** Monetary value of the tax. */
private BigDecimal value;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentThreeDSInfo.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that holds 3D Secure (3DS) authentication information for a MercadoPago payment.
*
* Contains the external resource URL for the 3DS challenge flow and the challenge request
* (creq) data needed to complete cardholder authentication.
*
* @see Payment#getThreeDSInfo()
*/
@Getter
public class PaymentThreeDSInfo {
/** URL of the external 3DS challenge page where the cardholder completes authentication. */
private String externalResourceUrl;
/** Challenge request (creq) payload used in the 3DS authentication flow. */
private String creq;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentTransactionData.java
================================================
package com.mercadopago.resources.payment;
import lombok.Getter;
/**
* Resource that holds transaction-level data from the point of interaction for a MercadoPago payment.
*
* Contains QR code information for Pix payments, bank transfer details, ticket URLs for
* offline payment methods, and subscription-related data for recurring payments. This data
* is typically provided within the {@link PaymentPointOfInteraction} resource.
*
* @see PaymentPointOfInteraction#getTransactionData()
*/
@Getter
public class PaymentTransactionData {
/** QR code string content used for Pix or other QR-based payment methods. */
private String qrCode;
/** Base64-encoded image of the QR code for rendering in client applications. */
private String qrCodeBase64;
/** BACEN (Brazilian Central Bank) end-to-end identifier for Pix transactions. */
private String transactionId;
/** Identifier of the bank transfer transaction. */
private Long bankTransferId;
/** Identifier of the financial institution that processed the transaction. */
private Long financialInstitution;
/** Banking information for both the payer and the collector involved in the transaction. */
private PaymentBankInfo bankInfo;
/** URL of the payment ticket or voucher for offline payment methods. */
private String ticketUrl;
/** Whether this is the first time the payment method is being used by the payer. */
private boolean firstTimeUse;
/** Sequence information for subscription-based recurring payments. */
private PaymentSubscriptionSequence subscriptionSequence;
/** Identifier of the subscription associated with this recurring payment. */
private String subscriptionId;
/** Invoice period details for subscription or recurring billing payments. */
private PaymentInvoicePeriod invoicePeriod;
/** Reference to a related payment in the context of recurring or linked transactions. */
private PaymentPaymentReference paymentReference;
/** Billing date for subscription or recurring payment invoices. */
private String billingDate;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentTransactionDetails.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource that holds detailed transaction information for a MercadoPago payment.
*
* Includes financial details such as the net received amount, total paid amount, installment
* breakdown, and references used by payment processors, acquirers, and financial institutions.
* Also contains barcode and digitable line data for ticket-based payment methods.
*
* @see Payment#getTransactionDetails()
*/
@Getter
public class PaymentTransactionDetails {
/** Name or identifier of the external financial institution that processed the payment. */
private String financialInstitution;
/** Net amount received by the seller after deducting all fees. */
private BigDecimal netReceivedAmount;
/** Total amount paid by the buyer, including fees and financing costs. */
private BigDecimal totalPaidAmount;
/** Amount of each installment when the payment is split into multiple installments. */
private BigDecimal installmentAmount;
/** Amount overpaid by the buyer, applicable only for ticket-based payment methods. */
private BigDecimal overpaidAmount;
/** URL of the external resource at the payment processor (e.g. ticket or voucher page). */
private String externalResourceUrl;
/**
* Reference identifier at the payment method level. For credit cards this is the USN (Unique
* Sequence Number); for offline methods it is the code to provide at the cashier or ATM.
*/
private String paymentMethodReferenceId;
/** Reference identifier assigned by the payment acquirer. */
private String acquirerReference;
/** BACEN (Brazilian Central Bank) end-to-end identifier for Pix transactions. */
private String transactionId;
/** Digitable line representation of the barcode for boleto or ticket payments. */
private String digitableLine;
/** Verification code used to validate the payment at certain financial institutions. */
private String verificationCode;
/** Period during which the payment amount can be deferred before becoming payable. */
private String payableDeferralPeriod;
/** Identifier of the bank transfer transaction. */
private String bankTransferId;
/** Barcode data associated with ticket or boleto payment methods. */
private PaymentBarcode barcode;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentUsersAmountCollector.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource that represents the amount breakdown from the collector's (seller's) perspective
* in a MercadoPago payment.
*
* Contains the transaction amount and net received amount in the collector's currency,
* useful for cross-currency marketplace reconciliation.
*
* @see PaymentAmounts#getCollector()
*/
@Getter
public class PaymentUsersAmountCollector {
/** ISO 4217 currency code of the collector's settlement currency. */
private String currencyId;
/** Gross transaction amount in the collector's currency. */
private BigDecimal transaction;
/** Net amount received by the collector after all fees are deducted. */
private BigDecimal netReceived;
}
================================================
FILE: src/main/java/com/mercadopago/resources/payment/PaymentUsersAmountPayer.java
================================================
package com.mercadopago.resources.payment;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource that represents the amount breakdown from the payer's (buyer's) perspective
* in a MercadoPago payment.
*
* Contains the transaction amount and total paid amount in the payer's currency,
* which may include fees and financing costs.
*
* @see PaymentAmounts#getPayer()
*/
@Getter
public class PaymentUsersAmountPayer {
/** ISO 4217 currency code of the payer's currency. */
private String currencyId;
/** Transaction amount in the payer's currency before additional charges. */
private BigDecimal transaction;
/** Total amount paid by the buyer, including fees and financing costs. */
private BigDecimal totalPaid;
}
================================================
FILE: src/main/java/com/mercadopago/resources/paymentmethod/PaymentMethod.java
================================================
package com.mercadopago.resources.paymentmethod;
import com.mercadopago.net.MPResource;
import java.math.BigDecimal;
import java.util.List;
import lombok.Getter;
/**
* Resource that represents an available payment method in the MercadoPago platform.
*
* Describes a payment method that can be used to process payments, including its type
* (credit card, debit card, ticket, bank transfer, etc.), current status, amount limits,
* accreditation time, and configuration settings such as card number validation rules
* and security code requirements.
*
* @see Payment Methods API reference
*/
@Getter
public class PaymentMethod extends MPResource {
/** Unique identifier of the payment method (e.g. visa, master, pix, bolbradesco). */
private String id;
/** Type classification of the payment method. */
private String type;
/** Identifier of the card associated with this payment method, when applicable. */
private String cardId;
/** Number of installments available for this payment method. */
private Integer installments;
/** Human-readable display name of the payment method (e.g. Visa, Mastercard, Pix). */
private String name;
/** Payment type identifier (e.g. credit_card, debit_card, ticket, bank_transfer, prepaid_card). */
private String paymentTypeId;
/** Current availability status of the payment method (e.g. active, inactive, temporally_unavailable). */
private String status;
/** URL of the payment method logo suitable for display on secure (HTTPS) sites. */
private String secureThumbnail;
/** URL of the payment method logo for general display. */
private String thumbnail;
/** Whether the payment capture can be deferred (e.g. supported, unsupported, does_not_apply). */
private String deferredCapture;
/** List of configuration settings defining card number, BIN, and security code validation rules. */
private List Identifies a bank or financial entity that processes payments for a specific payment
* method, such as ATM networks, banks for transfers, or card-issuing institutions.
*
* @see PaymentMethod#getFinancialInstitutions()
*/
@Getter
public class PaymentMethodFinancialInstitutions {
/** Unique external identifier of the financial institution (e.g. bank code, ATM company ID). */
private Long id;
/** Human-readable name or description of the financial institution. */
private String description;
}
================================================
FILE: src/main/java/com/mercadopago/resources/paymentmethod/PaymentMethodSettings.java
================================================
package com.mercadopago.resources.paymentmethod;
import lombok.Getter;
/**
* Resource that groups the validation and configuration settings for a MercadoPago payment method.
*
* Combines BIN pattern rules, card number length and validation settings, and security
* code requirements into a single settings object. A payment method may have multiple
* settings entries for different card ranges.
*
* @see PaymentMethod#getSettings()
*/
@Getter
public class PaymentMethodSettings {
/** BIN (Bank Identification Number) pattern and exclusion rules for card acceptance. */
private PaymentMethodSettingsBin bin;
/** Card number length and checksum validation settings. */
private PaymentMethodSettingsCardNumber cardNumber;
/** Security code (CVV/CVC) mode, length, and card location settings. */
private PaymentMethodSettingsSecurityCode securityCode;
}
================================================
FILE: src/main/java/com/mercadopago/resources/paymentmethod/PaymentMethodSettingsBin.java
================================================
package com.mercadopago.resources.paymentmethod;
import lombok.Getter;
/**
* Resource that defines BIN (Bank Identification Number) validation rules for a payment method.
*
* Uses regular expression patterns to determine which card BINs are accepted, excluded,
* or eligible for installment payments. These rules help identify the card issuer and
* control which cards can be used with a given payment method.
*
* @see PaymentMethodSettings#getBin()
*/
@Getter
public class PaymentMethodSettingsBin {
/** Regular expression pattern matching the accepted BIN ranges for this payment method. */
private String pattern;
/** Regular expression pattern matching BIN ranges that are explicitly excluded. */
private String exclusionPattern;
/** Regular expression pattern matching BIN ranges eligible for multi-installment payments. */
private String installmentsPattern;
}
================================================
FILE: src/main/java/com/mercadopago/resources/paymentmethod/PaymentMethodSettingsCardNumber.java
================================================
package com.mercadopago.resources.paymentmethod;
import lombok.Getter;
/**
* Resource that defines card number validation settings for a MercadoPago payment method.
*
* Specifies the expected card number length and whether checksum validation (typically
* the Luhn algorithm) should be applied to verify the card number.
*
* @see PaymentMethodSettings#getCardNumber()
*/
@Getter
public class PaymentMethodSettingsCardNumber {
/** Expected number of digits in the card number. */
private Integer length;
/** Validation algorithm to apply (e.g. standard for Luhn checksum, or none). */
private String validation;
}
================================================
FILE: src/main/java/com/mercadopago/resources/paymentmethod/PaymentMethodSettingsSecurityCode.java
================================================
package com.mercadopago.resources.paymentmethod;
import lombok.Getter;
/**
* Resource that defines security code (CVV/CVC) settings for a MercadoPago payment method.
*
* Specifies whether the security code is mandatory, its expected length, and where
* it is located on the physical card (front or back).
*
* @see PaymentMethodSettings#getSecurityCode()
*/
@Getter
public class PaymentMethodSettingsSecurityCode {
/** Whether the security code is mandatory or optional (e.g. mandatory, optional). */
private String mode;
/** Expected number of digits in the security code (typically 3 or 4). */
private int length;
/** Physical location of the security code on the card (e.g. back, front). */
private String cardLocation;
}
================================================
FILE: src/main/java/com/mercadopago/resources/point/OperatingMode.java
================================================
package com.mercadopago.resources.point;
/**
* Enumeration of operating modes available for Point of Sale (POS) devices.
*
* Defines how a MercadoPago Point device operates in the payment ecosystem:
* Returned after successfully requesting the cancellation of a previously created payment
* intent. Contains the identifier of the cancelled intent for confirmation purposes.
*
* @see com.mercadopago.client.point.PointClient#cancelPaymentIntent(String, String)
*/
@Getter
public class PointCancelPaymentIntent extends MPResource {
/** Unique identifier of the cancelled payment intent. */
private String id;
}
================================================
FILE: src/main/java/com/mercadopago/resources/point/PointDevice.java
================================================
package com.mercadopago.resources.point;
import lombok.Getter;
/**
* Resource representing a MercadoPago Point device.
*
* Contains basic identifying information about a physical Point device, including its unique
* identifier and current operating mode (e.g., PDV or STANDALONE).
*
* @see PointDevices
* @see OperatingMode
*/
@Getter
public class PointDevice {
/** Unique identifier of the Point device. */
private String id;
/** Current operating mode of the device (e.g., PDV or STANDALONE). */
private String operatingMode;
}
================================================
FILE: src/main/java/com/mercadopago/resources/point/PointDeviceOperatingMode.java
================================================
package com.mercadopago.resources.point;
import com.mercadopago.client.point.OperatingMode;
import com.mercadopago.net.MPResource;
import lombok.Getter;
/**
* Resource representing the result of changing a Point device's operating mode.
*
* Returned after requesting a change in the operating mode of a Point device. Contains the
* updated {@link OperatingMode} value confirming the applied configuration.
*
* @see OperatingMode
* @see com.mercadopago.client.point.PointClient#changeDeviceOperatingMode(String,
* com.mercadopago.client.point.PointDeviceOperatingModeRequest)
*/
@Getter
public class PointDeviceOperatingMode extends MPResource {
/** Updated operating mode of the device after the change request. */
private OperatingMode operatingMode;
}
================================================
FILE: src/main/java/com/mercadopago/resources/point/PointDevices.java
================================================
package com.mercadopago.resources.point;
import com.mercadopago.net.MPResource;
import com.mercadopago.resources.ResultsPaging;
import java.util.List;
import lombok.Getter;
/**
* Resource representing a paginated list of MercadoPago Point devices.
*
* Contains the collection of {@link PointDevice} entries associated with the authenticated
* account, along with pagination metadata for navigating large result sets.
*
* @see PointDevice
* @see com.mercadopago.client.point.PointClient#getDevices(com.mercadopago.client.point.PointDevicesRequest)
*/
@Getter
public class PointDevices extends MPResource {
/** Collection of Point devices returned in this page. */
private List A payment intent encapsulates a pending charge that is queued on a specific Point device.
* It holds the amount, description, payment configuration, and optional additional information
* such as external references and ticket printing preferences.
*
* @see PointPaymentIntentAdditionalInfo
* @see PointPaymentIntentPayment
* @see com.mercadopago.client.point.PointClient#createPaymentIntent(String,
* com.mercadopago.client.point.PointPaymentIntentRequest)
*/
@Getter
public class PointPaymentIntent extends MPResource {
/** Unique identifier of the payment intent. */
private String id;
/** Short description of the payment intent shown on the device. */
private String description;
/** Identifier of the Point device where this payment intent is queued. */
private String deviceId;
/** Total amount to be charged for this payment intent. */
private BigDecimal amount;
/** Additional metadata such as external reference, ticket number, and print settings. */
private PointPaymentIntentAdditionalInfo additionalInfo;
/** Payment configuration including type, installments, and cost allocation. */
private PointPaymentIntentPayment payment;
}
================================================
FILE: src/main/java/com/mercadopago/resources/point/PointPaymentIntentAdditionalInfo.java
================================================
package com.mercadopago.resources.point;
import lombok.Getter;
/**
* Resource containing additional metadata for a Point payment intent.
*
* Holds supplementary information that enriches the payment intent, including an external
* reference for integration with external systems, ticket printing preferences, and a ticket
* number for invoice tracking.
*
* @see PointPaymentIntent
*/
@Getter
public class PointPaymentIntentAdditionalInfo {
/**
* An alphanumeric value can be an identifier in your application. It will be returned in the
* Webhook notification.
*/
private String externalReference;
/** A boolean value that determines if you want to print the ticket on the device. */
private Boolean printOnTerminal;
/**
* An alphanumeric value to identify the invoice or ticket number. It will be printed on the
* device ticket.
*/
private String ticketNumber;
}
================================================
FILE: src/main/java/com/mercadopago/resources/point/PointPaymentIntentList.java
================================================
package com.mercadopago.resources.point;
import com.mercadopago.net.MPResource;
import java.util.List;
import lombok.Getter;
/**
* Resource representing a list of payment intent events from Point devices.
*
* Contains a collection of {@link PointPaymentIntentListEvent} entries, each representing a
* payment intent event with its status and creation timestamp. Used to retrieve the history of
* payment intents processed on a device.
*
* @see PointPaymentIntentListEvent
* @see com.mercadopago.client.point.PointClient#getPaymentIntentList(String)
*/
@Getter
public class PointPaymentIntentList extends MPResource {
/** Collection of payment intent events associated with the device. */
private List Each event captures a snapshot of a payment intent at a given point in time, including its
* current processing status and the timestamp when it was created.
*
* @see PointPaymentIntentList
*/
@Getter
public class PointPaymentIntentListEvent {
/** Unique identifier of the payment intent associated with this event. */
private String paymentIntentId;
/** Current processing status of the payment intent (e.g., open, finished, cancelled). */
private String status;
/** Timestamp when the payment intent was created. */
private OffsetDateTime createdOn;
}
================================================
FILE: src/main/java/com/mercadopago/resources/point/PointPaymentIntentPayment.java
================================================
package com.mercadopago.resources.point;
import lombok.Getter;
/**
* Resource containing payment configuration details for a Point payment intent.
*
* Defines how the payment should be processed, including the payment method type (credit card,
* debit card, or voucher), installment settings, and who bears the installment cost.
*
* @see PointPaymentIntent
*/
@Getter
public class PointPaymentIntentPayment {
/** Unique identifier of the resulting payment, available after processing. */
private String id;
/**
* Number of installments (1 to 72). Only applicable when {@code type} is {@code credit_card}.
*/
private Integer installments;
/**
* Party responsible for the installment cost ({@code seller} or {@code buyer}). Only applicable
* when {@code type} is {@code credit_card}.
*/
private String installmentsCost;
/** Payment method type: {@code credit_card}, {@code debit_card}, or {@code voucher_card}. */
private String type;
/** Specific voucher type when payment type is {@code voucher_card}. */
private String voucherType;
}
================================================
FILE: src/main/java/com/mercadopago/resources/point/PointSearchPaymentIntent.java
================================================
package com.mercadopago.resources.point;
import com.mercadopago.net.MPResource;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource representing the result of searching for a specific payment intent on a Point device.
*
* Extends the standard payment intent data with an additional {@code state} field that indicates
* the current lifecycle state of the intent. This resource is returned when querying for a
* previously created payment intent by its identifier.
*
* @see PointPaymentIntent
* @see PointPaymentIntentAdditionalInfo
* @see PointPaymentIntentPayment
* @see com.mercadopago.client.point.PointClient#searchPaymentIntent(String, String)
*/
@Getter
public class PointSearchPaymentIntent extends MPResource {
/** Unique identifier of the payment intent. */
private String id;
/** Short description of the payment intent shown on the device. */
private String description;
/** Identifier of the Point device where this payment intent is queued. */
private String deviceId;
/** Total amount to be charged for this payment intent. */
private BigDecimal amount;
/** Additional metadata such as external reference, ticket number, and print settings. */
private PointPaymentIntentAdditionalInfo additionalInfo;
/** Payment configuration including type, installments, and cost allocation. */
private PointPaymentIntentPayment payment;
/** Current lifecycle state of the payment intent (e.g., OPEN, FINISHED, CANCELED, ERROR). */
private String state;
}
================================================
FILE: src/main/java/com/mercadopago/resources/point/PointStatusPaymentIntent.java
================================================
package com.mercadopago.resources.point;
import com.mercadopago.net.MPResource;
import java.time.OffsetDateTime;
import lombok.Getter;
/**
* Resource representing the current status of a payment intent on a Point device.
*
* Provides a lightweight view of a payment intent's processing status along with its creation
* timestamp. Useful for polling or checking the progress of a payment intent.
*
* @see PointPaymentIntent
* @see com.mercadopago.client.point.PointClient#getPaymentIntentStatus(String, String)
*/
@Getter
public class PointStatusPaymentIntent extends MPResource {
/** Current processing status of the payment intent. */
private String status;
/** Timestamp when the payment intent was created. */
private OffsetDateTime createdOn;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preapproval/Preapproval.java
================================================
package com.mercadopago.resources.preapproval;
import com.mercadopago.net.MPResource;
import java.time.OffsetDateTime;
import lombok.Getter;
/**
* Resource representing a MercadoPago subscription (preapproval).
*
* A preapproval authorizes the seller to collect recurring payments from a payer according to
* the billing configuration defined in {@link PreapprovalAutoRecurring}. The lifecycle of a
* subscription includes creation, activation via the checkout link ({@code initPoint}), and
* ongoing automated billing until cancellation or expiration.
*
* @see PreapprovalAutoRecurring
* @see com.mercadopago.client.preapproval.PreapprovalClient
*/
@Getter
public class Preapproval extends MPResource {
/** Unique identifier of the preapproval (subscription). */
private String id;
/** Identifier of the payer who authorized the recurring charges. */
private Long payerId;
/** Email address of the payer associated with this subscription. */
private String payerEmail;
/** URL the payer is redirected to after completing the subscription flow. */
private String backUrl;
/** Identifier of the seller (collector) who receives the recurring payments. */
private Long collectorId;
/** Identifier of the application that created this subscription. */
private Long applicationId;
/** Current status of the subscription (e.g., pending, authorized, paused, cancelled). */
private String status;
/** Title or reason describing the purpose of the subscription. */
private String reason;
/** External reference for correlating this subscription with the integrator's system. */
private String externalReference;
/** Scheduled date of the next automatic payment debit. */
private OffsetDateTime nextPaymentDate;
/** Timestamp when the subscription was created. */
private OffsetDateTime dateCreated;
/** Timestamp when the subscription was last modified. */
private OffsetDateTime lastModified;
/** Production checkout URL where the payer authorizes the subscription. */
private String initPoint;
/** Sandbox checkout URL for testing the subscription flow. */
private String sandboxInitPoint;
/** Identifier of the payment method used for recurring charges. */
private String paymentMethodId;
/** Recurring billing configuration including frequency, currency, and amount. */
private PreapprovalAutoRecurring autoRecurring;
/** Optimistic concurrency control version number. */
private Long version;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preapproval/PreapprovalAutoRecurring.java
================================================
package com.mercadopago.resources.preapproval;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import lombok.Getter;
/**
* Resource representing the recurring billing configuration of a subscription (preapproval).
*
* Defines how often and how much is charged to the payer on each billing cycle, including the
* currency, amount, frequency, and the active time window of the recurring charges.
*
* @see Preapproval
*/
@Getter
public class PreapprovalAutoRecurring {
/** ISO 4217 currency code for the recurring charges (e.g., ARS, BRL, USD). */
private String currencyId;
/** Amount charged on each billing cycle. */
private BigDecimal transactionAmount;
/** Number of time units between each billing cycle. */
private Integer frequency;
/** Unit of time for the billing frequency ({@code days} or {@code months}). */
private String frequencyType;
/** Date when the recurring charges begin. */
private OffsetDateTime startDate;
/** Date when the recurring charges end. */
private OffsetDateTime endDate;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/Preference.java
================================================
package com.mercadopago.resources.preference;
import com.mercadopago.net.MPResource;
import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.util.List;
import java.util.Map;
import lombok.Getter;
/**
* Resource representing a MercadoPago checkout preference.
*
* A preference defines the payment experience for the buyer, including which items are being
* purchased, accepted payment methods, shipping options, redirect URLs, and expiration rules.
* After creation, the {@code initPoint} URL is used to redirect buyers to the MercadoPago
* Checkout flow.
*
* @see PreferenceItem
* @see PreferencePayer
* @see PreferencePaymentMethods
* @see PreferenceBackUrls
* @see PreferenceShipments
* @see com.mercadopago.client.preference.PreferenceClient
*/
@Getter
public class Preference extends MPResource {
/** Unique identifier of the preference. */
private String id;
/** Collection of items included in this checkout preference. */
private List Contains the individual amounts applicable to both the payer and the collector (seller),
* including their respective currencies and transaction values.
*
* @see Preference
* @see PreferenceUserAmount
*/
@Getter
public class PreferenceAmounts {
/** Amount information applicable to the payer. */
private PreferenceUserAmount payer;
/** Amount information applicable to the collector (seller). */
private PreferenceUserAmount collector;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceBackUrls.java
================================================
package com.mercadopago.resources.preference;
import lombok.Getter;
/**
* Resource representing the redirect URLs configured in a checkout preference.
*
* Defines the URLs where the buyer is redirected after completing the checkout flow, depending
* on the payment outcome: approved, pending, or failed.
*
* @see Preference
*/
@Getter
public class PreferenceBackUrls {
/** URL to redirect the buyer when the payment is approved. */
private String success;
/** URL to redirect the buyer when the payment is pending review or processing. */
private String pending;
/** URL to redirect the buyer when the payment is rejected or fails. */
private String failure;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceCategoryDescriptor.java
================================================
package com.mercadopago.resources.preference;
import java.time.OffsetDateTime;
import lombok.Getter;
/**
* Resource representing category-specific descriptive information for a preference item.
*
* Provides additional context for items in specialized categories such as travel. Includes
* passenger details, route information for flights, and the date of the event or trip.
*
* @see PreferenceItem
* @see PreferencePassenger
* @see PreferenceRoute
*/
@Getter
public class PreferenceCategoryDescriptor {
/** Passenger details associated with this item (e.g., for airline tickets). */
private PreferencePassenger passenger;
/** Flight route information including departure and destination. */
private PreferenceRoute route;
/** Date of the event or trip associated with this item. */
private OffsetDateTime eventDate;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceCounterCurrency.java
================================================
package com.mercadopago.resources.preference;
import lombok.Getter;
/**
* Resource representing the counter currency configuration for cross-currency payments.
*
* Specifies the alternative currency in which the payment amount is displayed or settled
* when it differs from the preference's primary currency.
*
* @see Preference
*/
@Getter
public class PreferenceCounterCurrency {
/** ISO 4217 currency code of the counter currency (e.g., USD, EUR). */
private String currencyId;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceDifferentialPricing.java
================================================
package com.mercadopago.resources.preference;
import lombok.Getter;
/**
* Resource representing the differential pricing configuration of a checkout preference.
*
* References a pre-configured differential pricing rule by its identifier. When applied, it
* enables special pricing conditions for specific buyer segments or payment methods.
*
* @see Preference
*/
@Getter
public class PreferenceDifferentialPricing {
/** Unique identifier of the differential pricing rule to apply. */
private Long id;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceFreeMethod.java
================================================
package com.mercadopago.resources.preference;
import lombok.Getter;
/**
* Resource representing a shipping method offered as free shipping in a checkout preference.
*
* Identifies a specific shipping method by its ID that the seller offers at no cost to the
* buyer. Only applicable when the shipment mode is {@code me2}.
*
* @see PreferenceShipments
*/
@Getter
public class PreferenceFreeMethod {
/** Unique identifier of the shipping method offered for free. */
private Long id;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceItem.java
================================================
package com.mercadopago.resources.preference;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource representing an item included in a checkout preference.
*
* Describes a product or service the buyer is purchasing, including its title, price, quantity,
* and optional metadata such as category, image, and warranty information.
*
* @see Preference
* @see PreferenceCategoryDescriptor
*/
@Getter
public class PreferenceItem {
/** Unique item code or SKU identifier. */
private String id;
/** Display title or name of the item. */
private String title;
/** Type classification of the item. */
private String type;
/** Detailed description of the item. */
private String description;
/** URL of the item's representative image. */
private String pictureUrl;
/** MercadoPago category identifier for the item. */
private String categoryId;
/** Number of units of this item being purchased. */
private int quantity;
/** Price per unit in the specified currency. */
private BigDecimal unitPrice;
/** Whether the item includes a warranty. */
private boolean warranty;
/** ISO 4217 currency code for the item's price (e.g., ARS, BRL, USD). */
private String currencyId;
/** Category-specific descriptor with additional details (e.g., passenger and route for travel). */
private PreferenceCategoryDescriptor categoryDescriptor;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferencePassenger.java
================================================
package com.mercadopago.resources.preference;
import com.mercadopago.client.common.IdentificationRequest;
import lombok.Getter;
/**
* Resource representing passenger information for travel-related preference items.
*
* Contains the personal details and identification of a passenger, typically used in
* airline or transportation category descriptors within a checkout preference.
*
* @see PreferenceCategoryDescriptor
*/
@Getter
public class PreferencePassenger {
/** First name of the passenger. */
private String firstName;
/** Last name of the passenger. */
private String lastName;
/** Official identification document of the passenger (type and number). */
private IdentificationRequest identification;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferencePayer.java
================================================
package com.mercadopago.resources.preference;
import com.mercadopago.resources.common.Address;
import com.mercadopago.resources.common.Identification;
import com.mercadopago.resources.common.Phone;
import java.time.OffsetDateTime;
import java.util.Date;
import lombok.Getter;
/**
* Resource representing the buyer (payer) information in a checkout preference.
*
* Contains the payer's personal details, contact information, address, and behavioral metadata
* used by MercadoPago to enhance the checkout experience and fraud prevention analysis.
*
* @see Preference
*/
@Getter
public class PreferencePayer {
/** First name of the payer. */
private String name;
/** Last name (surname) of the payer. */
private String surname;
/** Email address of the payer. */
private String email;
/** Phone contact information of the payer. */
private Phone phone;
/** Official identification document of the payer (type and number). */
private Identification identification;
/** Residential or billing address of the payer. */
private Address address;
/** Timestamp when the payer's user account was created. */
private OffsetDateTime dateCreated;
/** Timestamp of the payer's most recent purchase. */
private OffsetDateTime lastPurchase;
/** Authentication method used by the payer (e.g., gmail, facebook, native). */
private String authenticationType;
/** Whether the payer is a MercadoLibre Nivel 6 / Prime subscriber. */
private Boolean isPrimeUser;
/** Whether this is the payer's first online purchase. */
private Boolean isFirstPurchaseOnline;
/** Date when the payer registered on the platform. */
private OffsetDateTime registrationDate;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferencePaymentMethod.java
================================================
package com.mercadopago.resources.preference;
import lombok.Getter;
/**
* Resource representing a specific payment method referenced in a checkout preference.
*
* Used to identify individual payment methods that are either excluded from or set as default
* in the preference's payment configuration.
*
* @see PreferencePaymentMethods
*/
@Getter
public class PreferencePaymentMethod {
/** Unique identifier of the payment method (e.g., visa, master, amex). */
private String id;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferencePaymentMethods.java
================================================
package com.mercadopago.resources.preference;
import java.util.List;
import lombok.Getter;
/**
* Resource representing the payment methods configuration of a checkout preference.
*
* Controls which payment methods and types are available to the buyer during checkout,
* including exclusions, default selections, and installment limits.
*
* @see Preference
* @see PreferencePaymentMethod
* @see PreferencePaymentType
*/
@Getter
public class PreferencePaymentMethods {
/** Payment methods excluded from the checkout (except account_money). */
private List Used to identify payment type categories (e.g., credit_card, debit_card, ticket) that can
* be excluded from the checkout flow.
*
* @see PreferencePaymentMethods
*/
@Getter
public class PreferencePaymentType {
/** Identifier of the payment type (e.g., credit_card, debit_card, ticket, atm). */
private String id;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceReceiverAddress.java
================================================
package com.mercadopago.resources.preference;
import com.mercadopago.resources.common.Address;
import lombok.Getter;
/**
* Resource representing the shipping receiver's address in a checkout preference.
*
* Extends the base {@link Address} with additional location details such as country name,
* state name, city, floor, and apartment. Used to specify where the shipment should be delivered.
*
* @see PreferenceShipments
* @see Address
*/
@Getter
public class PreferenceReceiverAddress extends Address {
/** Full name of the country for the delivery address. */
private String countryName;
/** Full name of the state or province for the delivery address. */
private String stateName;
/** Floor number within the building. */
private String floor;
/** Apartment or unit identifier within the building. */
private String apartment;
/** Full name of the city for the delivery address. */
private String cityName;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceRoute.java
================================================
package com.mercadopago.resources.preference;
import java.time.OffsetDateTime;
import lombok.Getter;
/**
* Resource representing flight route information for travel-related preference items.
*
* Contains departure and arrival details for a flight segment, including airport codes,
* scheduled times, and the operating airline. Used within the category descriptor of travel items.
*
* @see PreferenceCategoryDescriptor
*/
@Getter
public class PreferenceRoute {
/** Departure airport code or city name. */
private String departure;
/** Destination airport code or city name. */
private String destination;
/** Scheduled departure date and time. */
private OffsetDateTime departureDateTime;
/** Scheduled arrival date and time. */
private OffsetDateTime arrivalDateTime;
/** Name of the airline or transportation company. */
private String company;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceSearch.java
================================================
package com.mercadopago.resources.preference;
import com.mercadopago.net.MPResource;
import java.time.OffsetDateTime;
import java.util.List;
import lombok.Getter;
/**
* Resource representing a lightweight preference summary returned from search results.
*
* Contains a subset of preference attributes optimized for listing and filtering, including
* identifiers, dates, payer information, and operational metadata. Unlike {@link Preference}, this
* resource does not include the full item details or nested configuration objects.
*
* @see Preference
* @see com.mercadopago.client.preference.PreferenceClient#search(com.mercadopago.client.preference.PreferenceSearchRequest)
*/
@Getter
public class PreferenceSearch extends MPResource {
/** Unique identifier of the preference. */
private String id;
/** Identifier of the OAuth application client that created this preference. */
private String clientId;
/** Identifier of the seller (collector) who receives the payment. */
private Long collectorId;
/** Timestamp when the preference was created. */
private OffsetDateTime dateCreated;
/** Start date from which the preference becomes active. */
private OffsetDateTime expirationDateFrom;
/** End date after which the preference is no longer valid. */
private OffsetDateTime expirationDateTo;
/** Whether this preference has an expiration window. */
private Boolean expires;
/** External reference for correlating this preference with the integrator's system. */
private String externalReference;
/** List of item identifiers included in this preference. */
private List Defines how purchased items are delivered to the buyer, including the shipping mode, cost,
* dimensions, available free methods, and the receiver's delivery address. Supports both
* MercadoEnvios ({@code me2}) and custom shipping modes.
*
* @see Preference
* @see PreferenceFreeMethod
* @see PreferenceReceiverAddress
*/
@Getter
public class PreferenceShipments {
/** Shipping mode (e.g., custom, me2, not_specified). */
private String mode;
/** Whether the buyer can pick up the shipment at the seller's store (me2 mode only). */
private Boolean localPickup;
/** Package dimensions in the format "height x width x length, weight" (me2 mode only). */
private String dimensions;
/** Identifier of the default shipping method pre-selected in checkout (me2 mode only). */
private String defaultShippingMethod;
/** List of shipping methods offered at no cost to the buyer (me2 mode only). */
private List Defines a tax entry with its type and monetary value. Multiple taxes can be associated with
* a single preference to cover different tax obligations (e.g., IVA, IIBB).
*
* @see Preference
*/
@Getter
public class PreferenceTax {
/** Tax type identifier (e.g., IVA, INC). */
private String type;
/** Monetary value of the tax. */
private BigDecimal value;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceTrack.java
================================================
package com.mercadopago.resources.preference;
import com.mercadopago.client.preference.PreferenceTrackValuesRequest;
import lombok.Getter;
/**
* Resource representing a tracking tag executed during the buyer's checkout interaction.
*
* Enables conversion tracking by associating the checkout flow with advertising platforms
* such as Google Ads or Facebook Ads. Each track specifies a type and its corresponding
* platform-specific identifiers.
*
* @see Preference
* @see PreferenceTrackValues
*/
@Getter
public class PreferenceTrack {
/** Tracking platform type ({@code google_ad} or {@code facebook_ad}). */
private String type;
/** Platform-specific tracking values (conversion IDs, pixel IDs, etc.). */
private PreferenceTrackValuesRequest values;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceTrackValues.java
================================================
package com.mercadopago.resources.preference;
import lombok.Getter;
/**
* Resource containing platform-specific tracking identifiers for checkout conversion tracking.
*
* Holds the values needed by advertising platforms to register conversions during the checkout
* flow. Supports Google Ads (via conversion ID and label) and Facebook Ads (via pixel ID).
*
* @see PreferenceTrack
*/
@Getter
public class PreferenceTrackValues {
/** Google Ads conversion ID used in the GTM Conversion Tracking tag. */
private String conversionId;
/** Google Ads conversion label used in the GTM Conversion Tracking tag. */
private String conversionLabel;
/** Facebook Pixel ID for tracking conversions on Facebook Ads. */
private String pixelId;
}
================================================
FILE: src/main/java/com/mercadopago/resources/preference/PreferenceUserAmount.java
================================================
package com.mercadopago.resources.preference;
import java.math.BigDecimal;
import lombok.Getter;
/**
* Resource representing the amount details for a specific party (payer or collector) in a
* checkout preference.
*
* Contains the currency and transaction amount applicable to the party. Used within
* {@link PreferenceAmounts} to break down the total preference amount by role.
*
* @see PreferenceAmounts
*/
@Getter
public class PreferenceUserAmount {
/** ISO 4217 currency code for the transaction amount (e.g., ARS, BRL, USD). */
private String currencyId;
/** Transaction amount applicable to this party. */
private BigDecimal transaction;
}
================================================
FILE: src/main/java/com/mercadopago/resources/user/User.java
================================================
package com.mercadopago.resources.user;
import com.mercadopago.net.MPResource;
import lombok.Getter;
/**
* Resource representing the authenticated MercadoPago user account.
*
* Contains profile information of the user associated with the current access token, including
* personal details, site affiliation, and country. Typically retrieved to verify credentials or
* obtain account metadata.
*
* @see com.mercadopago.client.user.UserClient
*/
@Getter
public class User extends MPResource {
/** Unique numeric identifier of the user account. */
private Long id;
/** Public nickname or display name of the user. */
private String nickname;
/** First name of the user. */
private String firstName;
/** Last name of the user. */
private String lastName;
/** Email address associated with the user account. */
private String email;
/** Identifier of the MercadoPago site the user belongs to (e.g., MLA, MLB, MLM). */
private String siteId;
/** ISO 3166-1 country code of the user's registered country. */
private String countryId;
}
================================================
FILE: src/main/java/com/mercadopago/serialization/Serializer.java
================================================
package com.mercadopago.serialization;
import static com.google.gson.stream.JsonToken.END_DOCUMENT;
import com.google.gson.FieldNamingPolicy;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonArray;
import com.google.gson.JsonDeserializer;
import com.google.gson.JsonElement;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import com.google.gson.JsonPrimitive;
import com.google.gson.JsonSerializer;
import com.google.gson.stream.JsonReader;
import com.google.gson.stream.JsonToken;
import com.google.gson.stream.MalformedJsonException;
import com.mercadopago.exceptions.MPJsonParseException;
import com.mercadopago.net.MPElementsResourcesPage;
import com.mercadopago.net.MPResource;
import com.mercadopago.net.MPResourceList;
import com.mercadopago.net.MPResultsResourcesPage;
import java.io.IOException;
import java.io.StringReader;
import java.lang.reflect.Type;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.List;
/**
* Central JSON serialization and deserialization utility for the MercadoPago Java SDK.
*
* This class wraps Google Gson and provides static helper methods to convert between
* Java objects (extending {@link MPResource}) and their JSON representations. Key behaviors:
* The JSON is first validated with {@link #isJsonValid(String)}, then converted
* using the pre-configured Gson instance (snake_case mapping, ISO 8601 dates).
*
* @param clazz the target class to deserialize into
* @param jsonObject the raw JSON string returned by the API
* @param This method handles API responses that return a top-level JSON array (as opposed
* to a paginated wrapper object). Each element of the array is deserialized independently
* and collected into the returned list.
*
* @param clazz the class of each element in the JSON array
* @param jsonObject the raw JSON array string (e.g., {@code [{"id":1}, {"id":2}]})
* @param Fields are converted to snake_case and dates are formatted as ISO 8601 strings
* per the SDK's Gson configuration.
*
* @param resource the object to serialize (typically an API request DTO)
* @param The method uses a streaming {@link JsonReader} to walk the entire token structure
* without materializing objects, making it efficient for large payloads. It returns
* {@code false} for malformed JSON and {@code true} for valid JSON objects, arrays,
* or primitive values.
*
* @param json the raw string to validate
* @return {@code true} if the string is valid JSON, {@code false} otherwise
* @throws IOException if an I/O error occurs while reading the string
*/
public static boolean isJsonValid(String json) throws IOException {
try {
JsonReader jsonReader = new JsonReader(new StringReader(json));
JsonToken token;
loop:
while ((token = jsonReader.peek()) != END_DOCUMENT && token != null) {
switch (token) {
case BEGIN_ARRAY:
jsonReader.beginArray();
break;
case END_ARRAY:
jsonReader.endArray();
break;
case BEGIN_OBJECT:
jsonReader.beginObject();
break;
case END_OBJECT:
jsonReader.endObject();
break;
case NAME:
jsonReader.nextName();
break;
case STRING:
case NUMBER:
case BOOLEAN:
case NULL:
jsonReader.skipValue();
break;
case END_DOCUMENT:
break loop;
default:
throw new AssertionError(token);
}
}
return true;
} catch (final MalformedJsonException ignored) {
return false;
}
}
}
================================================
FILE: src/main/java/com/mercadopago/webhook/WebhookSignatureValidator.java
================================================
package com.mercadopago.webhook;
import com.mercadopago.exceptions.MPInvalidWebhookSignatureException;
import com.mercadopago.exceptions.SignatureFailureReason;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Duration;
import java.time.Instant;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.function.Supplier;
import java.util.regex.Pattern;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
/**
* Verifies the authenticity of an incoming MercadoPago webhook notification by
* recomputing the HMAC-SHA256 signature locally and comparing it against the value
* carried in the {@code x-signature} header.
*
* This is a stateless, CPU-only utility. It performs no outbound HTTP calls and
* does not depend on {@link com.mercadopago.MercadoPagoConfig}; the integrator
* passes the secret signature explicitly on every call. The comparison is performed
* in constant time (via {@link MessageDigest#isEqual(byte[], byte[])}) to mitigate
* timing attacks.
*
* On failure, the validator throws {@link MPInvalidWebhookSignatureException}
* with a specific {@link SignatureFailureReason}. The integrator should respond with
* HTTP 401 to MercadoPago in all failure cases, log the request id for correlation,
* and not expose the failure reason in the HTTP response body.
*
* QR Code notifications are not signed by MercadoPago — do not call this
* validator for those events; they will always fail signature verification.
*/
public final class WebhookSignatureValidator {
private static final List{@code
* CardTokenClient client = new CardTokenClient();
* CardToken token = client.create(cardTokenRequest);
* // Use token.getId() when creating a payment
* }
*
* @see Card Tokens API reference
*/
public class CardTokenClient extends MercadoPagoClient {
/** Class-level logger for card token operations. */
private static final Logger LOGGER = Logger.getLogger(CardTokenClient.class.getName());
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public CardTokenClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code CardTokenClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public CardTokenClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Retrieves a card token by its unique identifier.
*
* @param id the unique identifier of the card token
* @return the requested {@link CardToken}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public CardToken get(String id) throws MPException, MPApiException {
return this.get(id, null);
}
/**
* Retrieves a card token by its unique identifier with custom request options.
*
* @param id the unique identifier of the card token
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link CardToken}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public CardToken get(String id, MPRequestOptions requestOptions)
throws MPException, MPApiException {
MPResponse response =
send(String.format("/v1/card_tokens/%s", id), HttpMethod.GET, null, null, requestOptions);
CardToken cardToken = Serializer.deserializeFromJson(CardToken.class, response.getContent());
cardToken.setResponse(response);
return cardToken;
}
/**
* Creates a new card token from card data.
*
* @param request the {@link CardTokenRequest} with card number, expiration, security code, and
* cardholder details
* @return the created {@link CardToken} containing the token identifier
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public CardToken create(CardTokenRequest request) throws MPException, MPApiException {
return this.create(request, null);
}
/**
* Creates a new card token from card data with custom request options.
*
* @param request the {@link CardTokenRequest} with card number, expiration, security code, and
* cardholder details
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the created {@link CardToken} containing the token identifier
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public CardToken create(CardTokenRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
MPResponse response =
send(
"/v1/card_tokens",
HttpMethod.POST,
Serializer.serializeToJson(request),
null,
requestOptions);
CardToken cardToken = Serializer.deserializeFromJson(CardToken.class, response.getContent());
cardToken.setResponse(response);
return cardToken;
}
}
================================================
FILE: src/main/java/com/mercadopago/client/cardtoken/CardTokenRequest.java
================================================
package com.mercadopago.client.cardtoken;
import lombok.Builder;
import lombok.Getter;
/**
* Request DTO used to create a card token for secure payment processing. Card tokens allow
* sensitive card data to be handled in a PCI-compliant manner by replacing actual card details
* with a temporary token that can be used in payment requests.
*
* @see Card Token API Reference
*/
@Builder
@Getter
public class CardTokenRequest {
/** Unique identifier of the saved card to be tokenized. */
private final String cardId;
/** Unique identifier of the customer who owns the card. */
private final String customerId;
/** Security code (CVV/CVC) printed on the card, required for token creation. */
private final String securityCode;
}
================================================
FILE: src/main/java/com/mercadopago/client/common/AddressRequest.java
================================================
package com.mercadopago.client.common;
import lombok.Getter;
import lombok.experimental.SuperBuilder;
/**
* Request DTO representing a physical address used across multiple Mercado Pago API resources such
* as payments, customers, and shipping. Serves as a reusable base for address-related requests.
*
* @see Mercado Pago API Reference
*/
@Getter
@SuperBuilder
public class AddressRequest {
/** Postal or ZIP code of the address (e.g., "01310-100"). */
private final String zipCode;
/** Name of the street (e.g., "Avenida Paulista"). */
private final String streetName;
/** Street number or house number (e.g., "1578"). */
private final String streetNumber;
/** Neighborhood or district name. */
private final String neighborhood;
/** City name (e.g., "Sao Paulo"). */
private final String city;
/** State or province name (e.g., "SP"). */
private final String state;
/** Additional address details such as suite or unit number. */
private final String complement;
/** Floor number in the building, if applicable. */
private final String floor;
}
================================================
FILE: src/main/java/com/mercadopago/client/common/IdentificationRequest.java
================================================
package com.mercadopago.client.common;
import lombok.Builder;
import lombok.Getter;
/**
* Request DTO representing a personal identification document used to identify payers,
* customers, and cardholders. The type and number vary by country (e.g., CPF in Brazil,
* DNI in Argentina, CC in Colombia).
*
* @see Mercado Pago API Reference
*/
@Getter
@Builder
public class IdentificationRequest {
/** Type of identification document (e.g., "CPF", "DNI", "CNPJ", "CC"). */
private final String type;
/** Identification document number. */
private final String number;
}
================================================
FILE: src/main/java/com/mercadopago/client/common/InvoicePeriod.java
================================================
package com.mercadopago.client.common;
import lombok.Builder;
import lombok.Getter;
/**
* Request DTO representing the billing period configuration for subscription invoices. Defines
* the frequency type and interval at which recurring charges are generated for a subscription plan.
*
* @see Subscriptions API Reference
*/
@Getter
@Builder
public class InvoicePeriod {
/** Frequency type of the billing period (e.g., "monthly", "daily"). */
private String type;
/** Number of frequency units between each billing cycle (e.g., 1 for every month). */
private Integer period;
}
================================================
FILE: src/main/java/com/mercadopago/client/common/PhoneRequest.java
================================================
package com.mercadopago.client.common;
import lombok.Builder;
import lombok.Getter;
/**
* Request DTO representing a phone number, split into area code and number. Used across multiple
* Mercado Pago API resources such as customers, payers, and shipping contacts.
*
* @see Mercado Pago API Reference
*/
@Getter
@Builder
public class PhoneRequest {
/** Telephone area code (e.g., "11" for Sao Paulo, "54" for Argentina). */
private final String areaCode;
/** Phone number without the area code. */
private final String number;
}
================================================
FILE: src/main/java/com/mercadopago/client/common/SubMerchant.java
================================================
package com.mercadopago.client.common;
import lombok.Builder;
import lombok.Getter;
/**
* Request DTO representing sub-merchant information for Payment Facilitator (PF) transactions.
* Required by card brands and regulators to identify the actual merchant in payment facilitator
* models, including details such as MCC, address, and tax identification.
*
* @see Mercado Pago API Reference
*/
@Getter
@Builder
public class SubMerchant {
/** Unique identifier code of the sub-merchant in the facilitator's system. */
private final String subMerchantId;
/** Merchant Category Code (MCC) per ABECS standards and/or primary CNAE classification. */
private final String mcc;
/** ISO 3166-1 country code where the sub-merchant is located (e.g., "BRA"). */
private final String country;
/** Street number of the sub-merchant's address. */
private final Integer addressDoorNumber;
/** Postal code (CEP) of the sub-merchant's address. */
private final String zip;
/** Tax identification number of the sub-merchant (CPF or CNPJ). */
private final String documentNumber;
/** City where the sub-merchant is located. */
private final String city;
/** Street name of the sub-merchant's address. */
private final String addressStreet;
/** Registered legal name of the sub-merchant. */
private final String legalName;
/** ISO code of the state or region where the sub-merchant is located. */
private final String regionCodeIso;
/** State or region code of the sub-merchant's address. */
private final String regionCode;
/** Type of tax identification document (e.g., "CPF", "CNPJ"). */
private final String documentType;
/** Phone number of the sub-merchant. */
private final String phone;
/** Website URL of the sub-merchant or payment facilitator. */
private final String url;
}
================================================
FILE: src/main/java/com/mercadopago/client/common/SubscriptionSequence.java
================================================
package com.mercadopago.client.common;
import lombok.Builder;
import lombok.Getter;
/**
* Request DTO representing the sequence tracking information for a recurring subscription payment.
* Indicates the current installment number and the total number of planned installments in the
* subscription lifecycle.
*
* @see Subscriptions API Reference
*/
@Getter
@Builder
public class SubscriptionSequence {
/** Current sequence number of this payment within the subscription (e.g., 3 of 12). */
private Integer number;
/** Total number of planned payments in the subscription series. */
private Integer total;
}
================================================
FILE: src/main/java/com/mercadopago/client/customer/CustomerAddressRequest.java
================================================
package com.mercadopago.client.customer;
import lombok.Builder;
import lombok.Getter;
/**
* Request DTO representing a customer's default address. Used when creating or updating
* a customer to specify their primary address information for shipping or billing purposes.
*
* @see Customers API Reference
*/
@Getter
@Builder
public class CustomerAddressRequest {
/** Unique identifier of an existing address to set as default. */
private final String id;
/** Postal or ZIP code of the address. */
private final String zipCode;
/** Name of the street. */
private final String streetName;
/** Street number or house number. */
private final Integer streetNumber;
}
================================================
FILE: src/main/java/com/mercadopago/client/customer/CustomerCardClient.java
================================================
package com.mercadopago.client.customer;
import static com.mercadopago.MercadoPagoConfig.getStreamHandler;
import com.google.gson.JsonObject;
import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.MercadoPagoClient;
import com.mercadopago.core.MPRequestOptions;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;
import com.mercadopago.net.HttpMethod;
import com.mercadopago.net.MPHttpClient;
import com.mercadopago.net.MPRequest;
import com.mercadopago.net.MPResourceList;
import com.mercadopago.net.MPResponse;
import com.mercadopago.resources.customer.CustomerCard;
import com.mercadopago.serialization.Serializer;
import java.util.logging.Logger;
import java.util.logging.StreamHandler;
/**
* Client for the MercadoPago Customer Cards API.
*
* {@code
* CustomerClient client = new CustomerClient();
* Customer customer = client.create(customerRequest);
* MPResourceList
*
* @see CustomerCardClient
* @see
* Customers API reference
*/
public class CustomerClient extends MercadoPagoClient {
/** Class-level logger for customer operations. */
private static final Logger LOGGER = Logger.getLogger(CustomerClient.class.getName());
/** Internal client used to perform card operations on behalf of this client. */
private final CustomerCardClient cardClient;
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public CustomerClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code CustomerClient} with a custom HTTP client.
*
* {@code
* IdentificationTypeClient client = new IdentificationTypeClient();
* MPResourceList
*
* @see
* Identification Types API reference
*/
public class IdentificationTypeClient extends MercadoPagoClient {
/** Class-level logger for identification type operations. */
private static final Logger LOGGER = Logger.getLogger(IdentificationTypeClient.class.getName());
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public IdentificationTypeClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs an {@code IdentificationTypeClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public IdentificationTypeClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Lists all available identification types for the authenticated user's country.
*
* @return an {@link MPResourceList} of {@link IdentificationType} (e.g., CPF, DNI, CURP)
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MPResourceList{@code
* MerchantOrderClient client = new MerchantOrderClient();
* MerchantOrder order = client.create(merchantOrderCreateRequest);
* MerchantOrder retrieved = client.get(order.getId());
* }
*
* @see
* Merchant Orders API reference
*/
public class MerchantOrderClient extends MercadoPagoClient {
/** Class-level logger for merchant order operations. */
private static final Logger LOGGER = Logger.getLogger(MerchantOrderClient.class.getName());
/** URL template for single-merchant-order endpoints (e.g. {@code /merchant_orders/{id}}). */
private static final String URL_WITH_ID = "/merchant_orders/%s";
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public MerchantOrderClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code MerchantOrderClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public MerchantOrderClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Retrieves a merchant order by its unique identifier.
*
* @param id the unique identifier of the merchant order
* @return the requested {@link MerchantOrder}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MerchantOrder get(Long id) throws MPException, MPApiException {
return this.get(id, null);
}
/**
* Retrieves a merchant order by its unique identifier with custom request options.
*
* @param id the unique identifier of the merchant order
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link MerchantOrder}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MerchantOrder get(Long id, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending get merchant order request");
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(URL_WITH_ID, id.toString()))
.method(HttpMethod.GET)
.build();
MPResponse response = send(mpRequest, requestOptions);
MerchantOrder result = deserializeFromJson(MerchantOrder.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Creates a new merchant order.
*
* @param request the {@link MerchantOrderCreateRequest} with order details (items, preference
* id, etc.)
* @return the created {@link MerchantOrder}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MerchantOrder create(MerchantOrderCreateRequest request)
throws MPException, MPApiException {
return this.create(request, null);
}
/**
* Creates a new merchant order with custom request options.
*
* @param request the {@link MerchantOrderCreateRequest} with order details (items, preference
* id, etc.)
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the created {@link MerchantOrder}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MerchantOrder create(MerchantOrderCreateRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending create merchant order request");
MPRequest mpRequest =
MPRequest.builder()
.uri("/merchant_orders")
.method(HttpMethod.POST)
.payload(Serializer.serializeToJson(request))
.build();
MPResponse response = send(mpRequest, requestOptions);
MerchantOrder result = deserializeFromJson(MerchantOrder.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Updates an existing merchant order.
*
* @param id the unique identifier of the merchant order to update
* @param request the {@link MerchantOrderUpdateRequest} with the updated attributes
* @return the updated {@link MerchantOrder}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MerchantOrder update(Long id, MerchantOrderUpdateRequest request)
throws MPException, MPApiException {
return this.update(id, request, null);
}
/**
* Updates an existing merchant order with custom request options.
*
* @param id the unique identifier of the merchant order to update
* @param request the {@link MerchantOrderUpdateRequest} with the updated attributes
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the updated {@link MerchantOrder}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MerchantOrder update(
Long id, MerchantOrderUpdateRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending update merchant order request");
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(URL_WITH_ID, id.toString()))
.method(HttpMethod.PUT)
.payload(Serializer.serializeToJson(request))
.build();
MPResponse response = send(mpRequest, requestOptions);
MerchantOrder result = deserializeFromJson(MerchantOrder.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Searches for merchant orders matching the specified criteria.
*
* @param request the {@link MPSearchRequest} containing search filters and pagination parameters
* @return an {@link MPElementsResourcesPage} of {@link MerchantOrder} with matching results and
* pagination metadata
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MPElementsResourcesPage{@code
* OauthClient client = new OauthClient();
* String authUrl = client.getAuthorizationURL(appId, redirectUri);
* // After user authorizes, exchange the code for credentials:
* CreateOauthCredential credential = client.createCredential(authorizationCode, redirectUri);
* }
*
* @see
* OAuth API reference
*/
public class OauthClient extends MercadoPagoClient {
/** Class-level logger for OAuth operations. */
private static final Logger LOGGER = Logger.getLogger(OauthClient.class.getName());
/** Internal client used to retrieve user information for building authorization URLs. */
private final UserClient userClient;
/** Base host for MercadoPago OAuth authorization endpoints. */
private final String authHost = "https://auth.mercadopago.com";
/** Relative path for the OAuth token endpoint. */
private final String path = "/oauth/token";
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public OauthClient() {
this(MercadoPagoConfig.getHttpClient());
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Constructs an {@code OauthClient} with a custom HTTP client.
*
* {@code
* OrderClient client = new OrderClient();
* Order order = client.create(orderCreateRequest);
* Order processed = client.process(order.getId());
* }
*
* @see Orders API
* reference
*/
public class OrderClient extends MercadoPagoClient {
/** Class-level logger for order operations. */
private static final Logger LOGGER = Logger.getLogger(OrderClient.class.getName());
/** URL template for single-order endpoints (e.g. {@code /v1/orders/{id}}). */
private static final String URL_WITH_ID = "/v1/orders/%s";
/** URL template for the order processing endpoint. */
private static final String URL_PROCESS = URL_WITH_ID + "/process";
/** URL template for creating transactions within an order. */
private static final String URL_TRANSACTION = URL_WITH_ID + "/transactions";
/** URL template for the order cancellation endpoint. */
private static final String URL_CANCEL = URL_WITH_ID + "/cancel";
/** URL template for the order capture endpoint. */
private static final String URL_CAPTURE = URL_WITH_ID + "/capture";
/** URL template for the order refund endpoint. */
private static final String URL_REFUND = URL_WITH_ID + "/refund";
/** URL template for a specific transaction within an order. */
private static final String URL_TRANSACTION_WITH_ID = URL_WITH_ID + "/transactions/%s";
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public OrderClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs an {@code OrderClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public OrderClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Creates a new order.
*
* @param request the {@link OrderCreateRequest} with the order details (items, payer, etc.)
* @return the created {@link Order}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Order create(OrderCreateRequest request) throws MPException, MPApiException {
return this.create(request, null);
}
/**
* Creates a new order with custom request options.
*
* @param request the {@link OrderCreateRequest} with the order details (items, payer, etc.)
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the created {@link Order}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Order create(OrderCreateRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending order creation request");
MPRequest mpRequest =
MPRequest.builder()
.uri("/v1/orders")
.method(HttpMethod.POST)
.payload(Serializer.serializeToJson(request))
.build();
MPResponse response = send(mpRequest, requestOptions);
Order result = deserializeFromJson(Order.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Retrieves an order by its unique identifier.
*
* @param id the unique identifier of the order
* @return the requested {@link Order}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Order get(String id) throws MPException, MPApiException {
return this.get(id, null);
}
/**
* Retrieves an order by its unique identifier with custom request options.
*
* @param id the unique identifier of the order
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link Order}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @throws IllegalArgumentException if {@code id} is blank or {@code null}
*/
public Order get(String id, MPRequestOptions requestOptions) throws MPException, MPApiException {
LOGGER.info("Sending order get request");
validateOrderID(id);
String url = String.format(URL_WITH_ID, id);
MPResponse response = send(url, HttpMethod.GET, null, null, requestOptions);
Order result = deserializeFromJson(Order.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Processes an order, triggering payment execution for its transactions.
*
* @param id the unique identifier of the order to process
* @return the processed {@link Order} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Order process(String id) throws MPException, MPApiException {
return this.process(id, null);
}
/**
* Processes an order with custom request options, triggering payment execution for its
* transactions.
*
* @param id the unique identifier of the order to process
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the processed {@link Order} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @throws IllegalArgumentException if {@code id} is blank or {@code null}
*/
public Order process(String id, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending order process request");
validateOrderID(id);
String url = String.format(URL_PROCESS, id);
MPResponse response = send(url, HttpMethod.POST, null, null, requestOptions);
Order result = deserializeFromJson(Order.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Creates a new transaction (payment) within an existing order.
*
* @param orderId the unique identifier of the order
* @param request the {@link OrderTransactionRequest} containing transaction/payment details
* @return the created {@link OrderTransaction}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public OrderTransaction createTransaction(String orderId, OrderTransactionRequest request)
throws MPException, MPApiException {
return this.createTransaction(orderId, request, null);
}
/**
* Creates a new transaction (payment) within an existing order with custom request options.
*
* @param orderId the unique identifier of the order
* @param request the {@link OrderTransactionRequest} containing transaction/payment details
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the created {@link OrderTransaction}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public OrderTransaction createTransaction(
String orderId, OrderTransactionRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending order transaction intent request");
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(URL_TRANSACTION, orderId))
.method(HttpMethod.POST)
.payload(Serializer.serializeToJson(request))
.build();
MPResponse response = send(mpRequest, requestOptions);
OrderTransaction result = deserializeFromJson(OrderTransaction.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Updates an existing transaction within an order.
*
* @param orderId the unique identifier of the order
* @param transactionId the unique identifier of the transaction to update
* @param request the {@link OrderPaymentRequest} containing the updated transaction details
* @return the updated {@link UpdateOrderTransaction}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public UpdateOrderTransaction updateTransaction(
String orderId, String transactionId, OrderPaymentRequest request)
throws MPException, MPApiException {
return this.updateTransaction(orderId, transactionId, request, null);
}
/**
* Updates an existing transaction within an order with custom request options.
*
* @param orderId the unique identifier of the order
* @param transactionId the unique identifier of the transaction to update
* @param request the {@link OrderPaymentRequest} containing the updated transaction details
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the updated {@link UpdateOrderTransaction}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @throws IllegalArgumentException if {@code orderId} or {@code transactionId} is blank or
* {@code null}
*/
public UpdateOrderTransaction updateTransaction(
String orderId,
String transactionId,
OrderPaymentRequest request,
MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending order transaction update request");
validateOrderID(orderId);
validateTransactionID(transactionId);
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(URL_TRANSACTION_WITH_ID, orderId, transactionId))
.method(HttpMethod.PUT)
.payload(Serializer.serializeToJson(request))
.build();
MPResponse response = send(mpRequest, requestOptions);
UpdateOrderTransaction result =
deserializeFromJson(UpdateOrderTransaction.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Cancels an order by its unique identifier.
*
* @param orderId the unique identifier of the order to cancel
* @return the cancelled {@link Order} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Order cancel(String orderId) throws MPException, MPApiException {
return this.cancel(orderId, null);
}
/**
* Cancels an order by its unique identifier with custom request options.
*
* @param orderId the unique identifier of the order to cancel
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the cancelled {@link Order} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @throws IllegalArgumentException if {@code orderId} is blank or {@code null}
*/
public Order cancel(String orderId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending order to delete");
validateOrderID(orderId);
String url = String.format(URL_CANCEL, orderId);
MPResponse response = send(url, HttpMethod.POST, null, null, requestOptions);
Order result = deserializeFromJson(Order.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Captures a previously authorized order, settling its payments.
*
* @param orderId the unique identifier of the order to capture
* @return the captured {@link Order} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Order capture(String orderId) throws MPException, MPApiException {
return this.capture(orderId, null);
}
/**
* Captures a previously authorized order with custom request options, settling its payments.
*
* @param orderId the unique identifier of the order to capture
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the captured {@link Order} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @throws IllegalArgumentException if {@code orderId} is blank or {@code null}
*/
public Order capture(String orderId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending order to capture");
validateOrderID(orderId);
String url = String.format(URL_CAPTURE, orderId);
MPResponse response = send(url, HttpMethod.POST, null, null, requestOptions);
Order result = deserializeFromJson(Order.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Deletes a transaction from an order.
*
* @param orderId the unique identifier of the order
* @param transactionId the unique identifier of the transaction to delete
* @return an {@link OrderTransaction} whose response holds the API result
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public OrderTransaction deleteTransaction(String orderId, String transactionId)
throws MPException, MPApiException {
return this.deleteTransaction(orderId, transactionId, null);
}
/**
* Deletes a transaction from an order with custom request options.
*
* @param orderId the unique identifier of the order
* @param transactionId the unique identifier of the transaction to delete
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return an {@link OrderTransaction} whose response holds the API result
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @throws IllegalArgumentException if {@code orderId} or {@code transactionId} is blank or
* {@code null}
*/
public OrderTransaction deleteTransaction(
String orderId, String transactionId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending order transaction delete request");
validateOrderID(orderId);
validateTransactionID(transactionId);
String url = String.format(URL_TRANSACTION_WITH_ID, orderId, transactionId);
MPResponse response = send(url, HttpMethod.DELETE, null, null, requestOptions);
OrderTransaction result = new OrderTransaction();
result.setResponse(response);
return result;
}
/**
* Creates a total refund for an order, refunding all transactions.
*
* @param orderId the unique identifier of the order to refund
* @return the refunded {@link Order} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Order refund(String orderId) throws MPException, MPApiException {
return this.refund(orderId, null, null);
}
/**
* Creates a total refund for an order with custom request options.
*
* @param orderId the unique identifier of the order to refund
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the refunded {@link Order} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Order refund(String orderId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
return this.refund(orderId, null, requestOptions);
}
/**
* Creates a partial refund for an order.
*
* @param orderId the unique identifier of the order to partially refund
* @param request the {@link OrderRefundRequest} containing the refund amount and details
* @return the refunded {@link Order} with updated status
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Order refund(String orderId, OrderRefundRequest request)
throws MPException, MPApiException {
return this.refund(orderId, request, null);
}
/**
* Creates a partial or total refund for an order with custom request options.
*
* {@code
* PaymentClient client = new PaymentClient();
* Payment payment = client.create(paymentCreateRequest);
* Payment captured = client.capture(payment.getId());
* PaymentRefund refund = client.refund(payment.getId());
* }
*
* @see PaymentRefundClient
* @see
* Payments API reference
*/
public class PaymentClient extends MercadoPagoClient {
/** Class-level logger for payment operations. */
private static final Logger LOGGER = Logger.getLogger(PaymentClient.class.getName());
/** URL template for single-payment endpoints (e.g. {@code /v1/payments/{id}}). */
private static final String URL_WITH_ID = "/v1/payments/%s";
/** Internal client used to perform refund operations on behalf of this client. */
private final PaymentRefundClient refundClient;
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public PaymentClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code PaymentClient} with a custom HTTP client.
*
* {@code
* PaymentMethodClient client = new PaymentMethodClient();
* MPResourceList
*
* @see
* Payment Methods API reference
*/
public class PaymentMethodClient extends MercadoPagoClient {
/** Class-level logger for payment method operations. */
private static final Logger LOGGER = Logger.getLogger(PaymentMethodClient.class.getName());
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public PaymentMethodClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code PaymentMethodClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public PaymentMethodClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Lists all available payment methods for the authenticated user's country.
*
* @return an {@link MPResourceList} of {@link PaymentMethod} (credit, debit, cash, etc.)
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MPResourceList{@code
* PointClient client = new PointClient();
* PointPaymentIntent intent = client.createPaymentIntent(deviceId, paymentIntentRequest);
* PointStatusPaymentIntent status = client.getPaymentIntentStatus(intent.getId());
* }
*
* @see
* Point Integration API reference
*/
public class PointClient extends MercadoPagoClient {
/** Class-level logger for Point operations. */
private static final Logger LOGGER = Logger.getLogger(PointClient.class.getName());
/** URL template for creating payment intents on a specific device. */
private static final String PAYMENT_INTENT_URL =
"/point/integration-api/devices/%s/payment-intents";
/** URL for listing payment intents with their final states. */
private static final String PAYMENT_INTENT_LIST_URL =
"/point/integration-api/payment-intents/events";
/** URL template for cancelling a specific payment intent on a device. */
private static final String PAYMENT_INTENT_DELETE_URL =
"point/integration-api/devices/%s/payment-intents/%s";
/** URL template for searching/retrieving a specific payment intent. */
private static final String PAYMENT_INTENT_SEARCH_URL =
"point/integration-api/payment-intents/%s";
/** URL template for retrieving the last status event of a payment intent. */
private static final String PAYMENT_INTENT_STATUS_URL =
"point/integration-api/payment-intents/%s/events";
/** URL for listing all Point devices. */
private static final String DEVICES_URL = "point/integration-api/devices";
/** URL template for operating on a specific device by its identifier. */
private static final String DEVICE_WITH_ID_URL = "point/integration-api/devices/%s";
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public PointClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code PointClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public PointClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Creates a payment intent on a specific Point device.
*
* @param deviceId the unique identifier of the Point device
* @param request the {@link PointPaymentIntentRequest} with amount, description, and payment
* details
* @return the created {@link PointPaymentIntent}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointPaymentIntent createPaymentIntent(String deviceId, PointPaymentIntentRequest request)
throws MPException, MPApiException {
return this.createPaymentIntent(deviceId, request, null);
}
/**
* Creates a payment intent on a specific Point device with custom request options.
*
* @param deviceId the unique identifier of the Point device
* @param request the {@link PointPaymentIntentRequest} with amount, description, and payment
* details
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the created {@link PointPaymentIntent}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointPaymentIntent createPaymentIntent(
String deviceId, PointPaymentIntentRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending create point payment intent request");
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(PAYMENT_INTENT_URL, deviceId))
.method(HttpMethod.POST)
.payload(Serializer.serializeToJson(request))
.build();
MPResponse response = send(mpRequest, requestOptions);
PointPaymentIntent result =
deserializeFromJson(PointPaymentIntent.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Retrieves a list of payment intents with their final states within a date range.
*
* @param request the {@link PointPaymentIntentListRequest} with start and end date filters
* @return a {@link PointPaymentIntentList} containing payment intents and their states
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointPaymentIntentList getPaymentIntentList(PointPaymentIntentListRequest request)
throws MPException, MPApiException {
return this.getPaymentIntentList(request, null);
}
/**
* Retrieves a list of payment intents with their final states within a date range with custom
* request options.
*
* @param request the {@link PointPaymentIntentListRequest} with start and end date filters
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return a {@link PointPaymentIntentList} containing payment intents and their states
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointPaymentIntentList getPaymentIntentList(
PointPaymentIntentListRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending get point payment intent list request");
MPRequest mpRequest =
MPRequest.builder()
.uri(PAYMENT_INTENT_LIST_URL)
.method(HttpMethod.GET)
.queryParams(request.getParams())
.build();
MPResponse response = send(mpRequest, requestOptions);
PointPaymentIntentList result =
deserializeFromJson(PointPaymentIntentList.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Cancels a payment intent on a specific Point device.
*
* @param deviceId the unique identifier of the Point device
* @param paymentIntentId the unique identifier of the payment intent to cancel
* @return a {@link PointCancelPaymentIntent} containing the cancelled payment intent identifier
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointCancelPaymentIntent cancelPaymentIntent(String deviceId, String paymentIntentId)
throws MPException, MPApiException {
return this.cancelPaymentIntent(deviceId, paymentIntentId, null);
}
/**
* Cancels a payment intent on a specific Point device with custom request options.
*
* @param deviceId the unique identifier of the Point device
* @param paymentIntentId the unique identifier of the payment intent to cancel
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return a {@link PointCancelPaymentIntent} containing the cancelled payment intent identifier
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointCancelPaymentIntent cancelPaymentIntent(
String deviceId, String paymentIntentId, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending cancel point payment intent request");
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(PAYMENT_INTENT_DELETE_URL, deviceId, paymentIntentId))
.method(HttpMethod.DELETE)
.build();
MPResponse response = send(mpRequest, requestOptions);
PointCancelPaymentIntent result =
deserializeFromJson(PointCancelPaymentIntent.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Retrieves a payment intent by its unique identifier.
*
* @param paymentIntentId the unique identifier of the payment intent
* @return the requested {@link PointSearchPaymentIntent}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointSearchPaymentIntent searchPaymentIntent(String paymentIntentId)
throws MPException, MPApiException {
return this.searchPaymentIntent(paymentIntentId, null);
}
/**
* Retrieves a payment intent by its unique identifier with custom request options.
*
* @param paymentIntentId the unique identifier of the payment intent
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link PointSearchPaymentIntent}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointSearchPaymentIntent searchPaymentIntent(
String paymentIntentId, MPRequestOptions requestOptions) throws MPException, MPApiException {
LOGGER.info("Sending search point payment intent request");
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(PAYMENT_INTENT_SEARCH_URL, paymentIntentId))
.method(HttpMethod.GET)
.build();
MPResponse response = send(mpRequest, requestOptions);
PointSearchPaymentIntent result =
deserializeFromJson(PointSearchPaymentIntent.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Retrieves the last status event for a payment intent.
*
* @param paymentIntentId the unique identifier of the payment intent
* @return the {@link PointStatusPaymentIntent} with the most recent status event
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointStatusPaymentIntent getPaymentIntentStatus(String paymentIntentId)
throws MPException, MPApiException {
return this.getPaymentIntentStatus(paymentIntentId, null);
}
/**
* Retrieves the last status event for a payment intent with custom request options.
*
* @param paymentIntentId the unique identifier of the payment intent
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link PointStatusPaymentIntent} with the most recent status event
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointStatusPaymentIntent getPaymentIntentStatus(
String paymentIntentId, MPRequestOptions requestOptions) throws MPException, MPApiException {
LOGGER.info("Sending get point payment intent status request");
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(PAYMENT_INTENT_STATUS_URL, paymentIntentId))
.method(HttpMethod.GET)
.build();
MPResponse response = send(mpRequest, requestOptions);
PointStatusPaymentIntent result =
deserializeFromJson(PointStatusPaymentIntent.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Retrieves Point devices, optionally filtered by POS and/or store.
*
* @param request the {@link MPSearchRequest} with optional POS or store filter parameters
* @return the {@link PointDevices} containing the list of devices
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointDevices getDevices(MPSearchRequest request) throws MPException, MPApiException {
return this.getDevices(request, null);
}
/**
* Retrieves Point devices with custom request options, optionally filtered by POS and/or store.
*
* @param request the {@link MPSearchRequest} with optional POS or store filter parameters
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the {@link PointDevices} containing the list of devices
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointDevices getDevices(MPSearchRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending get point devices request");
MPRequest mpRequest =
MPRequest.builder()
.uri(DEVICES_URL)
.method(HttpMethod.GET)
.queryParams(request.getParameters())
.build();
MPResponse response = send(mpRequest, requestOptions);
PointDevices result = deserializeFromJson(PointDevices.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Changes the operating mode of a Point device (e.g., PDV or standalone).
*
* @param deviceId the unique identifier of the Point device
* @param request the {@link PointDeviceOperatingModeRequest} with the desired operating mode
* @return the updated {@link PointDeviceOperatingMode}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointDeviceOperatingMode changeDeviceOperatingMode(
String deviceId, PointDeviceOperatingModeRequest request) throws MPException, MPApiException {
return this.changeDeviceOperatingMode(deviceId, request, null);
}
/**
* Changes the operating mode of a Point device with custom request options.
*
* @param deviceId the unique identifier of the Point device
* @param request the {@link PointDeviceOperatingModeRequest} with the desired operating mode
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the updated {@link PointDeviceOperatingMode}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public PointDeviceOperatingMode changeDeviceOperatingMode(
String deviceId, PointDeviceOperatingModeRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending change point device operating mode request");
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(DEVICE_WITH_ID_URL, deviceId))
.method(HttpMethod.PATCH)
.payload(Serializer.serializeToJson(request))
.build();
MPResponse response = send(mpRequest, requestOptions);
PointDeviceOperatingMode result =
deserializeFromJson(PointDeviceOperatingMode.class, response.getContent());
result.setResponse(response);
return result;
}
}
================================================
FILE: src/main/java/com/mercadopago/client/point/PointDeviceOperatingModeRequest.java
================================================
package com.mercadopago.client.point;
import lombok.Builder;
import lombok.Getter;
/**
* Request object to change the operating mode of a MercadoPago Point device.
*
* @see com.mercadopago.client.point.OperatingMode
* @see com.mercadopago.client.point.PointClient
*/
@Getter
@Builder
public class PointDeviceOperatingModeRequest {
/** Operating mode to set on the device (PDV or STANDALONE). */
private final OperatingMode operatingMode;
}
================================================
FILE: src/main/java/com/mercadopago/client/point/PointPaymentIntentAdditionalInfoRequest.java
================================================
package com.mercadopago.client.point;
import lombok.Builder;
import lombok.Getter;
/**
* Additional information for a Point payment intent, including external references and printing
* options.
*
* @see com.mercadopago.client.point.PointPaymentIntentRequest
*/
@Getter
@Builder
public class PointPaymentIntentAdditionalInfoRequest {
/** Alphanumeric identifier from your application, returned in the Webhook notification. */
private final String externalReference;
/** Whether to print the ticket on the Point device. */
private final Boolean printOnTerminal;
/** Alphanumeric invoice or ticket number, printed on the device ticket. */
private final String ticketNumber;
}
================================================
FILE: src/main/java/com/mercadopago/client/point/PointPaymentIntentListRequest.java
================================================
package com.mercadopago.client.point;
import java.time.LocalDate;
import java.util.HashMap;
import java.util.Map;
import lombok.Builder;
import lombok.Getter;
/**
* Request object to filter the list of Point payment intents by date range.
*
* @see com.mercadopago.client.point.PointClient
*/
@Getter
@Builder
public class PointPaymentIntentListRequest {
/** Start date for filtering payment intents. */
private final LocalDate startDate;
/** End date for filtering payment intents. */
private final LocalDate endDate;
/**
* Method responsible for mapping data range.
*
* @return map with data range.
*/
public Map{@code
* PreapprovalClient client = new PreapprovalClient();
* Preapproval subscription = client.create(preapprovalCreateRequest);
* Preapproval updated = client.update(subscription.getId(), preapprovalUpdateRequest);
* }
*
* @see
* Subscriptions API reference
*/
public class PreapprovalClient extends MercadoPagoClient {
/** Class-level logger for preapproval/subscription operations. */
private static final Logger LOGGER = Logger.getLogger(PreapprovalClient.class.getName());
/** URL template for single-preapproval endpoints (e.g. {@code /preapproval/{id}}). */
private static final String URL_WITH_ID = "/preapproval/%s";
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public PreapprovalClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code PreapprovalClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public PreapprovalClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Retrieves a preapproval (subscription) by its unique identifier.
*
* @param id the unique identifier of the preapproval
* @return the requested {@link Preapproval}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Preapproval get(String id) throws MPException, MPApiException {
return this.get(id, null);
}
/**
* Retrieves a preapproval (subscription) by its unique identifier with custom request options.
*
* @param id the unique identifier of the preapproval
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link Preapproval}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Preapproval get(String id, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending get preapproval request");
MPResponse response =
send(String.format(URL_WITH_ID, id), HttpMethod.GET, null, null, requestOptions);
Preapproval result = deserializeFromJson(Preapproval.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Creates a new preapproval (subscription).
*
* @param request the {@link PreapprovalCreateRequest} with subscription details (reason, amount,
* frequency, etc.)
* @return the created {@link Preapproval}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Preapproval create(PreapprovalCreateRequest request) throws MPException, MPApiException {
return this.create(request, null);
}
/**
* Creates a new preapproval (subscription) with custom request options.
*
* @param request the {@link PreapprovalCreateRequest} with subscription details (reason, amount,
* frequency, etc.)
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the created {@link Preapproval}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Preapproval create(PreapprovalCreateRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending create preapproval request");
MPResponse response =
send("/preapproval", HttpMethod.POST, serializeToJson(request), null, requestOptions);
Preapproval result = deserializeFromJson(Preapproval.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Updates an existing preapproval (subscription).
*
* @param id the unique identifier of the preapproval to update
* @param request the {@link PreapprovalUpdateRequest} with the updated subscription attributes
* @return the updated {@link Preapproval}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Preapproval update(String id, PreapprovalUpdateRequest request)
throws MPException, MPApiException {
return this.update(id, request, null);
}
/**
* Updates an existing preapproval (subscription) with custom request options.
*
* @param id the unique identifier of the preapproval to update
* @param request the {@link PreapprovalUpdateRequest} with the updated subscription attributes
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the updated {@link Preapproval}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public Preapproval update(
String id, PreapprovalUpdateRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending update preapproval request");
MPResponse response =
send(
String.format(URL_WITH_ID, id),
HttpMethod.PUT,
serializeToJson(request),
null,
requestOptions);
Preapproval result = deserializeFromJson(Preapproval.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Searches for preapprovals (subscriptions) matching the specified criteria.
*
* @param request the {@link MPSearchRequest} containing search filters and pagination parameters
* @return an {@link MPResultsResourcesPage} of {@link Preapproval} with matching results and
* pagination metadata
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public MPResultsResourcesPage{@code
* PreferenceClient client = new PreferenceClient();
* Preference preference = client.create(preferenceRequest);
* String initPoint = preference.getInitPoint();
* }
*
* @see
* Checkout Preferences API reference
*/
public class PreferenceClient extends MercadoPagoClient {
/** Class-level logger for preference operations. */
private static final Logger LOGGER = Logger.getLogger(PreferenceClient.class.getName());
/** URL template for single-preference endpoints (e.g. {@code /checkout/preferences/{id}}). */
private static final String URL_WITH_ID = "/checkout/preferences/%s";
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public PreferenceClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code PreferenceClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public PreferenceClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Retrieves a checkout preference by its unique identifier.
*
* @param id the unique identifier of the preference
* @return the requested {@link Preference}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Preference get(String id) throws MPException, MPApiException {
return this.get(id, null);
}
/**
* Retrieves a checkout preference by its unique identifier with custom request options.
*
* @param id the unique identifier of the preference
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the requested {@link Preference}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Preference get(String id, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending get preference request");
MPResponse response =
send(String.format(URL_WITH_ID, id), HttpMethod.GET, null, null, requestOptions);
Preference result = deserializeFromJson(Preference.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Creates a new checkout preference.
*
* @param request the {@link PreferenceRequest} with items, payer info, payment methods, and
* other preference attributes
* @return the created {@link Preference} including its {@code initPoint} URL
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Preference create(PreferenceRequest request) throws MPException, MPApiException {
return this.create(request, null);
}
/**
* Creates a new checkout preference with custom request options.
*
* @param request the {@link PreferenceRequest} with items, payer info, payment methods, and
* other preference attributes
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the created {@link Preference} including its {@code initPoint} URL
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Preference create(PreferenceRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending create preference request");
MPRequest mpRequest =
MPRequest.builder()
.uri("/checkout/preferences")
.method(HttpMethod.POST)
.payload(Serializer.serializeToJson(request))
.build();
MPResponse response = send(mpRequest, requestOptions);
Preference result = deserializeFromJson(Preference.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Updates an existing checkout preference.
*
* @param id the unique identifier of the preference to update
* @param request the {@link PreferenceRequest} with the updated preference attributes
* @return the updated {@link Preference}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Preference update(String id, PreferenceRequest request)
throws MPException, MPApiException {
return this.update(id, request, null);
}
/**
* Updates an existing checkout preference with custom request options.
*
* @param id the unique identifier of the preference to update
* @param request the {@link PreferenceRequest} with the updated preference attributes
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the updated {@link Preference}
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public Preference update(String id, PreferenceRequest request, MPRequestOptions requestOptions)
throws MPException, MPApiException {
LOGGER.info("Sending update preference request");
MPRequest mpRequest =
MPRequest.builder()
.uri(String.format(URL_WITH_ID, id))
.method(HttpMethod.PUT)
.payload(Serializer.serializeToJson(request))
.build();
MPResponse response = send(mpRequest, requestOptions);
Preference result = deserializeFromJson(Preference.class, response.getContent());
result.setResponse(response);
return result;
}
/**
* Searches for checkout preferences matching the specified criteria.
*
* @param request the {@link MPSearchRequest} containing search filters and pagination parameters
* @return an {@link MPElementsResourcesPage} of {@link PreferenceSearch} with matching results
* and pagination metadata
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
* @see api
* docs
*/
public MPElementsResourcesPage{@code
* UserClient client = new UserClient();
* User user = client.get();
* String country = user.getCountryId();
* }
*/
public class UserClient extends MercadoPagoClient {
/** Class-level logger for user operations. */
private static final Logger LOGGER = Logger.getLogger(UserClient.class.getName());
/**
* Default constructor. Uses the default HTTP client provided by {@link MercadoPagoConfig}.
*/
public UserClient() {
this(MercadoPagoConfig.getHttpClient());
}
/**
* Constructs a {@code UserClient} with a custom HTTP client.
*
* @param httpClient the {@link MPHttpClient} implementation used to execute HTTP requests
*/
public UserClient(MPHttpClient httpClient) {
super(httpClient);
StreamHandler streamHandler = getStreamHandler();
streamHandler.setLevel(MercadoPagoConfig.getLoggingLevel());
LOGGER.addHandler(streamHandler);
LOGGER.setLevel(MercadoPagoConfig.getLoggingLevel());
}
/**
* Retrieves information about the currently authenticated user.
*
* @return the authenticated {@link User} with account details and country information
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public User get() throws MPException, MPApiException {
return this.get(null);
}
/**
* Retrieves information about the currently authenticated user with custom request options.
*
* @param requestOptions optional {@link MPRequestOptions} to override access token, headers, or
* timeouts for this single request; may be {@code null}
* @return the authenticated {@link User} with account details and country information
* @throws MPException if a transport-level or SDK-internal error occurs
* @throws MPApiException if the API returns a non-successful HTTP status code
*/
public User get(MPRequestOptions requestOptions) throws MPException, MPApiException {
LOGGER.info("Sending get user request");
MPResponse response = send("/users/me", HttpMethod.GET, null, null, requestOptions);
User user = Serializer.deserializeFromJson(User.class, response.getContent());
user.setResponse(response);
return user;
}
}
================================================
FILE: src/main/java/com/mercadopago/core/MPRequestOptions.java
================================================
package com.mercadopago.core;
import java.util.Map;
import lombok.Builder;
import lombok.Data;
/**
* Per-request configuration overrides for MercadoPago API calls.
*
* {@code
* MPRequestOptions options = MPRequestOptions.builder()
* .accessToken("APP_USR-...")
* .connectionTimeout(5000)
* .customHeaders(Map.of("X-Idempotency-Key", uuid))
* .build();
* }
*
* @see com.mercadopago.MercadoPagoConfig
*/
@Data
@Builder
public class MPRequestOptions {
/** OAuth access token for this specific request, overriding the global token when set. */
private String accessToken;
/** HTTP connection timeout in milliseconds for this request. A value of {@code 0} uses the global default. */
private int connectionTimeout;
/** Timeout in milliseconds for obtaining a connection from the pool. A value of {@code 0} uses the global default. */
private int connectionRequestTimeout;
/** Socket (read) timeout in milliseconds for this request. A value of {@code 0} uses the global default. */
private int socketTimeout;
/** Additional HTTP headers to include in this request (e.g., idempotency keys, custom tracing headers). */
private Map
*
*
*
* Bancolombia ........... 1007
* Davivienda ............ 1051
* Banco de Bogotá ....... 1001
* BBVA Colombia ......... 1013
* Banco Popular ......... 1002
* Scotiabank Colpatria .. 1019
*
*
* @see Documentación oficial PSE
*/
public class CreateOrderPSE {
public static void main(String[] args) {
MercadoPagoConfig.setAccessToken("{{ACCESS_TOKEN}}");
OrderClient client = new OrderClient();
// PSE payment: id="pse", type="bank_transfer", financial_institution = bank code.
OrderPaymentRequest payment = OrderPaymentRequest.builder()
.amount("50000.00")
.paymentMethod(OrderPaymentMethodRequest.builder()
.id("pse")
.type("bank_transfer")
.financialInstitution("1007") // Bancolombia
.build())
.build();
List{@code
* try {
* Payment payment = client.create(request);
* } catch (MPApiException e) {
* System.out.println("Status: " + e.getStatusCode());
* System.out.println("Response: " + e.getApiResponse().getContent());
* }
* }
*
* @see MPException
* @see com.mercadopago.net.MPResponse
*/
@Getter
public class MPApiException extends Exception {
/** HTTP status code returned by the MercadoPago API (e.g., 400, 401, 404, 500). */
private final int statusCode;
/** Full API response including headers, status code, and body content. */
private final MPResponse apiResponse;
/**
* Constructs a new API exception with the specified message and response.
*
* @param message a human-readable description of the API error
* @param response the full {@link MPResponse} received from the API
*/
public MPApiException(String message, MPResponse response) {
this(message, null, response);
}
/**
* Constructs a new API exception with the specified message, underlying cause, and response.
*
* @param message a human-readable description of the API error
* @param cause the underlying throwable that triggered this exception, or {@code null}
* @param response the full {@link MPResponse} received from the API
*/
public MPApiException(String message, Throwable cause, MPResponse response) {
super(message, cause);
this.apiResponse = response;
this.statusCode = response.getStatusCode();
}
}
================================================
FILE: src/main/java/com/mercadopago/exceptions/MPException.java
================================================
package com.mercadopago.exceptions;
import lombok.Getter;
/**
* Base checked exception for SDK-side errors in the MercadoPago Java SDK.
*
*
*
*
* @see MPApiException
* @see MPJsonParseException
* @see MPMalformedRequestException
*/
@Getter
public class MPException extends Exception {
/**
* Constructs a new SDK exception with the specified detail message.
*
* @param message a human-readable description of the error
*/
public MPException(String message) {
super(message);
}
/**
* Constructs a new SDK exception with the specified detail message and underlying cause.
*
* @param message a human-readable description of the error
* @param cause the underlying throwable that triggered this exception
*/
public MPException(String message, Throwable cause) {
super(message, cause);
}
/**
* Constructs a new SDK exception wrapping an underlying cause.
*
* @param cause the underlying throwable that triggered this exception
*/
public MPException(Throwable cause) {
super(cause);
}
}
================================================
FILE: src/main/java/com/mercadopago/exceptions/MPInvalidWebhookSignatureException.java
================================================
package com.mercadopago.exceptions;
import lombok.Getter;
/**
* Exception thrown by {@link com.mercadopago.webhook.WebhookSignatureValidator}
* when a webhook notification cannot be confirmed as originating from MercadoPago.
*
*
*
*
* @see MPDefaultHttpClient
*/
public class KeepAliveStrategy implements ConnectionKeepAliveStrategy {
/**
* Default keep-alive timeout in milliseconds used when the server does not specify a
* {@code Keep-Alive} header with a {@code timeout} parameter. Value: {@value} ms (10 seconds).
*/
private static final int DEFAULT_KEEP_ALIVE_TIMEOUT_MS = 10000;
/** The name of the parameter to look for in the {@code Keep-Alive} header. */
private static final String KEEP_ALIVE_TIMEOUT_PARAM_NAME = "timeout";
/**
* Determines how long a connection may remain idle before being closed.
*
*
*
*
*
*
*
* @param mpRequest the {@link MPRequest} to send
* @return an {@link MPResponse} with status code, headers, and body
* @throws MPException if an unexpected transport-level error occurs
* @throws MPApiException if the API returns a non-success status code (greater than 299)
*/
@Override
public MPResponse send(MPRequest mpRequest) throws MPException, MPApiException {
try {
HttpRequestBase completeRequest = createHttpRequest(mpRequest);
HttpClientContext context = HttpClientContext.create();
HttpResponse response = executeHttpRequest(mpRequest, completeRequest, context);
String responseBody = "";
if (Objects.nonNull(response.getEntity())) {
responseBody = EntityUtils.toString(response.getEntity(), UTF_8);
}
Map{@code
* MPSearchRequest searchRequest = MPSearchRequest.builder()
* .limit(10)
* .offset(0)
* .filters(Map.of("status", "approved"))
* .build();
* }
*
*
*
*
* @see MPRequest
* @see com.mercadopago.MercadoPagoConfig#BASE_URL
*/
public class UrlFormatter {
/**
* Formats a request URL by prepending the MercadoPago base URL (when the path is relative)
* and appending URL-encoded query parameters.
*
*
*
*
* @see com.mercadopago.net.MPResultsResourcesPage
* @see com.mercadopago.net.MPSearchRequest
*/
@Getter
public class ResultsPaging {
/**
* The total number of items that match the search criteria across all pages. This value
* remains constant regardless of the current page.
*/
private int total;
/**
* The maximum number of items returned in a single page of results. Corresponds to the
* {@code limit} query parameter sent in the original request.
*/
private int limit;
/**
* The zero-based offset of the first item in the current page within the full result set.
* Corresponds to the {@code offset} query parameter sent in the original request.
*/
private int offset;
}
================================================
FILE: src/main/java/com/mercadopago/resources/common/Address.java
================================================
package com.mercadopago.resources.common;
import lombok.Getter;
/**
* Represents a generic physical address used across the MercadoPago API.
*
*
*
*
* @see PointDeviceOperatingMode
*/
public enum OperatingMode {
/** Device is integrated with an external point-of-sale (PDV) system. */
PDV,
/** Device operates independently without external system integration. */
STANDALONE
}
================================================
FILE: src/main/java/com/mercadopago/resources/point/PointCancelPaymentIntent.java
================================================
package com.mercadopago.resources.point;
import com.mercadopago.net.MPResource;
import lombok.Getter;
/**
* Resource representing the result of cancelling a payment intent on a Point device.
*
*
*
*
* @see MPResource
* @see MPJsonParseException
*/
public class Serializer {
/**
* ISO 8601 extended date-time formatter for deserialization.
* Pattern: {@code yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX][XX][X]} -- supports optional
* milliseconds and various offset formats.
*/
private static final DateTimeFormatter DESERIALIZE_DATE_FORMAT_ISO8601_EXTENDED =
DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX][XX][X]");
/**
* ISO 8601 basic (compact) date-time formatter for deserialization.
* Pattern: {@code yyyyMMdd'T'HHmmss[.SSS][XXX][XX][X]} -- no hyphens or colons in
* the date/time portion.
*/
private static final DateTimeFormatter DESERIALIZE_DATE_FORMAT_ISO8601_BASIC =
DateTimeFormatter.ofPattern("yyyyMMdd'T'HHmmss[.SSS][XXX][XX][X]");
/**
* Ordered array of date-time formatters tried during deserialization. The first
* formatter that successfully parses the input wins. Order:
* {@link DateTimeFormatter#ISO_DATE_TIME}, extended ISO 8601, basic ISO 8601.
*/
private static final DateTimeFormatter[] ISO8601_DATETIME_FORMATTERS =
new DateTimeFormatter[] {
DateTimeFormatter.ISO_DATE_TIME,
DESERIALIZE_DATE_FORMAT_ISO8601_EXTENDED,
DESERIALIZE_DATE_FORMAT_ISO8601_BASIC,
};
/**
* ISO 8601 date-time pattern used for serialization of {@link OffsetDateTime}
* values. Always includes milliseconds and a full timezone offset
* (e.g., {@code 2023-10-15T14:30:00.000-03:00}).
*/
private static final String SERIALIZE_DATE_FORMAT_ISO8601 = "yyyy-MM-dd'T'HH:mm:ss.SSSXXX";
/**
* Attempts to parse a JSON element as an {@link OffsetDateTime} by trying each formatter
* in {@link #ISO8601_DATETIME_FORMATTERS} in order.
*
* @param json the JSON element containing a date-time string
* @return the parsed {@link OffsetDateTime}, or {@code null} if the element is null/empty
* @throws DateTimeParseException if none of the known formatters can parse the value
*/
private static OffsetDateTime parseDateTime(JsonElement json) {
if (json == null || json.getAsString().isEmpty()) {
return null;
}
for (int i = 0; i < ISO8601_DATETIME_FORMATTERS.length; i++) {
try {
return OffsetDateTime.parse(json.getAsString(), ISO8601_DATETIME_FORMATTERS[i]);
} catch (DateTimeParseException e) {
// try all formatters, if none works, throw exception from last one
if (i == ISO8601_DATETIME_FORMATTERS.length - 1) {
throw e;
}
}
}
return null;
}
/**
* Pre-configured Gson instance shared by all serialization methods. Configured with:
*
*
*/
private static final Gson GSON =
new GsonBuilder()
.registerTypeAdapter(
OffsetDateTime.class,
(JsonDeserializer