Marketplace Split Payments with Advanced Payments API

The Mercado Pago Advanced Payments API is designed for marketplace platforms that need to collect a single payment from a buyer and automatically distribute funds to one or more sellers in a single API call. Each portion of the payment destined for a specific seller is called a disbursement. The platform can retain a marketplace fee (applicationFee) from each disbursement, schedule a future release date for funds, and — if needed — use a two-step authorize-then-capture flow to hold funds before confirming the transaction. The AdvancedPaymentClient class in the Java SDK covers the full lifecycle: create, get, search, capture, cancel, update release date, and disburse refunds via DisbursementRefundClient.

Set your access token once at application startup before using any client:

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

Creating an Advanced Payment

An AdvancedPaymentCreateRequest groups three key building blocks:

payments — one or more AdvancedPaymentPaymentRequest objects describing the payment source (card token, method, amount, installments).
disbursements — a list of AdvancedPaymentDisbursementRequest objects, one per seller receiving funds.
payer — an AdvancedPaymentPayerRequest identifying the buyer.

One-step (immediate capture)

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.resources.advancedpayment.AdvancedPayment;
import java.math.BigDecimal;
import java.util.Arrays;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

AdvancedPaymentClient client = new AdvancedPaymentClient();

AdvancedPaymentCreateRequest request = AdvancedPaymentCreateRequest.builder()
    .applicationId("{{APPLICATION_ID}}")
    .description("Marketplace order #1234")
    .externalReference("ADV-REF-1234")
    .capture(true) // immediate capture
    .binaryMode(false)
    .payments(Arrays.asList(
        AdvancedPaymentPaymentRequest.builder()
            .paymentMethodId("master")
            .paymentTypeId("credit_card")
            .token("{{CARD_TOKEN}}")
            .transactionAmount(new BigDecimal("150.00"))
            .installments(1)
            .processingMode("aggregator")
            .build()
    ))
    .disbursements(Arrays.asList(
        AdvancedPaymentDisbursementRequest.builder()
            .collectorId(111111111L)           // seller A
            .amount(new BigDecimal("100.00"))
            .applicationFee(new BigDecimal("5.00"))
            .externalReference("SELLER-A-REF")
            .build(),
        AdvancedPaymentDisbursementRequest.builder()
            .collectorId(222222222L)           // seller B
            .amount(new BigDecimal("50.00"))
            .applicationFee(new BigDecimal("2.50"))
            .externalReference("SELLER-B-REF")
            .build()
    ))
    .payer(AdvancedPaymentPayerRequest.builder()
        .email("buyer@example.com")
        .firstName("John")
        .lastName("Buyer")
        .build())
    .build();

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

Two-step (authorize then capture)

Set capture(false) to authorise the payment without moving funds. Call client.capture(id) later when you are ready to settle.

AdvancedPaymentCreateRequest request = AdvancedPaymentCreateRequest.builder()
    .applicationId("{{APPLICATION_ID}}")
    .description("Marketplace order #5678 – hold")
    .externalReference("ADV-REF-5678")
    .capture(false) // authorise only
    .payments(Arrays.asList(
        AdvancedPaymentPaymentRequest.builder()
            .paymentMethodId("master")
            .paymentTypeId("credit_card")
            .token("{{CARD_TOKEN}}")
            .transactionAmount(new BigDecimal("100.00"))
            .installments(1)
            .processingMode("aggregator")
            .build()
    ))
    .disbursements(Arrays.asList(
        AdvancedPaymentDisbursementRequest.builder()
            .collectorId(488656838L)
            .amount(new BigDecimal("80.00"))
            .applicationFee(new BigDecimal("2.00"))
            .build()
    ))
    .payer(AdvancedPaymentPayerRequest.builder()
        .email("buyer@example.com")
        .build())
    .build();

AdvancedPayment authorised = client.create(request);
System.out.println("Authorised ID: " + authorised.getId());
System.out.println("Status:        " + authorised.getStatus()); // pending / authorized

`AdvancedPaymentCreateRequest` fields

Field	Type	Description
`payments`	`List<AdvancedPaymentPaymentRequest>`	One or more payment sources
`disbursements`	`List<AdvancedPaymentDisbursementRequest>`	Sellers and amounts to distribute funds to
`payer`	`AdvancedPaymentPayerRequest`	Buyer information
`applicationId`	`String`	Your Mercado Pago application identifier
`description`	`String`	Human-readable payment description
`externalReference`	`String`	Your internal reference for reconciliation
`capture`	`Boolean`	`true` to capture immediately; `false` to authorise only
`binaryMode`	`Boolean`	`true` for instant approval/rejection (no intermediate states)

`AdvancedPaymentDisbursementRequest` fields

Field	Type	Description
`collectorId`	`Long`	Mercado Pago user ID of the receiving seller
`amount`	`BigDecimal`	Amount to disburse to this seller
`externalReference`	`String`	Your reference for this specific disbursement
`applicationFee`	`BigDecimal`	Marketplace fee retained from this disbursement
`moneyReleaseDate`	`String`	ISO 8601 date when funds are released to the seller

Retrieve an Advanced Payment

AdvancedPaymentClient client = new AdvancedPaymentClient();

AdvancedPayment payment = client.get(20458724L);
System.out.println("Status:          " + payment.getStatus());
System.out.println("External ref:    " + payment.getExternalReference());
System.out.println("Disbursements:   " + payment.getDisbursements().size());

Search Advanced Payments

import com.mercadopago.net.MPSearchRequest;
import com.mercadopago.net.MPResultsResourcesPage;
import java.util.HashMap;
import java.util.Map;

AdvancedPaymentClient client = new AdvancedPaymentClient();

Map<String, Object> filters = new HashMap<>();
filters.put("status", "approved");
filters.put("external_reference", "ADV-REF-1234");

MPSearchRequest searchRequest = MPSearchRequest.builder()
    .offset(0)
    .limit(20)
    .filters(filters)
    .build();

MPResultsResourcesPage<AdvancedPayment> results = client.search(searchRequest);
System.out.println("Found: " + results.getPaging().getTotal());
results.getResults().forEach(p ->
    System.out.println(p.getId() + " | " + p.getStatus())
);

Capture an Authorised Payment

After a two-step authorisation you can confirm the payment and trigger disbursements with a single call:

AdvancedPaymentClient client = new AdvancedPaymentClient();

AdvancedPayment captured = client.capture(20458724L);
System.out.println("Captured status: " + captured.getStatus()); // approved

Authorisations that are not captured within the issuer’s hold window (typically 7 days) will expire automatically. Always capture promptly after confirming order fulfilment.

Cancel an Advanced Payment

Cancel an authorisation (or an approved payment that has not been settled) to release the hold on the payer’s funds:

AdvancedPaymentClient client = new AdvancedPaymentClient();

AdvancedPayment cancelled = client.cancel(20458724L);
System.out.println("Cancelled status: " + cancelled.getStatus()); // cancelled

Cancellation is only available while the payment status allows it (e.g. authorized or pending). Approved and already-disbursed payments must be refunded instead.

Update Disbursement Release Date

Defer or advance the date on which seller funds are released by passing a new ISO 8601 date string:

AdvancedPaymentClient client = new AdvancedPaymentClient();

// Release funds for all disbursements on a specific date
AdvancedPayment updated = client.updateReleaseDate(
    20458724L,
    "2024-12-31T00:00:00.000-03:00"  // ISO 8601
);
System.out.println("Updated payment ID: " + updated.getId());

The underlying request sets moneyReleaseDate via AdvancedPaymentUpdateReleaseDateRequest and is POSTed to /v1/advanced_payments/{id}/disburses.

Disbursement Refunds (`DisbursementRefundClient`)

Use DisbursementRefundClient to issue full or partial refunds against individual disbursements within an advanced payment.

Refund a specific disbursement
Refund all disbursements at once

import com.mercadopago.client.disbursementrefund.DisbursementRefundClient;
import com.mercadopago.client.disbursementrefund.DisbursementRefundCreateRequest;
import com.mercadopago.resources.disbursementrefund.DisbursementRefund;
import java.math.BigDecimal;

DisbursementRefundClient refundClient = new DisbursementRefundClient();

// Partial refund of $50 on disbursement 123456
DisbursementRefundCreateRequest refundRequest =
    DisbursementRefundCreateRequest.builder()
        .amount(new BigDecimal("50.00")) // omit for a full refund
        .build();

DisbursementRefund refund = refundClient.create(
    20458724L,   // advancedPaymentId
    123456L,     // disbursementId
    refundRequest
);

System.out.println("Refund ID:           " + refund.getId());
System.out.println("Disbursement ID:     " + refund.getDisbursementId());
System.out.println("Amount refunded:     " + refund.getAmount());
System.out.println("Status:              " + refund.getStatus());
System.out.println("Date created:        " + refund.getDateCreated());

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

DisbursementRefundClient refundClient = new DisbursementRefundClient();

// Full refund across all disbursements (omit amount for full)
DisbursementRefundCreateRequest fullRefundRequest =
    DisbursementRefundCreateRequest.builder().build();

DisbursementRefund bulkRefund = refundClient.createAll(20458724L, fullRefundRequest);
System.out.println("Bulk refund status: " + bulkRefund.getStatus());

`DisbursementRefundCreateRequest` fields

Field	Type	Description
`amount`	`BigDecimal`	Amount to refund; omit or set `null` to refund the full disbursement amount

Complete Example

The following end-to-end example mirrors the official SDK example file — create an authorised payment and immediately capture it:

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.exceptions.MPApiException;
import com.mercadopago.exceptions.MPException;
import com.mercadopago.resources.advancedpayment.AdvancedPayment;
import java.math.BigDecimal;
import java.util.Arrays;

public class AdvancedPaymentExample {

    public static void main(String[] args) {
        MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

        AdvancedPaymentClient client = new AdvancedPaymentClient();

        try {
            AdvancedPaymentCreateRequest request = AdvancedPaymentCreateRequest.builder()
                .applicationId("{{APPLICATION_ID}}")
                .payments(Arrays.asList(
                    AdvancedPaymentPaymentRequest.builder()
                        .paymentMethodId("master")
                        .paymentTypeId("credit_card")
                        .token("{{CARD_TOKEN}}")
                        .transactionAmount(new BigDecimal("100.00"))
                        .installments(1)
                        .processingMode("aggregator")
                        .build()
                ))
                .disbursements(Arrays.asList(
                    AdvancedPaymentDisbursementRequest.builder()
                        .collectorId(488656838L)
                        .amount(new BigDecimal("80.00"))
                        .applicationFee(new BigDecimal("2.00"))
                        .build()
                ))
                .payer(AdvancedPaymentPayerRequest.builder()
                    .email("buyer@example.com")
                    .build())
                .externalReference("ADV-REF-001")
                .capture(false) // authorise first
                .build();

            AdvancedPayment payment = client.create(request);
            System.out.println("Advanced Payment ID: " + payment.getId());

            // Confirm order fulfilment, then capture
            AdvancedPayment captured = client.capture(payment.getId());
            System.out.println("Captured status: " + captured.getStatus());

        } catch (MPApiException e) {
            System.err.println("API error – status: " + e.getStatusCode());
            System.err.println("Message: "            + e.getMessage());
        } catch (MPException e) {
            System.err.println("SDK error: " + e.getMessage());
        }
    }
}

Error Handling

Both AdvancedPaymentClient and DisbursementRefundClient throw MPException for transport errors and MPApiException when the API returns a non-2xx status.

try {
    AdvancedPayment payment = client.create(request);
} catch (MPApiException e) {
    System.err.println("HTTP status: " + e.getStatusCode());
    System.err.println("Error:       " + e.getMessage());
} catch (MPException e) {
    System.err.println("SDK error:   " + e.getMessage());
}

Get Started

Guides

Marketplace Split Payments with Advanced Payments API

Creating an Advanced Payment

One-step (immediate capture)

Two-step (authorize then capture)

`AdvancedPaymentCreateRequest` fields

`AdvancedPaymentDisbursementRequest` fields

Retrieve an Advanced Payment

Search Advanced Payments

Capture an Authorised Payment

Cancel an Advanced Payment

Update Disbursement Release Date

Disbursement Refunds (`DisbursementRefundClient`)

`DisbursementRefundCreateRequest` fields

Complete Example

Error Handling

Build docs developers (and LLMs) love

Get Started

Guides

Documentation Index

​Creating an Advanced Payment

​One-step (immediate capture)

​Two-step (authorize then capture)

​AdvancedPaymentCreateRequest fields

​AdvancedPaymentDisbursementRequest fields

​Retrieve an Advanced Payment

​Search Advanced Payments

​Capture an Authorised Payment

​Cancel an Advanced Payment

​Update Disbursement Release Date

​Disbursement Refunds (DisbursementRefundClient)

​DisbursementRefundCreateRequest fields

​Complete Example

​Error Handling

Build docs developers (and LLMs) love

Creating an Advanced Payment

One-step (immediate capture)

Two-step (authorize then capture)

`AdvancedPaymentCreateRequest` fields

`AdvancedPaymentDisbursementRequest` fields

Retrieve an Advanced Payment

Search Advanced Payments

Capture an Authorised Payment

Cancel an Advanced Payment

Update Disbursement Release Date

Disbursement Refunds (`DisbursementRefundClient`)

`DisbursementRefundCreateRequest` fields

Complete Example

Error Handling