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.
AdvancedPaymentClient is the entry point for Mercado Pago’s Advanced Payments (split-payment) API, which enables marketplace platforms to collect a single payment from a buyer and distribute funds among multiple sellers (disbursements) simultaneously. The client supports two-step flows — authorize then capture — and provides fine-grained control over when individual disbursements are released to sellers. For disbursement-level refunds, use DisbursementRefundClient.
AdvancedPaymentClient
Package: com.mercadopago.client.advancedpayment
Constructors
// Uses the default HTTP client configured in MercadoPagoConfig
AdvancedPaymentClient()
// Supply a custom MPHttpClient (useful for testing or proxy scenarios)
AdvancedPaymentClient(MPHttpClient httpClient)
Methods
create
Creates a new advanced (split) payment.
AdvancedPayment create(AdvancedPaymentCreateRequest request) throws MPException, MPApiException
AdvancedPayment create(AdvancedPaymentCreateRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException
request
AdvancedPaymentCreateRequest
required
Optional per-request overrides for access token, headers, or timeouts. Pass null to use defaults.
AdvancedPayment
get
Retrieves an advanced payment by its unique identifier.
AdvancedPayment get(Long id) throws MPException, MPApiException
AdvancedPayment get(Long id, MPRequestOptions requestOptions) throws MPException, MPApiException
Unique numeric identifier of the advanced payment.
Optional per-request overrides.
AdvancedPayment
search
Searches for advanced payments matching the specified criteria.
MPResultsResourcesPage<AdvancedPayment> search(MPSearchRequest request) throws MPException, MPApiException
MPResultsResourcesPage<AdvancedPayment> search(MPSearchRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException
Search filters and pagination parameters (e.g., external_reference, status, offset, limit).
Optional per-request overrides.
MPResultsResourcesPage<AdvancedPayment>
capture
Captures a previously authorized (uncaptured) advanced payment. Only applicable when the payment was created with capture = false.
AdvancedPayment capture(Long id) throws MPException, MPApiException
AdvancedPayment capture(Long id, MPRequestOptions requestOptions) throws MPException, MPApiException
Unique identifier of the authorized payment to capture.
Optional per-request overrides.
AdvancedPayment
cancel
Cancels an advanced payment, setting its status to cancelled. Works for both authorized-only and approved payments depending on their current state.
AdvancedPayment cancel(Long id) throws MPException, MPApiException
AdvancedPayment cancel(Long id, MPRequestOptions requestOptions) throws MPException, MPApiException
Unique identifier of the advanced payment to cancel.
Optional per-request overrides.
AdvancedPayment
updateReleaseDate
Changes the money release date for all disbursements of an advanced payment. Use this to defer or accelerate when the seller receives their funds.
AdvancedPayment updateReleaseDate(Long id, String releaseDate) throws MPException, MPApiException
AdvancedPayment updateReleaseDate(Long id, String releaseDate, MPRequestOptions requestOptions) throws MPException, MPApiException
Unique identifier of the advanced payment.
New release date in ISO 8601 format (e.g., "2025-12-31T00:00:00.000Z").
Optional per-request overrides.
AdvancedPayment
AdvancedPaymentCreateRequest fields
AdvancedPaymentCreateRequest is a Lombok @Builder class with the following fields:
payments
List<AdvancedPaymentPaymentRequest>
required
List of payment sources — each entry specifies a card token and the transaction amount.
disbursements
List<AdvancedPaymentDisbursementRequest>
required
List of receivers — each entry specifies a collector (seller) ID and the amount they will receive.
payer
AdvancedPaymentPayerRequest
Buyer information (email, identification, etc.).
Mercado Pago application identifier for your marketplace integration.
Human-readable description shown to the payer.
Integrator-provided reference to correlate this payment with your own system.
When false, creates an authorized but uncaptured payment (two-step flow). Defaults to true.
When true, the payment is either fully approved or rejected — no pending state.
Disbursement Refunds
To refund an individual disbursement within an advanced payment, use DisbursementRefundClient:
// Refund a specific disbursement
DisbursementRefundClient refundClient = new DisbursementRefundClient();
DisbursementRefundCreateRequest refundRequest = DisbursementRefundCreateRequest.builder()
.amount(new BigDecimal("50.00")) // omit for a full refund
.build();
DisbursementRefund refund = refundClient.create(advancedPaymentId, disbursementId, refundRequest);
// Refund all disbursements at once
DisbursementRefund bulkRefund = refundClient.createAll(advancedPaymentId, refundRequest);
DisbursementRefundClient for full details.
Code Example
import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.advancedpayment.AdvancedPaymentClient;
import com.mercadopago.client.advancedpayment.AdvancedPaymentCreateRequest;
import com.mercadopago.client.advancedpayment.AdvancedPaymentDisbursementRequest;
import com.mercadopago.client.advancedpayment.AdvancedPaymentPayerRequest;
import com.mercadopago.client.advancedpayment.AdvancedPaymentPaymentRequest;
import com.mercadopago.net.MPResultsResourcesPage;
import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.resources.advancedpayment.AdvancedPayment;
import java.math.BigDecimal;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
MercadoPagoConfig.setAccessToken("YOUR_MARKETPLACE_ACCESS_TOKEN");
AdvancedPaymentClient client = new AdvancedPaymentClient();
// Build the create request for a split payment between two sellers
AdvancedPaymentCreateRequest createRequest = AdvancedPaymentCreateRequest.builder()
.payments(Arrays.asList(
AdvancedPaymentPaymentRequest.builder()
.token("card_token_from_frontend")
.transactionAmount(new BigDecimal("200.00"))
.installments(1)
.paymentMethodId("visa")
.build()
))
.disbursements(Arrays.asList(
AdvancedPaymentDisbursementRequest.builder()
.collectorId(123456789L)
.amount(new BigDecimal("120.00"))
.externalReference("seller-a-order-001")
.build(),
AdvancedPaymentDisbursementRequest.builder()
.collectorId(987654321L)
.amount(new BigDecimal("80.00"))
.externalReference("seller-b-order-001")
.build()
))
.payer(AdvancedPaymentPayerRequest.builder()
.email("buyer@example.com")
.build())
.externalReference("marketplace-order-XYZ")
.description("Marketplace purchase — two sellers")
.capture(false) // authorize only; capture later
.build();
AdvancedPayment payment = client.create(createRequest);
System.out.println("Advanced payment ID: " + payment.getId());
System.out.println("Status: " + payment.getStatus());
// Capture the authorized payment
AdvancedPayment captured = client.capture(payment.getId());
System.out.println("Captured status: " + captured.getStatus());
// Defer the release date for all disbursements
AdvancedPayment updated = client.updateReleaseDate(payment.getId(), "2025-12-31T00:00:00.000Z");
// Search by external reference
Map<String, Object> filters = new HashMap<>();
filters.put("external_reference", "marketplace-order-XYZ");
MPSearchRequest searchRequest = MPSearchRequest.builder()
.filters(filters)
.limit(5)
.offset(0)
.build();
MPResultsResourcesPage<AdvancedPayment> results = client.search(searchRequest);