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 Orders API represents the top-level purchase entity that groups one or more payment transactions, line items, payer details, and checkout configuration. OrderClient exposes the entire order lifecycle — creation, processing, capture, cancellation, refund — as well as fine-grained transaction management and search with pagination. After configuring your access token on MercadoPagoConfig, every operation returns a typed Order or OrderTransaction resource.
Setting up
import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.order.OrderClient;
MercadoPagoConfig.setAccessToken("APP_USR-your-access-token");
OrderClient client = new OrderClient();
Creating an order
Build an OrderCreateRequest with the order type, total amount, payer details, and the list of payment transactions you want to execute.
Build the payer
import com.mercadopago.client.order.OrderPayerRequest;
OrderPayerRequest payer = OrderPayerRequest.builder()
.email("buyer@example.com")
.firstName("Jane")
.lastName("Smith")
.build();
Build the payment transactions
import com.mercadopago.client.order.OrderPaymentRequest;
import com.mercadopago.client.order.OrderPaymentMethodRequest;
import com.mercadopago.client.order.OrderTransactionRequest;
import java.util.Arrays;
OrderPaymentRequest payment = OrderPaymentRequest.builder()
.amount("350.00")
.paymentMethod(OrderPaymentMethodRequest.builder()
.id("visa")
.type("credit_card")
.token("card-token-from-frontend") // generated by MercadoPago.js
.installments(1)
.statementDescriptor("MYSTORE")
.build())
.build();
OrderTransactionRequest transactions = OrderTransactionRequest.builder()
.payments(Arrays.asList(payment))
.build();
Build and submit the order
import com.mercadopago.client.order.OrderCreateRequest;
import com.mercadopago.resources.order.Order;
import com.mercadopago.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;
OrderCreateRequest request = OrderCreateRequest.builder()
.type("online")
.processingMode("automatic")
.totalAmount("350.00")
.externalReference("order-001")
.description("Premium plan subscription")
.payer(payer)
.transactions(transactions)
.build();
try {
Order order = client.create(request);
System.out.println("Order ID : " + order.getId());
System.out.println("Status : " + order.getStatus());
System.out.println("Total amount : " + order.getTotalAmount());
} catch (MPApiException ex) {
System.out.printf("API error %d: %s%n",
ex.getApiResponse().getStatusCode(),
ex.getApiResponse().getContent());
} catch (MPException ex) {
ex.printStackTrace();
}
Supply an X-Idempotency-Key header via MPRequestOptions when creating orders to guarantee safe retries. See the Per-request options section at the bottom of this page.
Processing an order
Calling process() triggers payment execution for all pending transactions in the order. Use this step when processingMode is set to "manual" and you want to explicitly start payment collection after reviewing the order.
Order processed = client.process(order.getId());
System.out.println("Status : " + processed.getStatus());
System.out.println("Status detail : " + processed.getStatusDetail());
Getting an order
Retrieve the latest state of an order by its string ID.
Order order = client.get("01JXXXXXXXXXXXXXXXXXXXXXXXXX");
System.out.println("Status : " + order.getStatus());
System.out.println("Total paid : " + order.getTotalPaidAmount());
System.out.println("Checkout URL : " + order.getCheckoutUrl());
Cancelling an order
Cancel an order that has not yet been completed or fully paid. The returned Order reflects the cancelled status.
Order cancelled = client.cancel("01JXXXXXXXXXXXXXXXXXXXXXXXXX");
System.out.println("New status: " + cancelled.getStatus()); // "cancelled"
Only orders that are still open (not yet fully processed or captured) can be cancelled. Already-paid orders must be handled through refunds.
Capturing an order
When an order’s payments were authorized but not yet settled (e.g., captureMode is "manual"), call capture() to settle all transactions at once.
Order captured = client.capture("01JXXXXXXXXXXXXXXXXXXXXXXXXX");
System.out.println("Status : " + captured.getStatus());
System.out.println("Status detail : " + captured.getStatusDetail());
Refunding an order
Total refund
Refund all payments on an order in a single call.
Order refunded = client.refund("01JXXXXXXXXXXXXXXXXXXXXXXXXX");
System.out.println("Status: " + refunded.getStatus());
Partial refund
Specify individual payment IDs and the amount to return for each.
import com.mercadopago.client.order.OrderRefundRequest;
import com.mercadopago.client.order.OrderRefundPaymentRequest;
import java.util.Arrays;
OrderRefundRequest refundRequest = OrderRefundRequest.builder()
.transactions(Arrays.asList(
OrderRefundPaymentRequest.builder()
.id("payment-transaction-id-1")
.amount("100.00")
.build()
))
.build();
Order partialRefund = client.refund("01JXXXXXXXXXXXXXXXXXXXXXXXXX", refundRequest);
System.out.println("Status: " + partialRefund.getStatus());
Transaction management
Transactions represent the individual payment intents within an order. You can add, update, or remove them before the order is processed.
Create a transaction
import com.mercadopago.client.order.OrderTransactionRequest;
import com.mercadopago.client.order.OrderPaymentRequest;
import com.mercadopago.client.order.OrderPaymentMethodRequest;
import com.mercadopago.resources.order.OrderTransaction;
import java.util.Arrays;
OrderTransactionRequest txRequest = OrderTransactionRequest.builder()
.payments(Arrays.asList(
OrderPaymentRequest.builder()
.amount("150.00")
.paymentMethod(OrderPaymentMethodRequest.builder()
.id("master")
.type("credit_card")
.token("new-card-token")
.installments(3)
.build())
.build()
))
.build();
OrderTransaction transaction = client.createTransaction(
"01JXXXXXXXXXXXXXXXXXXXXXXXXX",
txRequest
);
System.out.println("Transaction response: " + transaction.getResponse().getStatusCode());
Update a transaction
Replace the payment method or amount on an existing transaction by passing an OrderPaymentRequest.
import com.mercadopago.client.order.OrderPaymentRequest;
import com.mercadopago.client.order.OrderPaymentMethodRequest;
import com.mercadopago.resources.order.UpdateOrderTransaction;
OrderPaymentRequest updateRequest = OrderPaymentRequest.builder()
.amount("200.00")
.paymentMethod(OrderPaymentMethodRequest.builder()
.id("visa")
.type("credit_card")
.token("updated-card-token")
.installments(1)
.build())
.build();
UpdateOrderTransaction updated = client.updateTransaction(
"01JXXXXXXXXXXXXXXXXXXXXXXXXX", // orderId
"transaction-id-001", // transactionId
updateRequest
);
System.out.println("Update status: " + updated.getResponse().getStatusCode());
Delete a transaction
Remove a transaction from an order before it is processed.
import com.mercadopago.resources.order.OrderTransaction;
OrderTransaction deleted = client.deleteTransaction(
"01JXXXXXXXXXXXXXXXXXXXXXXXXX",
"transaction-id-001"
);
System.out.println("Delete HTTP status: " + deleted.getResponse().getStatusCode());
Searching orders
Use MPSearchRequest to filter and paginate your order history.
import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.resources.order.OrderSearchResponse;
import java.util.HashMap;
import java.util.Map;
Map<String, Object> filters = new HashMap<>();
filters.put("status", "processed");
filters.put("external_reference", "order-001");
MPSearchRequest searchRequest = MPSearchRequest.builder()
.limit(20)
.offset(0)
.filters(filters)
.build();
OrderSearchResponse results = client.search(searchRequest);
System.out.println("Total results: " + results.getPaging().getTotal());
for (Order o : results.getData()) {
System.out.printf(" id=%-30s status=%s total=%s%n",
o.getId(), o.getStatus(), o.getTotalAmount());
}
offset by limit on each call.
Per-request options
Pass MPRequestOptions as the last argument to any OrderClient method to override the access token, supply an idempotency key, or tune timeouts for that single call.
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();
// Use with any client method
Order order = client.create(request, options);
Order processed = client.process(order.getId(), options);
Order captured = client.capture(order.getId(), options);
Order cancelled = client.cancel(order.getId(), options);
Always send an X-Idempotency-Key header when creating orders. This ensures that retrying a failed or timed-out request does not produce a duplicate order.