Mercado Pago Additional SDK Client Classes Reference

The Mercado Pago Java SDK includes several ancillary clients that cover utility and platform-support operations such as retrieving identification document types, listing available payment methods, querying chargebacks, and managing merchant orders. This page documents each of these clients concisely, grouped by purpose.

MerchantOrderClient

Package: com.mercadopago.client.merchantorder MerchantOrderClient manages merchant orders, which group one or more payments and can be linked to a checkout preference, shipment, or external reference. They are commonly used in marketplace-style flows to track fulfilment and associate multiple payment attempts with a single purchase event.

Constructors

MerchantOrderClient()
MerchantOrderClient(MPHttpClient httpClient)

Methods

Signature	Description
`MerchantOrder get(Long id)`	Retrieve a merchant order by ID.
`MerchantOrder get(Long id, MPRequestOptions)`	Same with custom request options.
`MerchantOrder create(MerchantOrderCreateRequest)`	Create a new merchant order.
`MerchantOrder create(MerchantOrderCreateRequest, MPRequestOptions)`	Same with custom request options.
`MerchantOrder update(Long id, MerchantOrderUpdateRequest)`	Update an existing merchant order.
`MerchantOrder update(Long id, MerchantOrderUpdateRequest, MPRequestOptions)`	Same with custom request options.
`MPElementsResourcesPage<MerchantOrder> search(MPSearchRequest)`	Search merchant orders with pagination.
`MPElementsResourcesPage<MerchantOrder> search(MPSearchRequest, MPRequestOptions)`	Same with custom request options.

All methods throw MPException and MPApiException.

MerchantOrderCreateRequest key fields

preferenceId

String

Checkout preference ID that links this order to a payment preference.

siteId

String

Mercado Libre site ID (e.g., "MLA" for Argentina, "MLB" for Brazil).

items

List<MerchantOrderItemRequest>

List of items included in the order.

payer

MerchantOrderPayerRequest

Buyer information.

externalReference

String

External reference to correlate with your own system.

notificationUrl

String

Webhook URL for order and payment status notifications.

applicationId

String

Application ID for marketplace integrations.

ChargebackClient

Package: com.mercadopago.client.chargeback ChargebackClient provides read-only access to chargeback dispute records — cases where a cardholder has disputed a charge with their issuing bank. This client is used to retrieve the details of a specific chargeback or search for chargebacks matching given criteria so that your system can trigger internal dispute-handling workflows.

Constructors

ChargebackClient()
ChargebackClient(MPHttpClient httpClient)

Methods

Signature	Description
`Chargeback get(String id)`	Retrieve a chargeback by its ID.
`Chargeback get(String id, MPRequestOptions)`	Same with custom request options.
`MPResultsResourcesPage<Chargeback> search(MPSearchRequest)`	Search chargebacks with pagination.
`MPResultsResourcesPage<Chargeback> search(MPSearchRequest, MPRequestOptions)`	Same with custom request options.

All methods throw MPException and MPApiException.

InvoiceClient

Package: com.mercadopago.client.invoice InvoiceClient retrieves invoices (also called authorized payments) that are generated by Mercado Pago’s subscription (preapproval) engine. Each invoice represents a scheduled billing attempt against a subscriber’s saved payment method for a given billing cycle. The API endpoint is /authorized_payments/{id}.

Constructors

InvoiceClient()
InvoiceClient(MPHttpClient httpClient)

Methods

Signature	Description
`Invoice get(Long id)`	Retrieve an invoice by its numeric ID.
`Invoice get(Long id, MPRequestOptions)`	Same with custom request options.
`MPResultsResourcesPage<Invoice> search(MPSearchRequest)`	Search invoices (e.g., by `preapproval_id` or `payer_id`).
`MPResultsResourcesPage<Invoice> search(MPSearchRequest, MPRequestOptions)`	Same with custom request options.

All methods throw MPException and MPApiException.

IdentificationTypeClient

Package: com.mercadopago.client.identificationtype IdentificationTypeClient lists the identification document types recognized by Mercado Pago for the country associated with the authenticated user’s credentials. Common examples include CPF and CNPJ (Brazil) and DNI and CUIL (Argentina). These type IDs are required when creating customers or providing payer identification in payment requests.

Constructors

IdentificationTypeClient()
IdentificationTypeClient(MPHttpClient httpClient)

Methods

Signature	Description
`MPResourceList<IdentificationType> list()`	List all identification types for the authenticated user’s country.
`MPResourceList<IdentificationType> list(MPRequestOptions)`	Same with custom request options.

All methods throw MPException and MPApiException.

UserClient

Package: com.mercadopago.client.user UserClient retrieves information about the currently authenticated Mercado Pago user — typically the account associated with the access token in use. It is used internally by OauthClient to determine the seller’s country when building authorization URLs, but can also be called directly to inspect account details such as countryId and siteId.

Constructors

UserClient()
UserClient(MPHttpClient httpClient)

Methods

Signature	Description
`User get()`	Retrieve information about the authenticated user (`/users/me`).
`User get(MPRequestOptions)`	Same with custom request options (e.g., a seller’s access token).

All methods throw MPException and MPApiException.

PaymentMethodClient

Package: com.mercadopago.client.paymentmethod PaymentMethodClient lists all payment methods available for the country associated with the authenticated user’s credentials. Results include credit cards, debit cards, bank transfers, and cash payment networks. The id field of each PaymentMethod is the value required in paymentMethodId when creating payments or card tokens.

Constructors

PaymentMethodClient()
PaymentMethodClient(MPHttpClient httpClient)

Methods

Signature	Description
`MPResourceList<PaymentMethod> list()`	List all available payment methods.
`MPResourceList<PaymentMethod> list(MPRequestOptions)`	Same with custom request options.

All methods throw MPException and MPApiException.

DisbursementRefundClient

Package: com.mercadopago.client.disbursementrefund DisbursementRefundClient enables partial or full refunds of individual disbursements within an advanced (split) payment. It is used alongside AdvancedPaymentClient. Two operations are available: refund a single disbursement by specifying both the advancedPaymentId and disbursementId, or refund all disbursements at once using the bulk endpoint.

Constructors

DisbursementRefundClient()
DisbursementRefundClient(MPHttpClient httpClient)

Methods

Signature	Description
`DisbursementRefund create(Long advancedPaymentId, Long disbursementId, DisbursementRefundCreateRequest)`	Refund a specific disbursement by amount.
`DisbursementRefund create(Long advancedPaymentId, Long disbursementId, DisbursementRefundCreateRequest, MPRequestOptions)`	Same with custom request options.
`DisbursementRefund createAll(Long advancedPaymentId, DisbursementRefundCreateRequest)`	Refund all disbursements of an advanced payment at once.
`DisbursementRefund createAll(Long advancedPaymentId, DisbursementRefundCreateRequest, MPRequestOptions)`	Same with custom request options.

All methods throw MPException and MPApiException.

DisbursementRefundCreateRequest fields

amount

BigDecimal

Amount to refund. When null, the full disbursement amount is refunded.

Code Examples

IdentificationTypeClient

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.identificationtype.IdentificationTypeClient;
import com.mercadopago.net.MPResourceList;
import com.mercadopago.resources.identificationtype.IdentificationType;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

IdentificationTypeClient client = new IdentificationTypeClient();
MPResourceList<IdentificationType> types = client.list();

types.getResults().forEach(t ->
    System.out.printf("ID: %-10s  Name: %s%n", t.getId(), t.getName())
);
// Example output:
// ID: CPF        Name: CPF
// ID: CNPJ       Name: CNPJ

PaymentMethodClient

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.paymentmethod.PaymentMethodClient;
import com.mercadopago.net.MPResourceList;
import com.mercadopago.resources.paymentmethod.PaymentMethod;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

PaymentMethodClient client = new PaymentMethodClient();
MPResourceList<PaymentMethod> methods = client.list();

methods.getResults().forEach(m ->
    System.out.printf("ID: %-20s  Type: %-15s  Name: %s%n",
        m.getId(), m.getPaymentTypeId(), m.getName())
);
// Example output:
// ID: visa                 Type: credit_card      Name: Visa
// ID: pix                  Type: bank_transfer    Name: Pix
// ID: bolbradesco          Type: ticket           Name: Boleto Bancário

MerchantOrderClient

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.merchantorder.MerchantOrderClient;
import com.mercadopago.client.merchantorder.MerchantOrderCreateRequest;
import com.mercadopago.client.merchantorder.MerchantOrderItemRequest;
import com.mercadopago.resources.merchantorder.MerchantOrder;

import java.math.BigDecimal;
import java.util.Collections;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

MerchantOrderClient orderClient = new MerchantOrderClient();

MerchantOrderCreateRequest createRequest = MerchantOrderCreateRequest.builder()
    .siteId("MLB")
    .externalReference("my-order-001")
    .items(Collections.singletonList(
        MerchantOrderItemRequest.builder()
            .title("Widget")
            .quantity(2)
            .unitPrice(new BigDecimal("49.99"))
            .build()
    ))
    .build();

MerchantOrder order = orderClient.create(createRequest);
System.out.println("Order ID: " + order.getId());

// Retrieve by ID
MerchantOrder retrieved = orderClient.get(order.getId());
System.out.println("Status: " + retrieved.getStatus());

DisbursementRefundClient

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.disbursementrefund.DisbursementRefundClient;
import com.mercadopago.client.disbursementrefund.DisbursementRefundCreateRequest;
import com.mercadopago.resources.disbursementrefund.DisbursementRefund;

import java.math.BigDecimal;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

DisbursementRefundClient refundClient = new DisbursementRefundClient();

// Partial refund of a single disbursement
DisbursementRefundCreateRequest partialRefund = DisbursementRefundCreateRequest.builder()
    .amount(new BigDecimal("50.00"))
    .build();
DisbursementRefund refund = refundClient.create(123456789L, 987654321L, partialRefund);
System.out.println("Refund ID: " + refund.getId());

// Full refund of all disbursements (omit amount for full refund)
DisbursementRefundCreateRequest fullRefund = DisbursementRefundCreateRequest.builder().build();
DisbursementRefund bulkRefund = refundClient.createAll(123456789L, fullRefund);
System.out.println("Bulk refund ID: " + bulkRefund.getId());

Core

Clients

Exceptions & HTTP

Mercado Pago Additional SDK Client Classes Reference

MerchantOrderClient

Constructors

Methods

MerchantOrderCreateRequest key fields

ChargebackClient

Constructors

Methods

InvoiceClient

Constructors

Methods

IdentificationTypeClient

Constructors

Methods

UserClient

Constructors

Methods

PaymentMethodClient

Constructors

Methods

DisbursementRefundClient

Constructors

Methods

DisbursementRefundCreateRequest fields

Code Examples

IdentificationTypeClient

PaymentMethodClient

MerchantOrderClient

DisbursementRefundClient

Build docs developers (and LLMs) love

Core

Clients

Exceptions & HTTP

Documentation Index

​MerchantOrderClient

​Constructors

​Methods

​MerchantOrderCreateRequest key fields

​ChargebackClient

​Constructors

​Methods

​InvoiceClient

​Constructors

​Methods

​IdentificationTypeClient

​Constructors

​Methods

​UserClient

​Constructors

​Methods

​PaymentMethodClient

​Constructors

​Methods

​DisbursementRefundClient

​Constructors

​Methods

​DisbursementRefundCreateRequest fields

​Code Examples

​IdentificationTypeClient

​PaymentMethodClient

​MerchantOrderClient

​DisbursementRefundClient

Build docs developers (and LLMs) love

MerchantOrderClient

Constructors

Methods

MerchantOrderCreateRequest key fields

ChargebackClient

Constructors

Methods

InvoiceClient

Constructors

Methods

IdentificationTypeClient

Constructors

Methods

UserClient

Constructors

Methods

PaymentMethodClient

Constructors

Methods

DisbursementRefundClient

Constructors

Methods

DisbursementRefundCreateRequest fields

Code Examples

IdentificationTypeClient

PaymentMethodClient

MerchantOrderClient

DisbursementRefundClient