MPRequestOptions: Per-Request Configuration Overrides

MPRequestOptions is an immutable, per-request configuration object that lets you override the global defaults set in MercadoPagoConfig for a single API call. Any field left at its zero or null default automatically falls back to the corresponding global value, so you only need to populate the fields you want to change. Instances are constructed using the Lombok-generated builder and are safe to create on every request without pooling. Package: com.mercadopago.core

Priority Order

When the SDK resolves the final value of a setting, it follows this precedence chain (highest to lowest):

MPRequestOptions — field is non-null / non-zero in the options object passed to the API call.
Request object field — some resource request classes (e.g., PaymentCreateRequest) expose their own token or header fields.
MercadoPagoConfig — the global static configuration, used as the final fallback.

Creating an Instance

Builder (recommended)

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

MPRequestOptions options = MPRequestOptions.builder()
    .accessToken("APP_USR-seller-specific-token")
    .connectionTimeout(5000)
    .connectionRequestTimeout(5000)
    .socketTimeout(10000)
    .customHeaders(Map.of("x-idempotency-key", "my-unique-uuid-v4"))
    .build();

`createDefault()`

Returns an MPRequestOptions instance with all fields at their zero/null defaults. Passing this to any SDK method is equivalent to not passing MPRequestOptions at all — every setting will fall back to MercadoPagoConfig.

MPRequestOptions defaultOptions = MPRequestOptions.createDefault();

Fields

accessToken

String

OAuth access token used exclusively for this request, overriding the global token configured in MercadoPagoConfig.setAccessToken(). When null, the global token is used.This is the primary field for marketplace scenarios where each API call must be authenticated on behalf of a different connected seller.

MPRequestOptions options = MPRequestOptions.builder()
    .accessToken("APP_USR-seller-123-token")
    .build();

connectionTimeout

int (milliseconds)

default:"0 (use global)"

Maximum time in milliseconds to wait while establishing a new TCP connection for this request. A value of 0 means the SDK uses the value from MercadoPagoConfig.getConnectionTimeout() (default 20000 ms).

MPRequestOptions options = MPRequestOptions.builder()
    .connectionTimeout(3000) // 3-second connect timeout for this call
    .build();

connectionRequestTimeout

int (milliseconds)

default:"0 (use global)"

Maximum time in milliseconds to wait when acquiring an existing connection from the pool for this request. A value of 0 defers to MercadoPagoConfig.getConnectionRequestTimeout() (default 20000 ms).

MPRequestOptions options = MPRequestOptions.builder()
    .connectionRequestTimeout(3000)
    .build();

socketTimeout

int (milliseconds)

default:"0 (use global)"

Maximum time in milliseconds to wait for data to arrive on the socket during this request. A value of 0 defers to MercadoPagoConfig.getSocketTimeout() (default 20000 ms).

MPRequestOptions options = MPRequestOptions.builder()
    .socketTimeout(8000) // 8-second read timeout for this call
    .build();

customHeaders

Map<String, String>

Additional HTTP headers to include in this request only. Common use cases include:

Idempotency keys (x-idempotency-key) to safely retry POST requests.
Custom tracing headers for distributed tracing systems (e.g., x-request-id).

Header names are case-insensitive per the HTTP specification. Do not use this field to set Authorization or the standard Mercado Pago tracking headers — those are managed automatically by the SDK.

import java.util.Map;
import java.util.UUID;

MPRequestOptions options = MPRequestOptions.builder()
    .customHeaders(Map.of(
        "x-idempotency-key", UUID.randomUUID().toString(),
        "x-request-id",      "trace-abc-123"
    ))
    .build();

Common Use Cases

Per-merchant access token (marketplace)

In a marketplace integration each seller has their own OAuth token. Pass the seller’s token via MPRequestOptions so you never overwrite the global configuration shared by other threads.

import com.mercadopago.client.payment.PaymentClient;
import com.mercadopago.client.payment.PaymentCreateRequest;
import com.mercadopago.core.MPRequestOptions;
import com.mercadopago.model.payment.Payment;

PaymentClient client = new PaymentClient();

MPRequestOptions sellerOptions = MPRequestOptions.builder()
    .accessToken("APP_USR-seller-oauth-token")
    .build();

PaymentCreateRequest request = PaymentCreateRequest.builder()
    .transactionAmount(new BigDecimal("100.00"))
    .token("card-token")
    .installments(1)
    .paymentMethodId("visa")
    .payer(PayerRequest.builder().email("buyer@example.com").build())
    .build();

Payment payment = client.create(request, sellerOptions);

Idempotent POST requests

Attach a unique idempotency key to prevent duplicate charges if the network request is retried after a timeout.

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

String idempotencyKey = UUID.randomUUID().toString();

MPRequestOptions options = MPRequestOptions.builder()
    .customHeaders(Map.of("x-idempotency-key", idempotencyKey))
    .build();

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

Tighter timeouts for latency-sensitive operations

Use reduced timeouts for calls inside a user-facing request path where a slow API response should fail fast rather than block a web thread.

MPRequestOptions fastOptions = MPRequestOptions.builder()
    .connectionTimeout(2000)
    .connectionRequestTimeout(2000)
    .socketTimeout(4000)
    .build();

Payment payment = client.create(request, fastOptions);

All fields combined

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

MPRequestOptions options = MPRequestOptions.builder()
    .accessToken("APP_USR-seller-oauth-token")
    .connectionTimeout(3000)
    .connectionRequestTimeout(3000)
    .socketTimeout(8000)
    .customHeaders(Map.of(
        "x-idempotency-key", UUID.randomUUID().toString()
    ))
    .build();

MPSearchRequest

MPSearchRequest encapsulates the search filters and pagination parameters sent to any SDK search() method. It is constructed with the same Lombok builder pattern. Package: com.mercadopago.net

Fields

limit

Integer

Maximum number of results to return per page. Passed as the limit query parameter. If the filters map already contains a "limit" key, that value takes precedence over this field.

offset

Integer

Zero-based index of the first result to return. Passed as the offset query parameter. If the filters map already contains an "offset" key, that value takes precedence.

filters

Map<String, Object>

Arbitrary key-value pairs appended as additional query parameters. Use this to filter results by resource-specific fields such as status, external_reference, date_created.from, etc.Filter values override limit and offset if the same key appears in both places.

`getParameters()`

public Map<String, Object> getParameters()

Merges the limit, offset, and filters fields into a single query-parameter map that the SDK appends to the request URL. Returns a new mutable HashMap on every call.

Builder example

import com.mercadopago.net.MPSearchRequest;
import java.util.Map;

MPSearchRequest searchRequest = MPSearchRequest.builder()
    .limit(50)
    .offset(0)
    .filters(Map.of(
        "status",             "approved",
        "external_reference", "order-9876"
    ))
    .build();

// Pass to any search() method:
// PaymentClient client = new PaymentClient();
// MPResultsResourcesPage<Payment> page = client.search(searchRequest);

Paginating through all results

import com.mercadopago.client.payment.PaymentClient;
import com.mercadopago.net.MPResultsResourcesPage;
import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.model.payment.Payment;

PaymentClient client  = new PaymentClient();
int pageSize          = 100;
int offset            = 0;
int total;

do {
    MPSearchRequest req = MPSearchRequest.builder()
        .limit(pageSize)
        .offset(offset)
        .build();

    MPResultsResourcesPage<Payment> page = client.search(req);
    total  = page.getPaging().getTotal();
    offset += page.getResults().size();

    page.getResults().forEach(p -> System.out.println(p.getId()));
} while (offset < total);

Response Wrapper Types

All SDK list and search methods return one of three generic wrapper types, each of which extends MPResource and therefore carries an attached MPResponse with the raw HTTP metadata.

MPResourceList<T>

Package: com.mercadopago.net Represents a response whose JSON body is a flat array of resource objects — no pagination envelope. Used for endpoints that return all matching items in a single call.

[{"id": 1, ...}, {"id": 2, ...}]

getResults()

List<T>

The deserialized list of resource objects. May be empty but is never null.

MPResourceList<CardToken> list = cardTokenClient.list();
List<CardToken> tokens = list.getResults();

MPResultsResourcesPage<T>

Package: com.mercadopago.net Represents a paginated response following the {"paging": {...}, "results": [...]} envelope used by most Mercado Pago search endpoints.

{
  "paging":  {"total": 1500, "limit": 50, "offset": 0},
  "results": [{...}, {...}]
}

getPaging()

com.mercadopago.resources.ResultsPaging

Pagination metadata for the current page.

Show ResultsPaging fields

total

int

Total number of items matching the query across all pages. Constant across pages.

limit

int

Maximum items returned per page. Mirrors the limit parameter sent in the request.

offset

int

Zero-based position of the first item in this page within the full result set.

getResults()

List<T>

The deserialized resource objects for the current page.

MPResultsResourcesPage<Payment> page = paymentClient.search(searchRequest);

int total  = page.getPaging().getTotal();
int limit  = page.getPaging().getLimit();
int offset = page.getPaging().getOffset();

List<Payment> payments = page.getResults();

MPElementsResourcesPage<T>

Package: com.mercadopago.net Represents a paginated response following the alternative {"total": N, "next_offset": M, "elements": [...]} envelope used by some Mercado Pago endpoints (e.g., subscription-related resources).

{
  "total":       1500,
  "next_offset": 50,
  "elements":    [{...}, {...}]
}

getTotal()

int

Total number of items across all pages that match the search criteria. Constant across pages.

getNextOffset()

int

The offset value to pass as offset in the next request to retrieve the following page. When getNextOffset() >= getTotal(), all items have been fetched.

getElements()

List<T>

The deserialized resource objects for the current page.

int offset = 0;

do {
    MPSearchRequest req = MPSearchRequest.builder()
        .limit(50)
        .offset(offset)
        .build();

    MPElementsResourcesPage<Subscription> page = subscriptionClient.search(req);
    page.getElements().forEach(s -> System.out.println(s.getId()));
    offset = page.getNextOffset();

} while (offset < page.getTotal()); // page must be in scope; use a variable in real code

Accessing the Raw HTTP Response

Every object returned by the SDK — whether a single resource, an MPResourceList, an MPResultsResourcesPage, or an MPElementsResourcesPage — extends MPResource and exposes a getResponse() method that returns the underlying MPResponse.

getResponse()

com.mercadopago.net.MPResponse

The raw HTTP response from which the resource was deserialized.

Show MPResponse fields

getStatusCode()

Integer

HTTP status code of the response (e.g., 200, 201, 400, 404).

getHeaders()

Map<String, List<String>>

All response headers. Each header name maps to a list of values to support multi-value headers such as Set-Cookie.

getContent()

String

Raw UTF-8 response body. Empty string for 204 No Content responses.

import com.mercadopago.net.MPResponse;

Payment payment = paymentClient.get(12345L);

MPResponse response = payment.getResponse();
System.out.println("HTTP status : " + response.getStatusCode());
System.out.println("Raw body    : " + response.getContent());
System.out.println("Request-ID  : " + response.getHeaders().get("x-request-id"));

Core

Clients

Exceptions & HTTP

MPRequestOptions: Per-Request Configuration Overrides

Priority Order

Creating an Instance

Builder (recommended)

`createDefault()`

Fields

Common Use Cases

Per-merchant access token (marketplace)

Idempotent POST requests

Tighter timeouts for latency-sensitive operations

All fields combined

MPSearchRequest

Fields

`getParameters()`

Builder example

Paginating through all results

Response Wrapper Types

MPResourceList<T>

MPResultsResourcesPage<T>

MPElementsResourcesPage<T>

Accessing the Raw HTTP Response

Build docs developers (and LLMs) love

Core

Clients

Exceptions & HTTP

Documentation Index

​Priority Order

​Creating an Instance

​Builder (recommended)

​createDefault()

​Fields

​Common Use Cases

​Per-merchant access token (marketplace)

​Idempotent POST requests

​Tighter timeouts for latency-sensitive operations

​All fields combined

​MPSearchRequest

​Fields

​getParameters()

​Builder example

​Paginating through all results

​Response Wrapper Types

​MPResourceList<T>

​MPResultsResourcesPage<T>

​MPElementsResourcesPage<T>

​Accessing the Raw HTTP Response

Build docs developers (and LLMs) love

Priority Order

Creating an Instance

Builder (recommended)

`createDefault()`

Fields

Common Use Cases

Per-merchant access token (marketplace)

Idempotent POST requests

Tighter timeouts for latency-sensitive operations

All fields combined

MPSearchRequest

Fields

`getParameters()`

Builder example

Paginating through all results

Response Wrapper Types

MPResourceList<T>

MPResultsResourcesPage<T>

MPElementsResourcesPage<T>

Accessing the Raw HTTP Response