Get Started with the Mercado Pago Java SDK

This guide walks you through adding the Mercado Pago Java SDK to your project, authenticating with your access token, and executing your first payment — all in a few minutes. The SDK targets Java 1.8+ and is available from Maven Central, so no custom repository configuration is required.

Installation

Choose the build tool that matches your project.

The SDK is published to Maven Central. Run mvn install or gradle build after adding the dependency and it will be resolved automatically on the next build.

Maven

Add the following dependency to your pom.xml:

<dependency>
  <groupId>com.mercadopago</groupId>
  <artifactId>sdk-java</artifactId>
  <version>3.3.0</version>
</dependency>

Gradle

Add the dependency to your build.gradle:

implementation 'com.mercadopago:sdk-java:3.3.0'

Getting Your Credentials

You need a Mercado Pago access token to authenticate API calls. Retrieve it from the Mercado Pago Developer Panel:

Log in and navigate to Your applications.
Select or create an application.
Copy the Access token from the Credentials section.

Never commit your access token to source control. Use environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault) to inject it at runtime.

Quickstart

Add the dependency

Add the Maven or Gradle dependency shown above to your project and run a build to pull the artifact from Maven Central.Verify the dependency resolved correctly by importing a class from the SDK:

import com.mercadopago.MercadoPagoConfig;

If the import resolves without errors, the SDK is on your classpath.

Set your access token

Configure the global access token once at application startup — typically in your main method or application initializer. Every subsequent API call will use this token unless you override it per-request with MPRequestOptions.

import com.mercadopago.MercadoPagoConfig;

public class App {
    public static void main(String[] args) {
        // Read from an environment variable — never hardcode secrets
        MercadoPagoConfig.setAccessToken(System.getenv("MP_ACCESS_TOKEN"));
    }
}

For sandbox testing, use your Test access token from the Developer Panel. Switch to your Production access token only when going live.

Create your first payment

Use PaymentClient to create a card payment. Build the request with the fluent builder API, then call client.create().

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.payment.PaymentClient;
import com.mercadopago.client.payment.PaymentCreateRequest;
import com.mercadopago.client.payment.PaymentPayerRequest;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;
import com.mercadopago.resources.payment.Payment;

import java.math.BigDecimal;

public class CreatePaymentExample {

    public static void main(String[] args) {
        MercadoPagoConfig.setAccessToken(System.getenv("MP_ACCESS_TOKEN"));

        PaymentClient client = new PaymentClient();

        PaymentCreateRequest request = PaymentCreateRequest.builder()
                .transactionAmount(new BigDecimal("105.00"))
                .description("Blue running shoes — size 42")
                .paymentMethodId("visa")
                // Card token generated by the MercadoPago.js tokenizer on your front-end
                .token("{{CARD_TOKEN}}")
                .installments(1)
                .payer(PaymentPayerRequest.builder()
                        .email("buyer@example.com")
                        .build())
                .externalReference("order-1234")
                .build();

        try {
            Payment payment = client.create(request);
            System.out.println("Payment created — ID: " + payment.getId());
            System.out.println("Status: " + payment.getStatus());
            System.out.println("Status detail: " + payment.getStatusDetail());
        } catch (MPApiException e) {
            System.err.println("API error " + e.getStatusCode() + ": " + e.getMessage());
        } catch (MPException e) {
            System.err.println("SDK error: " + e.getMessage());
        }
    }
}

The token field must be a one-time card token created by the MercadoPago.js front-end tokenizer. The SDK never handles raw card numbers.

Handle the response

A successful create() call returns a Payment object. Check getStatus() to determine the outcome:

`getStatus()`	Meaning
`approved`	Payment captured and funds reserved.
`pending`	Payment initiated but awaiting payer action (e.g., bank redirect).
`in_process`	Under manual review by Mercado Pago’s risk team.
`rejected`	Payment declined. Check `getStatusDetail()` for the reason.

Payment payment = client.create(request);

switch (payment.getStatus()) {
    case "approved":
        System.out.println("Approved! Transaction ID: " + payment.getId());
        break;
    case "pending":
    case "in_process":
        System.out.println("Awaiting confirmation — poll or wait for webhook.");
        break;
    case "rejected":
        System.out.println("Rejected: " + payment.getStatusDetail());
        break;
    default:
        System.out.println("Unexpected status: " + payment.getStatus());
}

Order API Example

For Checkout PRO flows, use OrderClient instead of PaymentClient. The Orders API supports redirect-based checkouts, tracking pixels, and advanced configuration options added in SDK 3.3.0.

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.order.*;
import com.mercadopago.core.MPRequestOptions;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;
import com.mercadopago.resources.order.Order;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class CreateOrderExample {

    public static void main(String[] args) {
        MercadoPagoConfig.setAccessToken(System.getenv("MP_ACCESS_TOKEN"));

        OrderClient client = new OrderClient();

        OrderPaymentRequest payment = OrderPaymentRequest.builder()
                .amount("10.00")
                .paymentMethod(OrderPaymentMethodRequest.builder()
                        .id("master")
                        .type("credit_card")
                        .token("{{CARD_TOKEN}}")
                        .installments(1)
                        .build())
                .build();

        List<OrderPaymentRequest> payments = new ArrayList<>();
        payments.add(payment);

        OrderCreateRequest request = OrderCreateRequest.builder()
                .type("online")
                .totalAmount("10.00")
                .externalReference("ext_ref_001")
                .payer(OrderPayerRequest.builder()
                        .email("buyer@example.com")
                        .build())
                .transactions(OrderTransactionRequest.builder()
                        .payments(payments)
                        .build())
                .build();

        // Attach an idempotency key to safely retry on network failure
        Map<String, String> headers = new HashMap<>();
        headers.put("X-Idempotency-Key", "{{IDEMPOTENCY_KEY}}");

        MPRequestOptions requestOptions = MPRequestOptions.builder()
                .customHeaders(headers)
                .build();

        try {
            Order order = client.create(request, requestOptions);
            System.out.println("Order created: " + order.getId());
        } catch (MPApiException | MPException e) {
            System.err.println("Error creating order: " + e.getMessage());
        }
    }
}

Error Handling

The SDK throws two checked exception types. Always handle both.

try {
    Payment payment = client.create(request);
} catch (MPApiException e) {
    // The API returned a 4xx or 5xx HTTP response.
    // e.getStatusCode()   → HTTP status (e.g. 400, 401, 422)
    // e.getApiResponse()  → full MPResponse with headers and body
    System.err.println("HTTP " + e.getStatusCode() + " — " + e.getMessage());
} catch (MPException e) {
    // A transport or SDK-internal error occurred before a response was received.
    // Examples: connection timeout, DNS failure, serialization error.
    System.err.println("Transport error: " + e.getMessage());
}

MPApiException does not mean the payment failed — an HTTP 200 with status: rejected is a successful API call. Always inspect Payment.getStatus() after a successful response.

Per-Request Options

Use MPRequestOptions to override the access token, set tighter timeouts, or attach custom headers for a single API call without changing global configuration:

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

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

MPRequestOptions requestOptions = MPRequestOptions.builder()
        .accessToken("APP_USR-different-token")   // override global token
        .connectionTimeout(5000)                  // ms — override global 20 000 ms
        .connectionRequestTimeout(5000)
        .socketTimeout(5000)
        .customHeaders(customHeaders)
        .build();

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

Any field left at 0 or null in MPRequestOptions automatically falls back to the corresponding value in MercadoPagoConfig. You only need to set the fields you want to override.

Next Steps

Configuration — tune timeouts, logging, proxy, connection pool size, and swap in a custom HTTP client.
Mercado Pago API Reference (EN) — full REST API documentation.

Get Started

Guides

Get Started with the Mercado Pago Java SDK

Installation

Maven

Gradle

Getting Your Credentials

Quickstart

Order API Example

Error Handling

Per-Request Options

Next Steps

Build docs developers (and LLMs) love

Get Started

Guides

Documentation Index

​Installation

​Maven

​Gradle

​Getting Your Credentials

​Quickstart

​Order API Example

​Error Handling

​Per-Request Options

​Next Steps

Build docs developers (and LLMs) love

Installation

Maven

Gradle

Getting Your Credentials

Quickstart

Order API Example

Error Handling

Per-Request Options

Next Steps