Configure the Mercado Pago Java SDK

MercadoPagoConfig is the central configuration class for the Mercado Pago Java SDK. It exposes a set of static, volatile fields that govern every API call made from the current JVM process — authentication credentials, HTTP timeouts, connection pooling, logging verbosity, proxy routing, custom retry logic, and the underlying HTTP client implementation. Because all configurable fields are declared volatile (or synchronized for compound operations), you can safely set them from any thread at application startup without additional locking. Per-request overrides are also available via MPRequestOptions, which lets you change the access token, timeouts, or headers for a single call without touching global state. See Per-Request Overrides below.

Global Configuration Reference

The following table lists every configurable property on MercadoPagoConfig, its type, default value, and purpose.

Property	Type	Default	Description
`accessToken`	`String`	`null`	OAuth access token used to authenticate all API requests. Must be set before making any call.
`platformId`	`String`	`null`	Platform identifier sent as a request header for analytics and tracking.
`corporationId`	`String`	`null`	Corporation identifier header for multi-entity traffic attribution.
`integratorId`	`String`	`null`	Integrator identifier header to attribute API traffic to a specific integration partner.
`loggingLevel`	`java.util.logging.Level`	`Level.OFF`	Verbosity of SDK log output. Set to `Level.FINEST` for full request/response logging.
`loggingHandler`	`java.util.logging.StreamHandler`	`null`	Custom log handler. When `null`, a default `ConsoleHandler` writing to `System.err` is used.
`metricsScope`	`String`	`"prod"`	Scope label included in SDK metrics reporting.
`maxConnections`	`int`	`10`	Maximum number of concurrent HTTP connections maintained in the connection pool.
`connectionTimeout`	`int`	`20000`	Timeout in milliseconds for establishing a new HTTP connection.
`connectionRequestTimeout`	`int`	`20000`	Timeout in milliseconds for obtaining a leased connection from the pool.
`socketTimeout`	`int`	`20000`	Socket read timeout in milliseconds — how long to wait for response data after the connection is established.
`httpClient`	`MPHttpClient`	`MPDefaultHttpClient`	Pluggable HTTP client. Lazily initialized to `MPDefaultHttpClient` on first use; replace with a custom implementation via `setHttpClient()`.
`proxy`	`org.apache.http.HttpHost`	`null`	HTTP proxy host through which all API requests are routed. `null` means direct connection.
`retryHandler`	`org.apache.http.client.HttpRequestRetryHandler`	`null`	Custom retry logic delegate. When set, the Apache HTTP client defers retry decisions to this handler.

Property Details

accessToken

String

required

The OAuth bearer token used to authenticate every API request. Obtain yours from the Mercado Pago Developer Panel. Can be overridden per-request via MPRequestOptions.accessToken.

MercadoPagoConfig.setAccessToken(System.getenv("MP_ACCESS_TOKEN"));

platformId

String

Sent as the x-platform-id header on every request. Used by Mercado Pago to identify the platform or framework generating traffic (e.g., a specific e-commerce platform integration).

MercadoPagoConfig.setPlatformId("your-platform-id");

corporationId

String

Sent as the x-corporation-id header. Used in multi-entity deployments to attribute traffic to a specific corporate account.

MercadoPagoConfig.setCorporationId("your-corporation-id");

integratorId

String

Sent as the x-integrator-id header to identify the integration partner or agency responsible for the integration.

MercadoPagoConfig.setIntegratorId("your-integrator-id");

loggingLevel

java.util.logging.Level

default:"Level.OFF"

Controls SDK log verbosity using the standard java.util.logging levels. Level.OFF (default) disables all output. Use Level.FINEST to log full request and response details during development.

MercadoPagoConfig.setLoggingLevel(Level.FINE);

loggingHandler

java.util.logging.StreamHandler

A custom StreamHandler to receive SDK log records. When not set, the SDK creates a ConsoleHandler writing to System.err. Supply a FileHandler or a handler that bridges to your application’s logging framework.

metricsScope

String

default:"\"prod\""

A label included in internal SDK metrics payloads. Change to "sandbox" or a custom value when you need to distinguish metric traffic from non-production environments.

maxConnections

int

default:"10"

The maximum number of concurrent HTTP connections the pool maintains. Increase this value for high-throughput applications that issue many concurrent API requests.

MercadoPagoConfig.setMaxConnections(50);

connectionTimeout

int

default:"20000"

Milliseconds to wait when establishing a new TCP connection to the Mercado Pago API. A value of 0 means wait indefinitely.

MercadoPagoConfig.setConnectionTimeout(5000);

connectionRequestTimeout

int

default:"20000"

Milliseconds to wait for an available connection to be leased from the pool. Relevant when all pool connections are busy. A value of 0 means wait indefinitely.

MercadoPagoConfig.setConnectionRequestTimeout(5000);

socketTimeout

int

default:"20000"

Milliseconds to wait for data after a connection is established — essentially the read timeout. Tune this down if you need fast failure detection, or up for slow payment method flows.

MercadoPagoConfig.setSocketTimeout(10000);

httpClient

MPHttpClient

The MPHttpClient implementation used for all API calls. Defaults to MPDefaultHttpClient (Apache HttpClient 4.x / 5.x based). Replace with a custom implementation to add instrumentation, circuit-breaking, or an alternative HTTP library.

proxy

org.apache.http.HttpHost

An Apache HttpHost describing the HTTP proxy through which all API requests are routed. Set to null (the default) to connect directly.

retryHandler

org.apache.http.client.HttpRequestRetryHandler

A custom HttpRequestRetryHandler that decides whether a failed request should be retried. When not set, the Apache HTTP client uses its default retry strategy (no retries on I/O exceptions for non-idempotent methods).

Configuration Examples

Setting Timeouts

Tune all three timeout values together for a tighter latency budget in production:

import com.mercadopago.MercadoPagoConfig;

public class AppConfig {
    public static void configure() {
        MercadoPagoConfig.setAccessToken(System.getenv("MP_ACCESS_TOKEN"));

        // Reduce all timeouts from the default 20 000 ms to 5 000 ms
        MercadoPagoConfig.setConnectionTimeout(5000);
        MercadoPagoConfig.setConnectionRequestTimeout(5000);
        MercadoPagoConfig.setSocketTimeout(5000);

        // Allow up to 50 concurrent connections for a high-throughput service
        MercadoPagoConfig.setMaxConnections(50);
    }
}

All timeout values are in milliseconds. A value of 0 means wait indefinitely — avoid this in production.

Enabling Logging

The SDK uses java.util.logging. Set loggingLevel to any standard Level to enable output. Use Level.FINEST during development to inspect raw HTTP request and response details.

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

// Enable verbose SDK logging — fine-grained request/response details
MercadoPagoConfig.setLoggingLevel(Level.FINEST);

To redirect log output to a file instead of the console, supply a custom FileHandler:

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

FileHandler fileHandler = new FileHandler("/var/log/mercadopago-sdk.log", true);
fileHandler.setFormatter(new SimpleFormatter());
fileHandler.setLevel(Level.FINE);

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

Level.FINEST logs full HTTP request and response bodies, which may include sensitive data such as card tokens or payer PII. Do not enable this level in production logs shipped to third-party systems.

Configuring a Proxy

Route all SDK traffic through an HTTP proxy by setting an Apache HttpHost:

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

// All API requests will be routed through proxy.internal:8080
HttpHost proxy = new HttpHost("proxy.internal", 8080, "http");
MercadoPagoConfig.setProxy(proxy);

To remove a previously configured proxy and restore direct connectivity:

MercadoPagoConfig.setProxy(null);

The proxy field uses synchronized getters and setters internally, so it is safe to change at runtime from any thread.

Custom HTTP Client

Replace the default MPDefaultHttpClient with your own implementation of the MPHttpClient interface. This is useful when you need to add instrumentation (e.g., Micrometer metrics, OpenTelemetry spans), plug in a circuit breaker, or use a different HTTP library entirely. The MPHttpClient interface requires a single method:

package com.mercadopago.net;

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

public interface MPHttpClient {
    MPResponse send(MPRequest request) throws MPException, MPApiException;
}

Implement and register your custom client before creating any SDK client instances:

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;
import com.mercadopago.net.MPHttpClient;
import com.mercadopago.net.MPRequest;
import com.mercadopago.net.MPResponse;

public class InstrumentedHttpClient implements MPHttpClient {

    private final MPHttpClient delegate;

    public InstrumentedHttpClient(MPHttpClient delegate) {
        this.delegate = delegate;
    }

    @Override
    public MPResponse send(MPRequest request) throws MPException, MPApiException {
        long start = System.currentTimeMillis();
        try {
            MPResponse response = delegate.send(request);
            recordSuccess(request.getUri(), System.currentTimeMillis() - start);
            return response;
        } catch (MPApiException | MPException e) {
            recordFailure(request.getUri(), System.currentTimeMillis() - start);
            throw e;
        }
    }

    private void recordSuccess(String uri, long durationMs) {
        // e.g. meterRegistry.timer("mp.api.request", "uri", uri).record(...)
    }

    private void recordFailure(String uri, long durationMs) {
        // e.g. meterRegistry.counter("mp.api.error", "uri", uri).increment()
    }
}

// Wrap the default client with instrumentation
MPHttpClient instrumented = new InstrumentedHttpClient(MercadoPagoConfig.getHttpClient());
MercadoPagoConfig.setHttpClient(instrumented);

// All subsequent client calls will use your instrumented implementation
PaymentClient paymentClient = new PaymentClient();

Per-Request Overrides

MPRequestOptions lets you override MercadoPagoConfig values for a single API call without affecting global state. Any field left at 0 (for int) or null (for objects) falls back to the global configuration automatically.

import com.mercadopago.core.MPRequestOptions;
import java.util.HashMap;
import java.util.Map;

Map<String, String> headers = new HashMap<>();
headers.put("X-Idempotency-Key", "a8098c1a-f86e-11da-bd1a-00112444be1e");

MPRequestOptions options = MPRequestOptions.builder()
        .accessToken("APP_USR-sandbox-token")  // different token for this call only
        .connectionTimeout(3000)               // tighter timeout for this call
        .connectionRequestTimeout(3000)
        .socketTimeout(3000)
        .customHeaders(headers)
        .build();

Payment payment = paymentClient.create(request, options);

MPRequestOptions supports the following overridable fields:

Field	Type	Description
`accessToken`	`String`	Per-request OAuth token. Overrides `MercadoPagoConfig.accessToken`.
`connectionTimeout`	`int`	Per-request connection timeout (ms). `0` uses global default.
`connectionRequestTimeout`	`int`	Per-request pool lease timeout (ms). `0` uses global default.
`socketTimeout`	`int`	Per-request socket read timeout (ms). `0` uses global default.
`customHeaders`	`Map<String, String>`	Additional HTTP headers merged into the request (e.g., idempotency keys).

Thread Safety

All fields in MercadoPagoConfig are declared volatile so that writes from one thread are immediately visible to all other threads without explicit synchronization. The proxy field uses synchronized accessors for compound read-modify operations. The httpClient field is lazily initialized via a synchronized method.

Configure MercadoPagoConfig once at application startup — ideally in a static initializer block or an application lifecycle hook — before any client objects are created. Changing global configuration mid-flight in a multi-threaded environment is safe at the volatile memory level, but can produce surprising behavior if in-flight requests read different settings than the ones that were active when the request was initiated.

// Recommended: configure once at startup
static {
    MercadoPagoConfig.setAccessToken(System.getenv("MP_ACCESS_TOKEN"));
    MercadoPagoConfig.setConnectionTimeout(5000);
    MercadoPagoConfig.setSocketTimeout(10000);
    MercadoPagoConfig.setLoggingLevel(Level.WARNING);
}

Get Started

Guides

Global Configuration Reference

Property Details

Configuration Examples

Setting Timeouts

Enabling Logging

Configuring a Proxy

Custom HTTP Client

Per-Request Overrides

Thread Safety

Build docs developers (and LLMs) love

Get Started

Guides

Documentation Index

​Global Configuration Reference

​Property Details

​Configuration Examples

​Setting Timeouts

​Enabling Logging

​Configuring a Proxy

​Custom HTTP Client

​Per-Request Overrides

​Thread Safety

Build docs developers (and LLMs) love

Global Configuration Reference

Property Details

Configuration Examples

Setting Timeouts

Enabling Logging

Configuring a Proxy

Custom HTTP Client

Per-Request Overrides

Thread Safety