PaymentClient: Full Payment Lifecycle API Reference

PaymentClient is the primary entry point for the Mercado Pago Payments API (v1). It covers the complete payment lifecycle: creating payments, retrieving them by ID, cancelling pending payments, capturing authorized payments (full or partial), paginated search, and the full set of refund operations. Refund operations are internally delegated to PaymentRefundClient and exposed as convenience methods so you only ever need to interact with this single client. Package: com.mercadopago.client.payment

Constructors

`PaymentClient()`

Creates a PaymentClient using the default HTTP client configured via MercadoPagoConfig.

PaymentClient client = new PaymentClient();

`PaymentClient(MPHttpClient httpClient)`

Creates a PaymentClient with a custom HTTP client. An internal PaymentRefundClient is also initialised with the same HTTP client.

httpClient

MPHttpClient

required

The HTTP client implementation used to execute all requests.

PaymentClient client = new PaymentClient(customHttpClient);

Methods

`get` — Retrieve a payment by ID

public Payment get(Long id) throws MPException, MPApiException
public Payment get(Long id, MPRequestOptions requestOptions) throws MPException, MPApiException

Retrieves a single payment by its unique identifier.

Long

required

The unique identifier of the payment to retrieve.

requestOptions

MPRequestOptions

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

Returns: Payment — the requested payment object. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`create` — Create a payment

public Payment create(PaymentCreateRequest request) throws MPException, MPApiException
public Payment create(PaymentCreateRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Creates a new payment. The request must include at minimum transactionAmount, paymentMethodId, and payer.

request

PaymentCreateRequest

required

The payment creation request. Key fields:

Field	Type	Description
`transactionAmount`	`BigDecimal`	Total amount to charge.
`paymentMethodId`	`String`	Payment method identifier (e.g. `"visa"`, `"pix"`).
`payer`	`PaymentPayerRequest`	Payer details including email and identification.
`token`	`String`	Card token generated by the tokenization flow.
`installments`	`Integer`	Number of installments selected by the buyer.
`capture`	`Boolean`	`true` to capture immediately; `false` to only authorize/reserve.
`externalReference`	`String`	Your internal order or reference ID.
`notificationUrl`	`String`	Webhook URL for payment status change notifications.
`description`	`String`	Payment reason or item title.
`binaryMode`	`Boolean`	When `true`, only approved/rejected statuses are used.

requestOptions

MPRequestOptions

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

Returns: Payment — the created payment, including its assigned id and initial status. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`cancel` — Cancel a pending payment

public Payment cancel(Long id) throws MPException, MPApiException
public Payment cancel(Long id, MPRequestOptions requestOptions) throws MPException, MPApiException

Cancels a pending payment by setting its status to cancelled. Only payments that are currently in pending or in_process state can be cancelled.

Long

required

The unique identifier of the payment to cancel.

requestOptions

MPRequestOptions

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

Returns: Payment — the cancelled payment with updated status. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`capture` — Capture an authorized payment

Captures a payment that was previously authorized (created with capture = false). Overloads are provided for full capture and partial capture.

Full capture

public Payment capture(Long id) throws MPException, MPApiException
public Payment capture(Long id, MPRequestOptions requestOptions) throws MPException, MPApiException

Captures the full authorized amount.

Long

required

The unique identifier of the authorized payment to capture.

requestOptions

MPRequestOptions

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

Partial capture

public Payment capture(Long id, BigDecimal amount) throws MPException, MPApiException
public Payment capture(Long id, BigDecimal amount, MPRequestOptions requestOptions) throws MPException, MPApiException

Captures a specific amount. The captured amount must be less than or equal to the originally authorized amount.

Long

required

The unique identifier of the authorized payment to capture.

amount

BigDecimal

required

The amount to capture. Pass null to capture the full authorized amount.

requestOptions

MPRequestOptions

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

Returns: Payment — the updated payment with captured = true and the final transactionAmount. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`search` — Search payments with pagination

public MPResultsResourcesPage<Payment> search(MPSearchRequest request) throws MPException, MPApiException
public MPResultsResourcesPage<Payment> search(MPSearchRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

Searches for payments that match the specified filters and returns a paginated result page.

request

MPSearchRequest

required

Search parameters. Use MPSearchRequest.builder().filters(map).offset(0).limit(30).build() to configure filters such as status, external_reference, date_created.range, etc.

requestOptions

MPRequestOptions

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

Returns: MPResultsResourcesPage<Payment> — contains .getResults() (list of matching payments), .getPaging().getTotal(), .getPaging().getOffset(), and .getPaging().getLimit(). Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`refund` — Refund a payment

Creates a total or partial refund for a captured payment. These methods delegate to the internal PaymentRefundClient.

Total refund

public PaymentRefund refund(Long paymentId) throws MPException, MPApiException
public PaymentRefund refund(Long paymentId, MPRequestOptions requestOptions) throws MPException, MPApiException

Returns the full payment amount to the payer.

paymentId

Long

required

The unique identifier of the payment to refund in full.

requestOptions

MPRequestOptions

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

Partial refund

public PaymentRefund refund(Long paymentId, BigDecimal amount) throws MPException, MPApiException
public PaymentRefund refund(Long paymentId, BigDecimal amount, MPRequestOptions requestOptions) throws MPException, MPApiException

Returns a specific amount to the payer. Multiple partial refunds can be created until the full amount has been refunded.

paymentId

Long

required

The unique identifier of the payment to partially refund.

amount

BigDecimal

required

The amount to refund. Must be greater than zero and at most the remaining refundable amount.

requestOptions

MPRequestOptions

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

Returns: PaymentRefund — the created refund, including its id, amount, and status. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`getRefund` — Retrieve a specific refund

public PaymentRefund getRefund(Long paymentId, Long refundId) throws MPException, MPApiException
public PaymentRefund getRefund(Long paymentId, Long refundId, MPRequestOptions requestOptions) throws MPException, MPApiException

Retrieves a single refund by its ID within the context of a specific payment.

paymentId

Long

required

The unique identifier of the original payment.

refundId

Long

required

The unique identifier of the refund to retrieve.

requestOptions

MPRequestOptions

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

Returns: PaymentRefund — the requested refund object. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

`listRefunds` — List all refunds for a payment

public MPResourceList<PaymentRefund> listRefunds(Long paymentId) throws MPException, MPApiException
public MPResourceList<PaymentRefund> listRefunds(Long paymentId, MPRequestOptions requestOptions) throws MPException, MPApiException

Lists all refunds associated with a given payment.

paymentId

Long

required

The unique identifier of the payment whose refunds should be listed.

requestOptions

MPRequestOptions

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

Returns: MPResourceList<PaymentRefund> — contains .getResults() with all refunds for the payment. Throws: MPException on transport/SDK errors; MPApiException on non-2xx API responses.

Resource classes

`Payment` resource

Key fields returned by the API on the Payment object:

Long

Unique payment identifier assigned by Mercado Pago.

status

String

Current payment status: approved, pending, in_process, rejected, cancelled, refunded, charged_back.

statusDetail

String

Detailed explanation of the current status or rejection cause.

transactionAmount

BigDecimal

Total amount charged to the payer.

transactionAmountRefunded

BigDecimal

Total amount that has been refunded for this payment.

captured

boolean

true if the payment has been captured; false if only authorized/reserved.

paymentMethodId

String

Payment method used (e.g. visa, master, pix).

paymentTypeId

String

Type of the payment method: credit_card, debit_card, ticket, bank_transfer.

externalReference

String

Your system’s reference identifier passed at creation.

dateCreated

OffsetDateTime

Timestamp when the payment was created.

dateApproved

OffsetDateTime

Timestamp when the payment was approved.

pointOfInteraction

PaymentPointOfInteraction

Data about the payment origin context, including QR code or deep-link data for Pix payments.

`PaymentRefund` resource

Long

Unique identifier of this refund.

paymentId

Long

Identifier of the original payment that was refunded.

amount

BigDecimal

Amount returned to the payer.

status

String

Current refund status: approved, in_process.

dateCreated

OffsetDateTime

Timestamp when the refund was created.

Usage example

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.payment.PaymentClient;
import com.mercadopago.client.payment.PaymentCreateRequest;
import com.mercadopago.client.payment.PaymentPayerRequest;
import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.resources.payment.Payment;
import com.mercadopago.resources.payment.PaymentRefund;
import java.math.BigDecimal;
import java.util.Map;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

PaymentClient client = new PaymentClient();

// 1. Create a payment (card token flow)
PaymentCreateRequest createRequest = PaymentCreateRequest.builder()
    .transactionAmount(new BigDecimal("150.00"))
    .token("card_token_from_sdk")
    .paymentMethodId("visa")
    .installments(1)
    .payer(PaymentPayerRequest.builder()
        .email("buyer@example.com")
        .build())
    .externalReference("order-1234")
    .notificationUrl("https://your-site.com/webhooks/mp")
    .build();

Payment payment = client.create(createRequest);
System.out.println("Payment ID: " + payment.getId());
System.out.println("Status: " + payment.getStatus());

// 2. Retrieve the payment
Payment fetched = client.get(payment.getId());

// 3. Authorize-then-capture flow (two-step)
PaymentCreateRequest authRequest = PaymentCreateRequest.builder()
    .transactionAmount(new BigDecimal("200.00"))
    .token("card_token_from_sdk")
    .paymentMethodId("master")
    .installments(1)
    .capture(false)           // only authorize/reserve
    .payer(PaymentPayerRequest.builder().email("buyer@example.com").build())
    .build();

Payment authorized = client.create(authRequest);
Payment captured  = client.capture(authorized.getId());          // full capture
// Payment partialCap = client.capture(authorized.getId(), new BigDecimal("100.00")); // partial

// 4. Cancel a pending payment
Payment cancelled = client.cancel(authorized.getId());

// 5. Search payments
MPSearchRequest search = MPSearchRequest.builder()
    .filters(Map.of("status", "approved", "external_reference", "order-1234"))
    .offset(0)
    .limit(10)
    .build();
var page = client.search(search);
System.out.println("Total found: " + page.getPaging().getTotal());

// 6. Total refund
PaymentRefund totalRefund = client.refund(payment.getId());

// 7. Partial refund
PaymentRefund partialRefund = client.refund(payment.getId(), new BigDecimal("50.00"));

// 8. List all refunds for the payment
var refunds = client.listRefunds(payment.getId());
refunds.getResults().forEach(r -> System.out.println("Refund " + r.getId() + ": " + r.getAmount()));

Core

Clients

Exceptions & HTTP

PaymentClient: Full Payment Lifecycle API Reference

Constructors

`PaymentClient()`

`PaymentClient(MPHttpClient httpClient)`

Methods

`get` — Retrieve a payment by ID

`create` — Create a payment

`cancel` — Cancel a pending payment

`capture` — Capture an authorized payment

Full capture

Partial capture

`refund` — Refund a payment

Total refund

Partial refund

`getRefund` — Retrieve a specific refund

`listRefunds` — List all refunds for a payment

Resource classes

`Payment` resource

`PaymentRefund` resource

Usage example

Build docs developers (and LLMs) love

Core

Clients

Exceptions & HTTP

Documentation Index

​Constructors

​PaymentClient()

​PaymentClient(MPHttpClient httpClient)

​Methods

​get — Retrieve a payment by ID

​create — Create a payment

​cancel — Cancel a pending payment

​capture — Capture an authorized payment

​Full capture

​Partial capture

​search — Search payments with pagination

​refund — Refund a payment

​Total refund

​Partial refund

​getRefund — Retrieve a specific refund

​listRefunds — List all refunds for a payment

​Resource classes

​Payment resource

​PaymentRefund resource

​Usage example

Build docs developers (and LLMs) love

Constructors

`PaymentClient()`

`PaymentClient(MPHttpClient httpClient)`

Methods

`get` — Retrieve a payment by ID

`create` — Create a payment

`cancel` — Cancel a pending payment

`capture` — Capture an authorized payment

Full capture

Partial capture

`search` — Search payments with pagination

`refund` — Refund a payment

Total refund

Partial refund

`getRefund` — Retrieve a specific refund

`listRefunds` — List all refunds for a payment

Resource classes

`Payment` resource

`PaymentRefund` resource

Usage example