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.

The Mercado Pago Java SDK is the official client library for integrating Mercado Pago’s payment platform into Java applications. It provides a comprehensive, type-safe interface to the full Mercado Pago REST API surface — covering one-time payments, Checkout PRO orders, subscription pre-approvals, in-person point-of-sale transactions, marketplace split payments, and more. Built for Java 1.8 and later, the SDK handles authentication, serialization, HTTP connection pooling, retries, and logging so you can focus on your business logic rather than API plumbing.

​
Requirements

To use the SDK your environment must meet the following prerequisites:
  • Java 1.8 or later — the SDK is compiled with source and target set to 1.8 and uses no APIs beyond that baseline.
  • Maven 3.x or Gradle — for dependency resolution and build lifecycle management.
  • A Mercado Pago account with an active access token. Create a free account if you don’t have one yet.

​
Current Version

The latest stable release published to Maven Central is 3.3.0. 
<!-- Maven -->
<dependency>
  <groupId>com.mercadopago</groupId>
  <artifactId>sdk-java</artifactId>
  <version>3.3.0</version>
</dependency>
See the Quickstart for full Maven and Gradle installation instructions.

​
What’s Included

The SDK ships one focused client class per API domain. Every client extends MercadoPagoClient and exposes overloaded methods that accept an optional MPRequestOptions for per-request configuration.

PaymentClient

Create, retrieve, cancel, capture (full and partial), search, and refund payments via the /v1/payments API. Includes a built-in PaymentRefundClient accessible through convenience methods.

OrderClient

Manage online and Checkout PRO orders via the Orders API. Supports creation with redirect URLs, tracking pixels, shipment details, and installment rules.

PreferenceClient

Create and manage Checkout PRO preferences that define the buyer experience — items, payment methods, redirect URLs, and expiry settings via /checkout/preferences.

PreapprovalClient

Create and manage recurring subscription agreements (pre-approvals) that authorize periodic charges to a payer’s payment method.

PreApprovalPlanClient

Define reusable subscription plan templates that multiple pre-approvals can reference, simplifying billing configuration at scale.

PointClient

Integrate with Mercado Pago Point in-person terminals to create and manage payment intents for face-to-face transactions.

AdvancedPaymentClient

Execute marketplace split payments that distribute a single charge across multiple sellers via /v1/advanced_payments.

CustomerClient

Create and manage saved customer profiles and their stored payment cards via /v1/customers.

MerchantOrderClient

Retrieve and manage merchant orders — containers that group one or more payments for a single transaction.

OauthClient

Exchange authorization codes for access tokens and refresh existing tokens via the OAuth 2.0 flow.

ChargebackClient

Read-only access to payment dispute (chargeback) records for monitoring and responding to cardholder disputes.

InvoiceClient

Retrieve subscription billing invoices generated by active pre-approvals via /authorized_payments.

​
Architecture Overview

Understanding four core concepts will help you use the SDK effectively.

​
MercadoPagoConfig — Global Settings

MercadoPagoConfig is a static configuration class whose fields apply to every API call made from the current JVM. At minimum you must set an access token before making any request: 
MercadoPagoConfig.setAccessToken("APP_USR-...");
Beyond authentication, MercadoPagoConfig lets you tune HTTP timeouts, connection pool size, logging verbosity, proxy routing, and the underlying HTTP client implementation. All fields are declared volatile, making the class safe to configure from any thread at startup. See the Configuration page for the full property reference.

​
MPRequestOptions — Per-Request Overrides

Any field left at its zero/null default in MPRequestOptions falls back to the corresponding MercadoPagoConfig value. This lets you override the access token, timeouts, or add custom headers (such as idempotency keys) for a single call without touching global state: 
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;

Map<String, String> headers = new HashMap<>();
headers.put("X-Idempotency-Key", UUID.randomUUID().toString());

MPRequestOptions options = MPRequestOptions.builder()
    .accessToken("APP_USR-different-token")
    .connectionTimeout(5000)
    .customHeaders(headers)
    .build();

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

​
Builder Pattern on All Request Objects

Every request class (PaymentCreateRequest, OrderCreateRequest, PreferenceRequest, etc.) uses Lombok’s @Builder, giving you a fluent, compile-time-checked construction API: 
PaymentCreateRequest request = PaymentCreateRequest.builder()
    .transactionAmount(new BigDecimal("100.00"))
    .description("Blue running shoes")
    .paymentMethodId("visa")
    .payer(PaymentPayerRequest.builder()
        .email("buyer@example.com")
        .build())
    .build();

​
Exception Hierarchy

The SDK throws two checked exception types:
ExceptionWhen thrown
MPApiExceptionThe API returned a non-2xx HTTP status code. Exposes the full MPResponse for inspection.
MPExceptionA transport-level or SDK-internal error occurred (e.g., connection timeout, serialization failure).
Always catch both in production code: 
try {
    Payment payment = client.create(request);
} catch (MPApiException e) {
    // API returned 4xx/5xx — inspect e.getApiResponse()
    System.err.println("API error: " + e.getMessage());
} catch (MPException e) {
    // Transport or SDK error
    System.err.println("SDK error: " + e.getMessage());
}

​
Next Steps

Quickstart

Install the SDK, set your credentials, and process your first payment in under five minutes.

Configuration

Explore every configurable property: timeouts, logging, proxy, connection pool, and custom HTTP client.

Build docs developers (and LLMs) love

Get started for freeTalk to us