Skip to main content

Documentation Index

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

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

MercadoPagoConfig is the central, static, thread-safe configuration class for the Mercado Pago Java SDK. All of its fields are declared volatile (or synchronized where necessary), so a single call during application startup propagates consistently across all threads. Every API resource class in the SDK reads from this global configuration at request time, meaning you only need to configure the SDK once — typically at application bootstrap — before making any API calls. Per-request overrides (for example, a different access token per merchant in a marketplace) can be specified through MPRequestOptions. Any field left at its zero or null default in that object automatically falls back to the values set here. Package: com.mercadopago

​
SDK Constants

The following constants are defined as public static final fields and cannot be changed at runtime.
ConstantValueDescription
CURRENT_VERSION"3.3.0"SDK version string, included in every API request’s tracking header.
BASE_URL"https://api.mercadopago.com"Root URL for all Mercado Pago REST API endpoints.
PRODUCT_ID"BC32A7VTRPP001U8NHJ0"Internal analytics identifier sent as a header on every request.
TRACKING_ID"platform:<javaVersion>,type:SDK<version>,so;"Composite tracking header built from getJavaVersion() and CURRENT_VERSION.

​
Configuration Properties

All properties are read and written through static getter/setter methods generated by Lombok. Call the setter once at startup; getters are used internally by the SDK on every request.
​
accessToken
String
required
OAuth 2.0 access token used to authenticate every API request. This is the only required configuration field. Obtain your token from the Mercado Pago Developer Dashboard.
MercadoPagoConfig.setAccessToken("APP_USR-0000000000000000-000000-00000000000000000000000000000000-000000000");
​
platformId
String
Optional platform identifier forwarded as an HTTP header (x-platform-id) on every request. Use this when your application is a platform that processes transactions on behalf of multiple sellers.
MercadoPagoConfig.setPlatformId("your-platform-id");
​
corporationId
String
Optional corporation identifier forwarded as an HTTP header (x-corporation-id). Used for multi-entity or enterprise account setups to attribute requests to a specific legal entity.
MercadoPagoConfig.setCorporationId("your-corporation-id");
​
integratorId
String
Optional integrator identifier forwarded as an HTTP header (x-integrator-id). Identifies the technology partner or integration agency responsible for the integration.
MercadoPagoConfig.setIntegratorId("your-integrator-id");
​
loggingLevel
java.util.logging.Level
default:"Level.OFF"
Controls the verbosity of the SDK’s internal logger. The default value Level.OFF disables all SDK log output. Set to Level.FINE or Level.INFO to enable diagnostic logging during development.Available levels (most to least verbose): Level.ALL, Level.FINEST, Level.FINER, Level.FINE, Level.CONFIG, Level.INFO, Level.WARNING, Level.SEVERE, Level.OFF.
import java.util.logging.Level;

MercadoPagoConfig.setLoggingLevel(Level.INFO);
​
loggingHandler
java.util.logging.StreamHandler
Custom log handler for SDK output. When null (the default), the SDK creates a new ConsoleHandler that writes to System.err. Supply your own StreamHandler (or a subclass such as FileHandler) to redirect log output to a file or another sink.See getStreamHandler() for the lazy-initialization behavior.
import java.util.logging.FileHandler;

FileHandler fileHandler = new FileHandler("/var/log/mercadopago-sdk.log", true);
MercadoPagoConfig.setLoggingHandler(fileHandler);
​
metricsScope
String
default:"\"prod\""
Scope label included when the SDK reports internal metrics back to Mercado Pago infrastructure. The default value "prod" indicates production traffic. Change to "sandbox" or a custom label only if instructed by Mercado Pago support.
MercadoPagoConfig.setMetricsScope("prod");
​
maxConnections
int
default:"10"
Maximum number of concurrent HTTP connections maintained in the SDK’s connection pool. Increase this value for high-throughput applications that issue many parallel API calls. The pool is created lazily the first time getHttpClient() is called.
MercadoPagoConfig.setMaxConnections(50);
​
connectionTimeout
int (milliseconds)
default:"20000"
Maximum time in milliseconds the SDK will wait while establishing a new TCP connection to the Mercado Pago API. A value of 0 means indefinitely. Throws ConnectTimeoutException when exceeded.
MercadoPagoConfig.setConnectionTimeout(5000); // 5 seconds
​
connectionRequestTimeout
int (milliseconds)
default:"20000"
Maximum time in milliseconds the SDK will wait to acquire an existing connection from the connection pool. This timeout is relevant under high concurrency when all pooled connections are in use. Throws ConnectionPoolTimeoutException when exceeded.
MercadoPagoConfig.setConnectionRequestTimeout(5000);
​
socketTimeout
int (milliseconds)
default:"20000"
Maximum time in milliseconds the SDK will wait for data to arrive on an open socket (i.e., time between consecutive TCP packets during the response body transfer). A value of 0 means indefinitely. Throws SocketTimeoutException when exceeded.
MercadoPagoConfig.setSocketTimeout(10000); // 10 seconds
​
httpClient
com.mercadopago.net.MPHttpClient
Custom HTTP client implementation that replaces the built-in MPDefaultHttpClient. Implement the MPHttpClient interface to use a different HTTP library, add request/response interceptors, or integrate with your application’s existing HTTP infrastructure. Must be set before the first API call is made.
MPHttpClient myClient = new MyCustomHttpClient();
MercadoPagoConfig.setHttpClient(myClient);
​
proxy
org.apache.http.HttpHost
HTTP proxy host through which all SDK requests are routed. When null (the default), requests go directly to BASE_URL. The getter and setter for this field are @Synchronized to prevent partial reads during concurrent updates.
import org.apache.http.HttpHost;

MercadoPagoConfig.setProxy(new HttpHost("proxy.example.com", 8080, "http"));
​
retryHandler
org.apache.http.client.HttpRequestRetryHandler
Custom retry handler that overrides the default Apache HTTP client retry strategy. When set, the underlying CloseableHttpClient delegates all retry decisions to this handler. Useful for implementing exponential backoff or disabling retries entirely.
import org.apache.http.client.HttpRequestRetryHandler;

HttpRequestRetryHandler noRetry = (exception, executionCount, context) -> false;
MercadoPagoConfig.setRetryHandler(noRetry);

​
Methods

​
getHttpClient()

public static synchronized MPHttpClient getHttpClient()
Returns the MPHttpClient instance used for all API communication. On the first call, if no custom client has been set via setHttpClient(), a new MPDefaultHttpClient is instantiated using the current pool and timeout settings. Subsequent calls return the same instance (singleton).
​
return
com.mercadopago.net.MPHttpClient
The active HTTP client — either the custom implementation set via setHttpClient(), or a lazily created MPDefaultHttpClient. Never null.
Set a custom client with MercadoPagoConfig.setHttpClient(myClient) before the first API call. Once getHttpClient() has been called internally, the default client has already been instantiated and changing pool/timeout settings alone will have no effect on it.

​
getStreamHandler()

public static StreamHandler getStreamHandler()
Returns the active StreamHandler for SDK logging. If a custom handler has been configured via setLoggingHandler(), that handler is returned. Otherwise, a new ConsoleHandler (writing to System.err) is created and returned each time.
​
return
java.util.logging.StreamHandler
The configured StreamHandler, or a freshly constructed ConsoleHandler if none has been set.

​
getJavaVersion()

public static synchronized String getJavaVersion()
Returns the Java runtime version formatted as "major|full". For example, on Java 11.0.12+7 this returns "11|11.0.12+7". This value is embedded in the TRACKING_ID constant that is sent as a header on every API request so the Mercado Pago platform can identify the client environment.
​
return
String
A string in the format "majorVersion|fullVersion", or null if the java.runtime.version system property is unavailable.

​
Code Examples

​
Minimal production setup

import com.mercadopago.MercadoPagoConfig;

// Required: set your OAuth access token once at application startup
MercadoPagoConfig.setAccessToken("APP_USR-0000000000000000-000000-00000000000000000000000000000000-000000000");

​
Fine-tuned timeouts and connection pool

import com.mercadopago.MercadoPagoConfig;

MercadoPagoConfig.setAccessToken("APP_USR-...");

// Allow up to 50 concurrent connections
MercadoPagoConfig.setMaxConnections(50);

// 5-second connect and pool-acquire timeouts; 15-second socket timeout
MercadoPagoConfig.setConnectionTimeout(5000);
MercadoPagoConfig.setConnectionRequestTimeout(5000);
MercadoPagoConfig.setSocketTimeout(15000);

​
Enable debug logging to a file

import com.mercadopago.MercadoPagoConfig;
import java.util.logging.FileHandler;
import java.util.logging.Level;
import java.util.logging.SimpleFormatter;

FileHandler fh = new FileHandler("/var/log/mercadopago-sdk.log", true);
fh.setFormatter(new SimpleFormatter());

MercadoPagoConfig.setLoggingHandler(fh);
MercadoPagoConfig.setLoggingLevel(Level.FINE);

MercadoPagoConfig.setAccessToken("APP_USR-...");

​
Route requests through an HTTP proxy

import com.mercadopago.MercadoPagoConfig;
import org.apache.http.HttpHost;

MercadoPagoConfig.setAccessToken("APP_USR-...");
MercadoPagoConfig.setProxy(new HttpHost("proxy.corp.example.com", 3128, "http"));

​
Marketplace: tracking identifiers

import com.mercadopago.MercadoPagoConfig;

MercadoPagoConfig.setAccessToken("APP_USR-...");
MercadoPagoConfig.setPlatformId("MP-PLATFORM-ID");
MercadoPagoConfig.setIntegratorId("MP-INTEGRATOR-ID");
MercadoPagoConfig.setCorporationId("MP-CORP-ID");

Build docs developers (and LLMs) love

Get started for freeTalk to us