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 Payments API lets you charge buyers, authorize and capture amounts in two steps, cancel pending payments, search your transaction history, and issue full or partial refunds — all through a single PaymentClient instance. After you set your access token on MercadoPagoConfig, every operation is a single method call that returns a typed Payment or PaymentRefund resource.

​
Setting up

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.payment.PaymentClient;

MercadoPagoConfig.setAccessToken("APP_USR-your-access-token");
PaymentClient client = new PaymentClient();
PaymentClient automatically creates an internal PaymentRefundClient so you never need to instantiate refund handling separately.

​
Creating a payment

Build a PaymentCreateRequest with the transaction amount, a card token, the payer’s email, and the payment method. Pass it to client.create() to process the charge immediately.
1

Build the payer

import com.mercadopago.client.payment.PaymentPayerRequest;

PaymentPayerRequest payer = PaymentPayerRequest.builder()
    .email("buyer@example.com")
    .firstName("Jane")
    .lastName("Smith")
    .build();
2

Build the request

import com.mercadopago.client.payment.PaymentCreateRequest;
import java.math.BigDecimal;

PaymentCreateRequest request = PaymentCreateRequest.builder()
    .transactionAmount(new BigDecimal("350.00"))
    .token("card-token-from-frontend")   // generated by MercadoPago.js
    .description("Premium subscription — 1 month")
    .installments(1)
    .paymentMethodId("visa")
    .payer(payer)
    .externalReference("order-001")
    .notificationUrl("https://yourapp.example.com/webhooks/mp")
    .build();
3

Create the payment

import com.mercadopago.resources.payment.Payment;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;

try {
    Payment payment = client.create(request);
    System.out.println("Created payment ID : " + payment.getId());
    System.out.println("Status             : " + payment.getStatus());
    System.out.println("Status detail      : " + payment.getStatusDetail());
} catch (MPApiException ex) {
    System.out.printf("API error %d: %s%n",
        ex.getApiResponse().getStatusCode(),
        ex.getApiResponse().getContent());
} catch (MPException ex) {
    ex.printStackTrace();
}
For POST, PUT, and PATCH requests the SDK generates a unique X-Idempotency-Key automatically. You can override it per request using MPRequestOptions — see the Per-request options section below.

​
Getting a payment

Retrieve a payment by its numeric ID to read the latest status, amounts, or transaction details. 
Payment payment = client.get(1234567890L);

System.out.println("Status          : " + payment.getStatus());
System.out.println("Amount          : " + payment.getTransactionAmount());
System.out.println("Payment method  : " + payment.getPaymentMethodId());
System.out.println("Captured        : " + payment.isCaptured());

​
Cancelling a payment

Cancel a payment that is still in the pending state. The returned Payment object reflects the cancelled status. 
Payment cancelled = client.cancel(1234567890L);
System.out.println("New status: " + cancelled.getStatus()); // "cancelled"
Only payments in pending status can be cancelled. Approved or rejected payments cannot be cancelled — issue a refund instead.

​
Capturing a payment

When you create a payment with capture(false), the card is authorized but not charged. Use client.capture() to settle the funds. 
// Capture the full authorized amount
Payment captured = client.capture(1234567890L);
System.out.println("Captured: " + captured.isCaptured());
System.out.println("Status  : " + captured.getStatus());
Calling capture(id) with no amount always captures the full authorized amount. Passing an explicit BigDecimal amount performs a partial capture for exactly that value.

​
Searching payments

Use MPSearchRequest to filter payments and paginate through results. Filters map directly to the query parameters accepted by the /v1/payments/search endpoint. 
import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.net.MPResultsResourcesPage;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> filters = new HashMap<>();
filters.put("status", "approved");
filters.put("external_reference", "order-001");

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

MPResultsResourcesPage<Payment> results = client.search(searchRequest);

System.out.println("Total results : " + results.getPaging().getTotal());
System.out.println("Returned now  : " + results.getResults().size());

for (Payment p : results.getResults()) {
    System.out.printf("  id=%-15d status=%s amount=%s%n",
        p.getId(), p.getStatus(), p.getTransactionAmount());
}
Advance to the next page by incrementing offset by limit on each subsequent call.

​
Refunds

Refund operations are exposed directly on PaymentClient and internally delegate to PaymentRefundClient. Both full and partial refunds are supported.

​
Full refund

Return the entire transaction amount to the payer. 
import com.mercadopago.resources.payment.PaymentRefund;

PaymentRefund refund = client.refund(1234567890L);

System.out.println("Refund ID     : " + refund.getId());
System.out.println("Amount        : " + refund.getAmount());
System.out.println("Status        : " + refund.getStatus());

​
Partial refund

Return only a portion of the amount. 
import java.math.BigDecimal;

PaymentRefund partialRefund = client.refund(1234567890L, new BigDecimal("50.00"));
System.out.println("Refund amount : " + partialRefund.getAmount());

​
Get a refund

Retrieve a specific refund by its ID. 
// getRefund(paymentId, refundId)
PaymentRefund refund = client.getRefund(1234567890L, 9876543210L);
System.out.println("Refund status : " + refund.getStatus());

​
List all refunds

List every refund that has been issued against a payment. 
import com.mercadopago.net.MPResourceList;

MPResourceList<PaymentRefund> refunds = client.listRefunds(1234567890L);

for (PaymentRefund r : refunds.getResults()) {
    System.out.printf("  refund id=%-12d amount=%s status=%s%n",
        r.getId(), r.getAmount(), r.getStatus());
}

​
Per-request options

MPRequestOptions lets you override the access token, set custom headers (including an explicit idempotency key), or tune HTTP timeouts for a single call without touching the global MercadoPagoConfig. 
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();

// Pass options as the second argument to any client method
Payment payment = client.create(request, options);
Payment fetched  = client.get(payment.getId(), options);
Payment captured = client.capture(payment.getId(), options);
For POST, PUT, and PATCH requests the SDK generates a X-Idempotency-Key automatically if you do not supply one. Supply your own key in customHeaders when you need deterministic replay protection — for example, when retrying a timed-out request.

Build docs developers (and LLMs) love

Get started for freeTalk to us