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.

A Mercado Pago checkout preference is the configuration object that drives the Checkout Pro payment experience. It declares what is being sold (items), who is buying (payer), which payment methods are accepted, where to redirect the buyer after payment, and when the session expires. When you call PreferenceClient.create(), Mercado Pago returns a ready-to-use initPoint URL that you embed in your site or app — clicking it opens the hosted Mercado Pago checkout flow with all your settings pre-applied.

​
Setting up

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.preference.PreferenceClient;

MercadoPagoConfig.setAccessToken("APP_USR-your-access-token");
PreferenceClient client = new PreferenceClient();

​
What is a preference?

A preference defines the complete payment experience for a single checkout session:
  • Items — titles, quantities, and unit prices that appear in the checkout summary.
  • Payer — pre-fill the buyer’s email and personal details to streamline the form.
  • Payment methods — exclude specific methods or card types, and set installment limits.
  • Back URLs — where to send the buyer after a successful, pending, or failed payment.
  • Expiration — an optional window after which the checkout session is no longer valid.
After creation the Preference resource contains an initPoint (production) and a sandboxInitPoint (test environment) URL. Redirect your buyer to the appropriate URL to start the payment flow.

​
Creating a preference

1

Define the items

import com.mercadopago.client.preference.PreferenceItemRequest;
import java.math.BigDecimal;
import java.util.Arrays;
import java.util.List;

List<PreferenceItemRequest> items = Arrays.asList(
    PreferenceItemRequest.builder()
        .id("SKU-001")
        .title("Wireless Headphones")
        .description("Noise-cancelling over-ear headphones")
        .quantity(1)
        .unitPrice(new BigDecimal("129.99"))
        .currencyId("BRL")
        .build(),
    PreferenceItemRequest.builder()
        .id("SKU-002")
        .title("USB-C Charging Cable")
        .description("2-metre braided cable")
        .quantity(2)
        .unitPrice(new BigDecimal("19.99"))
        .currencyId("BRL")
        .build()
);
2

Define the payer

import com.mercadopago.client.preference.PreferencePayerRequest;

PreferencePayerRequest payer = PreferencePayerRequest.builder()
    .name("Jane")
    .surname("Smith")
    .email("buyer@example.com")
    .build();
3

Define back URLs

import com.mercadopago.client.preference.PreferenceBackUrlsRequest;

PreferenceBackUrlsRequest backUrls = PreferenceBackUrlsRequest.builder()
    .success("https://yourapp.example.com/checkout/success")
    .pending("https://yourapp.example.com/checkout/pending")
    .failure("https://yourapp.example.com/checkout/failure")
    .build();
4

Build and create the preference

import com.mercadopago.client.preference.PreferenceRequest;
import com.mercadopago.resources.preference.Preference;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;

PreferenceRequest preferenceRequest = PreferenceRequest.builder()
    .items(items)
    .payer(payer)
    .backUrls(backUrls)
    .autoReturn("approved")
    .externalReference("cart-42")
    .notificationUrl("https://yourapp.example.com/webhooks/mp")
    .build();

try {
    Preference preference = client.create(preferenceRequest);
    System.out.println("Preference ID : " + preference.getId());
    System.out.println("Init point    : " + preference.getInitPoint());
    System.out.println("Sandbox URL   : " + preference.getSandboxInitPoint());
} catch (MPApiException ex) {
    System.out.printf("API error %d: %s%n",
        ex.getApiResponse().getStatusCode(),
        ex.getApiResponse().getContent());
} catch (MPException ex) {
    ex.printStackTrace();
}
Set autoReturn to "approved" to automatically redirect buyers back to your backUrls.success URL right after a successful payment. Use "all" to redirect after any final status.

​
Getting a preference

Retrieve a previously created preference by its string ID. 
Preference preference = client.get("your-preference-id");

System.out.println("ID         : " + preference.getId());
System.out.println("Init point : " + preference.getInitPoint());
System.out.println("Created at : " + preference.getDateCreated());
The initPoint field always contains the live production checkout URL. Use sandboxInitPoint while testing in the Mercado Pago sandbox environment.

​
Updating a preference

Update any fields on an existing preference. Pass the same PreferenceRequest builder with the fields you want to change; unspecified fields are omitted from the request body. 
PreferenceRequest updateRequest = PreferenceRequest.builder()
    .items(Arrays.asList(
        PreferenceItemRequest.builder()
            .id("SKU-001")
            .title("Wireless Headphones — Special Edition")
            .quantity(1)
            .unitPrice(new BigDecimal("149.99"))
            .currencyId("BRL")
            .build()
    ))
    .externalReference("cart-42-updated")
    .build();

Preference updated = client.update("your-preference-id", updateRequest);
System.out.println("Updated init point: " + updated.getInitPoint());

​
Searching preferences

Use MPSearchRequest to filter your preference list and paginate through results. 
import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.net.MPElementsResourcesPage;
import com.mercadopago.resources.preference.PreferenceSearch;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> filters = new HashMap<>();
filters.put("external_reference", "cart-42");

MPSearchRequest searchRequest = MPSearchRequest.builder()
    .limit(10)
    .offset(0)
    .filters(filters)
    .build();

MPElementsResourcesPage<PreferenceSearch> results = client.search(searchRequest);

System.out.println("Total results: " + results.getTotal());
for (PreferenceSearch ps : results.getElements()) {
    System.out.println("  Preference ID: " + ps.getId());
}
Increment offset by limit to fetch subsequent pages.

​
Using the initPoint URL

After creating a preference, redirect your buyer to preference.getInitPoint() to start the Checkout Pro payment flow. In a typical web integration you generate the URL on the server and send it to the front end: 
// Server-side: create preference and send the URL to the client
Preference preference = client.create(preferenceRequest);
String checkoutUrl = preference.getInitPoint(); // use sandboxInitPoint for testing

// Return checkoutUrl in your API response, then on the front end:
// window.location.href = checkoutUrl;
The initPoint URL is valid until the preference’s expirationDateTo is reached (if set). By default, preferences do not expire, but you should store the preference ID in your database so you can retrieve or update it later.

​
Per-request options

Pass MPRequestOptions as the second argument to any PreferenceClient method to override the access token or set custom headers for that single request. 
import com.mercadopago.core.MPRequestOptions;
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-alternate-access-token")
    .connectionTimeout(5_000)
    .socketTimeout(10_000)
    .customHeaders(headers)
    .build();

Preference preference = client.create(preferenceRequest, options);
Preference fetched    = client.get("your-preference-id", options);
Preference updated    = client.update("your-preference-id", updateRequest, options);

Build docs developers (and LLMs) love

Get started for freeTalk to us