OrderClient: Java Orders API Reference for Mercado Pago

OrderClient is the entry point for the Mercado Pago Orders API (v1). An order is the top-level entity that groups one or more payment transactions, line items, payer information, and configuration options for online or point-of-sale checkout flows. The client exposes the complete order lifecycle — creation, retrieval, processing, cancellation, capture, and refund — as well as transaction management operations (create, update, delete individual transactions within an order) and paginated search. Package: com.mercadopago.client.order

Note: All methods that accept an orderId or transactionId parameter validate that the value is non-blank. A blank or null value throws IllegalArgumentException immediately, before any HTTP request is made.

Constructors

`OrderClient()`

Creates an OrderClient using the default HTTP client configured via MercadoPagoConfig.

OrderClient client = new OrderClient();

`OrderClient(MPHttpClient httpClient)`

Creates an OrderClient with a custom HTTP client.

httpClient

MPHttpClient

required

The HTTP client implementation used to execute all requests.

OrderClient client = new OrderClient(customHttpClient);

Methods

`create` — Create an order

public Order create(OrderCreateRequest request) throws MPException, MPApiException
public Order create(OrderCreateRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Creates a new order. After creation the order is in created state; call process to trigger payment execution.

request

OrderCreateRequest

required

The order creation request. Key fields:

Field	Type	Description
`type`	`String`	Order type: `"online"` or `"point"`.
`totalAmount`	`String`	Total amount as a decimal string (e.g. `"150.00"`).
`externalReference`	`String`	Your system’s reference identifier for this order.
`transactions`	`OrderTransactionRequest`	Transaction/payment details for the order.
`payer`	`OrderPayerRequest`	Payer information for the order.
`items`	`List<OrderItemRequest>`	Line items included in the checkout.
`captureMode`	`String`	`"automatic"` or `"manual"` capture mode.
`processingMode`	`String`	`"aggregator"` or `"gateway"` processing.
`description`	`String`	Short description of the order.
`expirationTime`	`String`	ISO 8601 duration or datetime for order expiry.
`config`	`OrderConfigRequest`	Payment method and checkout configuration options.

requestOptions

MPRequestOptions

Optional per-request overrides for access token, custom headers, or timeouts. Pass null to use global defaults.

Returns: Order — the created order, including id, status, and checkoutUrl. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`get` — Retrieve an order by ID

public Order get(String id) throws MPException, MPApiException
public Order get(String id, MPRequestOptions requestOptions) throws MPException, MPApiException

Retrieves a single order by its unique string identifier.

String

required

The unique identifier of the order. Must not be blank or null.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: Order — the requested order. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses; IllegalArgumentException if id is blank or null.

`process` — Process an order

public Order process(String id) throws MPException, MPApiException
public Order process(String id, MPRequestOptions requestOptions) throws MPException, MPApiException

Triggers payment execution for the order’s transactions. The order must be in created status before calling this method.

String

required

The unique identifier of the order to process. Must not be blank or null.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: Order — the order with updated status reflecting the payment outcome. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses; IllegalArgumentException if id is blank or null.

`cancel` — Cancel an order

public Order cancel(String orderId) throws MPException, MPApiException
public Order cancel(String orderId, MPRequestOptions requestOptions) throws MPException, MPApiException

Cancels an order. The order must not yet be fully captured or refunded.

orderId

String

required

The unique identifier of the order to cancel. Must not be blank or null.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: Order — the cancelled order with updated status. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses; IllegalArgumentException if orderId is blank or null.

`capture` — Capture an authorized order

public Order capture(String orderId) throws MPException, MPApiException
public Order capture(String orderId, MPRequestOptions requestOptions) throws MPException, MPApiException

Captures a previously authorized order (created with captureMode = "manual"), settling all its payments.

orderId

String

required

The unique identifier of the order to capture. Must not be blank or null.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: Order — the captured order with updated status. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses; IllegalArgumentException if orderId is blank or null.

`refund` — Refund an order

Refunds all or part of an order’s payments. If no OrderRefundRequest is provided, a total refund is performed.

Total refund

public Order refund(String orderId) throws MPException, MPApiException
public Order refund(String orderId, MPRequestOptions requestOptions) throws MPException, MPApiException

Refunds all transactions in the order.

orderId

String

required

The unique identifier of the order to refund. Must not be blank or null.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Partial refund

public Order refund(String orderId, OrderRefundRequest request) throws MPException, MPApiException
public Order refund(String orderId, OrderRefundRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Refunds specific transactions or amounts within the order.

orderId

String

required

The unique identifier of the order to partially refund. Must not be blank or null.

request

OrderRefundRequest

required

Refund details. Contains a transactions field — a list of OrderRefundPaymentRequest objects each specifying the payment ID and refund amount. Pass null to perform a total refund.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: Order — the order with updated status and transaction refund state. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses; IllegalArgumentException if orderId is blank or null.

`createTransaction` — Add a transaction to an order

public OrderTransaction createTransaction(String orderId, OrderTransactionRequest request) throws MPException, MPApiException
public OrderTransaction createTransaction(String orderId, OrderTransactionRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Creates a new payment transaction within an existing order. Use this to add a payment method to an order before calling process.

orderId

String

required

The unique identifier of the order to add a transaction to.

request

OrderTransactionRequest

required

Transaction details including payment method, amount, and payer information.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: OrderTransaction — the created transaction object. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`updateTransaction` — Update a transaction in an order

public UpdateOrderTransaction updateTransaction(String orderId, String transactionId, OrderPaymentRequest request) throws MPException, MPApiException
public UpdateOrderTransaction updateTransaction(String orderId, String transactionId, OrderPaymentRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Updates an existing transaction within an order, for example to change its payment method or amount.

orderId

String

required

The unique identifier of the order. Must not be blank or null.

transactionId

String

required

The unique identifier of the transaction to update. Must not be blank or null.

request

OrderPaymentRequest

required

The updated transaction/payment details.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: UpdateOrderTransaction — the updated transaction result. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses; IllegalArgumentException if orderId or transactionId is blank or null.

`deleteTransaction` — Delete a transaction from an order

public OrderTransaction deleteTransaction(String orderId, String transactionId) throws MPException, MPApiException
public OrderTransaction deleteTransaction(String orderId, String transactionId, MPRequestOptions requestOptions) throws MPException, MPApiException

Removes a transaction from an order. The returned OrderTransaction object holds the API response but no body content.

orderId

String

required

The unique identifier of the order. Must not be blank or null.

transactionId

String

required

The unique identifier of the transaction to delete. Must not be blank or null.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: OrderTransaction — an object whose getResponse() holds the raw API response (typically a 204 No Content). Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses; IllegalArgumentException if either ID is blank or null.

`search` — Search orders with pagination

public OrderSearchResponse search(MPSearchRequest request) throws MPException, MPApiException
public OrderSearchResponse search(MPSearchRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Searches for orders matching the specified filters and returns a paginated response.

request

MPSearchRequest

required

Search parameters. Build with MPSearchRequest.builder().filters(map).offset(0).limit(20).build(). Common filters include external_reference, status, user_id.

requestOptions

MPRequestOptions

Optional per-request overrides. Pass null to use global defaults.

Returns: OrderSearchResponse — contains matching orders and pagination metadata. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

Resource classes

`Order` resource

Key fields on the Order object returned by the API:

String

Unique identifier of the order.

status

String

Current order status: created, processed, expired, cancelled.

statusDetail

String

Sub-status providing additional context about the current order status.

totalAmount

String

Total order amount as a decimal string.

totalPaidAmount

String

Total amount already paid on this order.

externalReference

String

Your system’s reference ID for this order.

checkoutUrl

String

URL to redirect the buyer to the checkout flow. Generated at creation.

captureMode

String

Capture mode: automatic or manual.

transactions

OrderTransaction

Transaction details including payments, refunds, and chargebacks.

items

List<OrderItem>

Line items included in the order.

payer

OrderPayer

Payer information associated with the order.

createdDate

String

ISO 8601 timestamp when the order was created.

Usage example

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.order.OrderClient;
import com.mercadopago.client.order.OrderCreateRequest;
import com.mercadopago.client.order.OrderRefundRequest;
import com.mercadopago.client.order.OrderRefundPaymentRequest;
import com.mercadopago.resources.order.Order;
import java.util.List;
import java.util.Map;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

OrderClient client = new OrderClient();

// 1. Create an order
OrderCreateRequest createRequest = OrderCreateRequest.builder()
    .type("online")
    .totalAmount("250.00")
    .externalReference("my-order-9876")
    .description("Premium subscription")
    .captureMode("automatic")
    .processingMode("aggregator")
    .build();

Order order = client.create(createRequest);
System.out.println("Order ID: " + order.getId());
System.out.println("Checkout URL: " + order.getCheckoutUrl());

// 2. Process the order (triggers payment execution)
Order processed = client.process(order.getId());
System.out.println("Status after process: " + processed.getStatus());

// 3. Retrieve the order
Order fetched = client.get(order.getId());

// 4. Cancel the order
Order cancelled = client.cancel(order.getId());

// 5. Capture a manually-authorized order
Order captured = client.capture(order.getId());

// 6. Total refund
Order refunded = client.refund(order.getId());

// 7. Partial refund targeting specific transactions
OrderRefundRequest refundRequest = OrderRefundRequest.builder()
    .transactions(List.of(
        OrderRefundPaymentRequest.builder()
            .paymentId("TXN_ID")
            .amount("100.00")
            .build()
    ))
    .build();
Order partialRefund = client.refund(order.getId(), refundRequest);

// 8. Search orders
var results = client.search(
    MPSearchRequest.builder()
        .filters(Map.of("external_reference", "my-order-9876"))
        .offset(0)
        .limit(10)
        .build()
);
System.out.println("Found: " + results.getData().size() + " order(s)");

Core

Clients

Exceptions & HTTP

OrderClient: Java Orders API Reference for Mercado Pago

Constructors

`OrderClient()`

`OrderClient(MPHttpClient httpClient)`

Methods

`create` — Create an order

`get` — Retrieve an order by ID

`process` — Process an order

`cancel` — Cancel an order

`capture` — Capture an authorized order

`refund` — Refund an order

Total refund

Partial refund

`createTransaction` — Add a transaction to an order

`updateTransaction` — Update a transaction in an order

`deleteTransaction` — Delete a transaction from an order

Resource classes

`Order` resource

Usage example

Build docs developers (and LLMs) love

Core

Clients

Exceptions & HTTP

Documentation Index

​Constructors

​OrderClient()

​OrderClient(MPHttpClient httpClient)

​Methods

​create — Create an order

​get — Retrieve an order by ID

​process — Process an order

​cancel — Cancel an order

​capture — Capture an authorized order

​refund — Refund an order

​Total refund

​Partial refund

​createTransaction — Add a transaction to an order

​updateTransaction — Update a transaction in an order

​deleteTransaction — Delete a transaction from an order

​search — Search orders with pagination

​Resource classes

​Order resource

​Usage example

Build docs developers (and LLMs) love

Constructors

`OrderClient()`

`OrderClient(MPHttpClient httpClient)`

Methods

`create` — Create an order

`get` — Retrieve an order by ID

`process` — Process an order

`cancel` — Cancel an order

`capture` — Capture an authorized order

`refund` — Refund an order

Total refund

Partial refund

`createTransaction` — Add a transaction to an order

`updateTransaction` — Update a transaction in an order

`deleteTransaction` — Delete a transaction from an order

`search` — Search orders with pagination

Resource classes

`Order` resource

Usage example