Split Payments 1:N

To integrate Split Payments 1:N, you will need two Seller test accounts: one for your main application and another to act as the secondary participant that receives a share of the split. The data obtained from these accounts will be used later during the integration.

When you create an application, a test account of type Seller is automatically created, so you will only need to create a second test account to continue with the integration.

Test accounts are users who have the same functionalities as a real Mercado Pago user, but allow you to test the operation of your development without compromising real data.

Follow the steps below to create a seller test account.

1. In Mercado Pago Developers, navigate to Your Integrations in the upper right corner of the screen, and click on the card corresponding to the application you are using for development.
2. Having accessed "Application Details", go to Tests > Test Accounts in the left sidebar menu, and click the Create test account button.

3. On the "Create new account" screen, select the country of operation of the account, bearing in mind that this information cannot be edited later.
4. Next, enter a description to identify the account.
5. Select the Account Type as Seller.
6. Because it is a seller user, it is not necessary to indicate any value for the available money.
7. Accept the Privacy Statement and the Terms and Conditions, and click Create test account.

Get account data

Once you have both accounts created, you will need the User ID and the Username from those accounts to continue with the integration.

When creating the accounts, you will have access to two identifiers: the User ID, a numeric identifier used in the splits array when configuring the split payment, and the Username, an alphanumeric identifier automatically assigned by Mercado Pago and used to compose the invitation email when configuring the split consent in tests.

To obtain this data, follow the steps below.

1. In the integration data you created in Create application, go to Test > Test accounts.
2. In the account tabs, click on Seller.
3. In the table shown, after the country indicator, you will find the User ID followed by the Username (in TEST+digits format) for each test Seller account.

With this information, continue with the split consent configuration.

Before including a secondary seller in a split order, the primary seller must create a formal consent with that seller. The secondary seller must explicitly accept the terms through the Mercado Pago interface.

This flow generates the receiver_id, a unique identifier in UUID format, that identifies each secondary seller in all Split Payments 1:N operations and must be used to create orders.

The consent must have ACTIVE status before including the secondary seller in a split order. Attempts with a different status will return a validation error.

The possible statuses for a consent are:

When working with test accounts (required during the integration testing process), you can use the x-test-status header when sending a request to the endpoint /v1/split-consentPOST to force the consent directly to the status you need to test, without the secondary seller having to intervene manually. If the header is not sent, the API will default to PENDING status.

This mechanism allows you to simulate all possible scenarios in the consent lifecycle during development.

Create invitation

To create a consent, send a request to the endpoint /v1/split-consentPOST with the secondary seller's test email in the format {USERNAME}@testuser.com in the invites node.

Since the email acceptance flow does not work for test accounts, include the header x-test-status: ACTIVE so the consent is created directly with that status. The receiver_id field is always returned, regardless of the status.

curl
curl --request POST \
  --url https://api.mercadopago.com/v1/split-consent \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
  --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
  --header 'x-test-token: true' \
  --header 'x-test-status: ACTIVE' \
  --data '{
    "invites": [
      {
        "seller_email": "{USERNAME}@testuser.com"
      }
    ]
  }'

If creation is successful, the response will return the receiver_id, which is the UUID associated with the secondary seller and that you will use in the splits array when creating orders.

The consent status varies according to the header sent in the request. If you include x-test-status: ACTIVE, the consent will be created directly with ACTIVE status. Otherwise, the status will be PENDING until the secondary seller accepts the invitation.

You can simulate all lifecycle scenarios using the following values in the x-test-status header:

json
{
  "succeeded": [
    {
      "seller_email": "{USERNAME}@testuser.com",
      "receiver_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "ACTIVE",
      "invite_url": "https://www.mercadopago.com/split/invite/550e8400"
    }
  ],
  "failed": []
}

To invite multiple sellers in a single request, add multiple objects with their respective emails (seller_email) to the invites node.

With the obtained receiver_id, you can proceed to verify the consent status.

Verify consent status

To query consents, send a request to the endpoint /v1/split-consentGET with the status=ACTIVE query to filter the search.

curl
curl --request GET \
  --url 'https://api.mercadopago.com/v1/split-consent?status=ACTIVE' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

If successful, the response will be similar to the example below.

json
{
  "paging": { "total": 1, "offset": 0, "limit": 20 },
  "results": [
    {
      "receiver_id": "550e8400-e29b-41d4-a716-446655440000",
      "seller_email": "{USERNAME}@testuser.com",
      "status": "ACTIVE",
      "created_at": "2026-01-26T10:00:00Z",
      "updated_at": "2026-01-26T14:00:00Z"
    }
  ]
}

Configure consent status notifications

To automatically track changes to a split consent's status, you can receive a Webhook notification for each transition without relying on the email sent to the primary seller or polling the API.

Configure the event on the application's general WebhooksApplication notification settings screen, available under Your integrations > Application details > Notifications > Webhooks. screen. Select the event in the Other events group, on the tab for the environment you want to configure —test or production— and enter the URL where you want to receive notifications.

In the Portuguese interface, select Split - Autorização under Outros eventos.

A notification is sent whenever the consent status changes, except when the initial invitation is created with status PENDING.

The received notification will have a structure similar to the following:

json
{
  "receiver_id": "7f8e9a1b-...",
  "status": "ACTIVE",
  "action": "consent.accepted",
  "canceled_by": null
}

For information about configuring notifications and validating their origin, see Configure notifications.

Test the acceptance flow via interface

In addition to forcing the status with x-test-status, you can also test the complete acceptance flow, simulating production behavior.

To do this, create the consent without the header x-test-status. The consent will have status PENDING and the response will include the invite_url:

curl
curl --request POST \
  --url https://api.mercadopago.com/v1/split-consent \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
  --header 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
  --header 'x-test-token: true' \
  --data '{
    "invites": [
      {
        "seller_email": "test@testuser.com"
      }
    ]
  }'

The test secondary seller will receive an email from Mercado Pago with the invite_url link. To simulate acceptance, the secondary seller must access that link authenticated with their own test account on Mercado Pago. When doing so, they will be directed to the acceptance or rejection screen in the Mercado Pago interface. The routing to the sandbox environment occurs automatically when the user is authenticated with a test account, with no additional configuration needed.

Cancel consent

To cancel an existing consent, send a request to the endpoint /v1/split-consent/{receiver_id}PATCH.

curl
curl --request PATCH \
  --url 'https://api.mercadopago.com/v1/split-consent/{receiver_id}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
  --data '{"status": "CANCELED"}'

The primary seller can cancel consents with status PENDING or ACTIVE, while the secondary seller can reject an invitation (PENDING → REJECTED) or cancel an active consent (ACTIVE → CANCELED). All secondary seller actions on the consent status are performed exclusively through the Mercado Pago interface, not via API.

To check possible consent API errors, see the Possible errors section of this documentation.

To create an order with Split Payments 1:N, send a request to the endpoint :TagComponent with the data of the involved sellers and the chosen payment method information.

You can offer payments with credit card, debit card, and Pix.

Credit and debit card

1. Get the card token

The token field in the request body is a secure representation of the card data, generated with MercadoPago.js. Make sure you have configured the development environment before continuing.

To generate the token on your application's frontend, use the createCardToken method of the MercadoPago.js instance:

javascript
const token = await mp.fields.createCardToken({
  cardholderName: "APRO",
  identificationType: "CPF",
  identificationNumber: "12345678909"
});
// Use token.id as the value of the "token" field in the backend request

2. Create the order

Send a request to the endpoint /v1/ordersPOST, replacing {{OWNER_USER_ID}} with the numeric user_id of the primary seller (visible in Integration data > Details > User IDNumeric identifier of your Mercado Pago account, visible in Integration data > Details.) and {{PARTNER_CONSENT_UUID}} with the UUID generated by the consent API /v1/split-consentPOST for the secondary seller.

curl
curl --request POST \
  --url https://api.mercadopago.com/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
  --header 'x-idempotency-key: {{SOME_UNIQUE_VALUE}}' \
  --header 'x-meli-session-id: {{YOUR_DEVICE_ID}}' \
  --data '{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "total_amount": "500.00",
  "processing_mode": "automatic",
  "payer": {
    "email": "test@testuser.com",
    "first_name": "APRO",
    "last_name": "Test",
    "entity_type": "individual",
    "identification": {
      "type": "CPF",
      "number": "12345678909"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "500.00",
        "payment_method": {
          "id": "master",
          "type": "credit_card",
          "token": "your_card_token_here",
          "installments": 1,
          "statement_descriptor": "MYSTORE"
        }
      }
    ]
  },
  "config": {
    "split_rules": {
      "amount_type": "fixed"
    }
  },
  "splits": [
    {
      "receiver_id": "{{OWNER_USER_ID}}",
      "receiver_type": "owner",
      "amount": "350.00",
      "description": "Primary seller"
    },
    {
      "receiver_id": "{{PARTNER_CONSENT_UUID}}",
      "receiver_type": "partner",
      "amount": "150.00",
      "description": "Secondary seller"
    }
  ],
  "items": [
    {
      "title": "Sample product",
      "description": "Product description",
      "category_id": "electronics",
      "quantity": 1,
      "unit_price": "500.00"
    }
  ],
  "integration_data": {
    "integrator_id": "dev_123",
    "platform_id": "1234567890"
  }
}'

3. Verify the order

To confirm the order was processed correctly with the split, send a request to the endpoint /v1/orders/{id}GET, replacing {order_id} with the ID returned in the creation response and using your Test Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it in Your integrations > Application details > Tests > Test credentials.Test credentials.

curl
curl --request GET \
  --url https://api.mercadopago.com/v1/orders/{order_id} \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

Make sure the returned status is "processed", the status_detail is "accredited", and that the splits array correctly reflects the receiver_id, receiver_type and amount values defined during creation.

json
{
    "id": "ORDTST01K5HQXYKPDQTS6V0DXQ3ZVSFT",
    "processing_mode": "automatic",
    "external_reference": "ext_ref_1234",
    "site_id": "MLB",
    "currency": "BRL",
    "status": "processed",
    "status_detail": "accredited",
    "total_amount": "500.00",
    "splits": [
        {
            "receiver_id": "2366102316",
            "receiver_type": "owner",
            "amount": "350.00",
            "description": "Primary seller"
        },
        {
            "receiver_id": "550e8400-e29b-41d4-a716-446655440000",
            "receiver_type": "partner",
            "amount": "150.00",
            "description": "Secondary seller"
        }
    ]
}

After confirming the order was correctly created with the split, go to the Notifications section to track your transactions in real time.

Pix

1. Create the order with Pix

For Pix payments, send a request to the endpoint /v1/ordersPOST with the payer data and the split rules.

curl
curl --request POST \
  --url https://api.mercadopago.com/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
  --header 'x-idempotency-key: {{UNIQUE_IDEMPOTENCY_KEY}}' \
  --data '{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "total_amount": "500.00",
  "processing_mode": "automatic",
  "payer": {
    "email": "test@testuser.com",
    "first_name": "APRO",
    "last_name": "Test",
    "entity_type": "individual",
    "identification": {
      "type": "CPF",
      "number": "12345678909"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": "500.00",
        "payment_method": {
          "id": "pix",
          "type": "bank_transfer"
        },
        "expiration_time": "P1D"
      }
    ]
  },
  "config": {
    "split_rules": {
      "amount_type": "fixed"
    }
  },
  "splits": [
    {
      "receiver_id": "{{OWNER_USER_ID}}",
      "receiver_type": "owner",
      "amount": "350.00",
      "description": "Primary seller"
    },
    {
      "receiver_id": "{{PARTNER_CONSENT_UUID}}",
      "receiver_type": "partner",
      "amount": "150.00",
      "description": "Secondary seller"
    }
  ]
}'

After sending the request, the response will include the fields needed to make the payment available to the buyer. Use the ticket_url to redirect the buyer to a payment page, or render the qr_code_base64 directly on the screen. For more details on how to display Pix to the buyer, see Pix.

2. Verify the order

To confirm the order was processed correctly with the split, send a request to the endpoint /v1/orders/{id}GET.

curl
curl --request GET \
  --url https://api.mercadopago.com/v1/orders/{order_id} \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

Once the buyer completes the Pix payment, the order will be updated with status: "processed" and status_detail: "accredited".

After confirming the order was correctly created with the split, go to the Notifications section to track your transactions in real time.

2. Create the order

Send a request to the endpoint /v1/ordersPOST, replacing {{OWNER_USER_ID}} with the numeric user_id of the primary seller (visible in Integration data > Details > User IDNumeric identifier of your Mercado Pago account, visible in Integration data > Details.) and {{PARTNER_CONSENT_UUID}} with the UUID generated by the consent API for the secondary seller.

3. Verify the order

To confirm the order was processed correctly with the split, send a request to the endpoint /v1/orders/{id}GET.

curl
curl --request GET \
  --url https://api.mercadopago.com/v1/orders/{order_id} \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

You must ensure the returned status is "processed", the status_detail is "accredited", and the splits array reflects the configured division, as in the example below:

After confirming the order was correctly created with the split, continue with notifications configuration in the Notifications section.

Configure 3D Secure (3DS)

To add 3DS authentication to Split Payments 1:N, see Integrate 3D Secure (3DS).

Notifications

To configure and receive Webhook notifications for your Split Payments 1:N orders, see Configure notifications.

The testing process allows you to verify if the configurations made during your integration work correctly, and if payments will be processed without errors, avoiding possible failures when making the checkout available to final buyers.

In this section you will find the steps needed to perform a test purchase with cards.

Perform a test purchase with cards

To test your integration with credit and/or debit cards you should perform a test purchase with these payment methods, simulating the actions of a buyer user.

To do this, access the store that has your checkout integrated, select a product or service, and start the purchase process.

1. Complete payer data

To make a successful test purchase, fill in the required data at checkout following the information indicated below.

Buyer email

In the email field, enter the email address test@testuser.com, which is the only one allowed for testing. This way, your system will understand that it is a purchase made with a test buyer user.

Card details

Mercado Pago provides test cards that will allow you to test payments without using a real card.

Their data, such as number, security code, and expiration date, can be combined with the data relating to the cardholder, which will allow you to test different payment scenarios. That is, you can use the information of any test card and test different payment results based on the cardholder's data.

Below, you can see the data of the test debit and credit cards. Select the one you want to use to test your integration.

Next, choose which payment scenario to test and fill in the cardholder's information (First name and last name, Document type and number) as indicated in the table below.

Once you have completed all the fields correctly, click the button to process the payment and wait for the result.

2. Verify test purchase

To verify that the test purchase was carried out according to the expected results based on the data entered, send a request to the /v1/orders/{id}GET endpoint, replacing id with the order identification, received in the response to its creation.

The response to this call should bring the detailed information of the test transaction, along with the status chosen for the payment in the previous step within the status field.

Once these steps are completed, the integration of cards as a payment method is complete and you can go to production.

These are transactions that occur when a specific charge is reversed and the paid amounts are returned to the transaction participants. You can refund specific participants without affecting the others' share, or process a full refund.

curl
curl --request POST \
  --url https://api.mercadopago.com/v1/orders/{order_id}/refund \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'

json
{
  "id": "ORD01J49MMW3SSBK5PSV3DFR32959",
  "status": "processed",
  "status_detail": "refunded",
  "transactions": {
    "refunds": [
      {
        "id": "REF01J49MMW3SSBK5PSV3DFR32959",
        "transaction_id": "PAY01JEVQM06WDW16MAQ8B5SC0MSC",
        "reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
        "amount": "24.50",
        "status": "processed"
      }
    ]
  }
}

curl
curl --request POST \
  --url https://api.mercadopago.com/v1/orders/{order_id}/refund \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
  --data '{
  "splits": [
    {
      "receiver_id": "{{RECEIVER_ID_1}}"
    }
  ]
}'

json
{
  "id": "ORD01J49MMW3SSBK5PSV3DFR32959",
  "status": "processed",
  "status_detail": "refunded",
  "transactions": {
    "refunds": [
      {
        "id": "REF01J49MMW3SSBK5PSV3DFR32959",
        "transaction_id": "PAY01JEVQM06WDW16MAQ8B5SC0MSC",
        "reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
        "amount": "24.50",
        "status": "processed"
      }
    ]
  }
}

curl
curl --request POST \
  --url https://api.mercadopago.com/v1/orders/{order_id}/refund \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
  --data '{
  "splits": [
    {
      "receiver_id": "{{RECEIVER_ID_1}}",
      "amount": "50.00"
    }
  ]
}'

json
{
  "id": "ORD01J49MMW3SSBK5PSV3DFR32959",
  "status": "processed",
  "status_detail": "refunded",
  "transactions": {
    "refunds": [
      {
        "id": "REF01J49MMW3SSBK5PSV3DFR32959",
        "transaction_id": "PAY01JEVQM06WDW16MAQ8B5SC0MSC",
        "reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
        "amount": "50.00",
        "status": "processed"
      }
    ]
  }
}

curl
curl --request POST \
  --url https://api.mercadopago.com/v1/orders/{order_id}/refund \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
  --data '{
  "splits": [
    {
      "receiver_id": "{{RECEIVER_ID_1}}",
      "amount": "50.00"
    },
    {
      "receiver_id": "{{RECEIVER_ID_2}}",
      "amount": "10.00"
    }
  ]
}'

json
{
  "id": "ORD01J49MMW3SSBK5PSV3DFR32959",
  "status": "processed",
  "status_detail": "refunded",
  "transactions": {
    "refunds": [
      {
        "id": "REF01J49MMW3SSBK5PSV3DFR32959",
        "transaction_id": "PAY01JEVQM06WDW16MAQ8B5SC0MSC",
        "reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
        "amount": "50.00",
        "status": "processed"
      },
      {
        "id": "REF01J49MMW3SSBK5PSV3DFR32960",
        "transaction_id": "PAY01JEVQM06WDW16MAQ8B5SC0MSD",
        "reference_id": "01JEVQM899NWSQC4FYWWW7KTF8",
        "amount": "10.00",
        "status": "processed"
      }
    ]
  }
}

Split Payments 1:N has an exclusive report for the primary seller. For more information on how to create and configure the report, see the reports documentation.

Mercado Pago split payments sales report

The Mercado Pago split payments sales report records transactions made with Split Payments 1:N, including fees, settlements, and financial blocks per transaction. It is available for download in csv and json formats. You will also find data such as the total transaction amount, marketplace fee, Mercado Pago fee, and total money received.

This report can only be used through the API.

Download report

To download the Mercado Pago split payments sales report, you need to configure it through the API. This process can be done in two ways: manually or automatically. In both options, some preliminary configurations are required as indicated below.

• Frequency.
• List of email addresses that will receive the report.
• List of columns or attributes to include.

Use the report

The report can be used as a reconciliation tool between the total transactions made with Split Payments 1:N and your systems or reconciliation tools. The report provides detailed information such as dates, concepts, status, amounts, and fees per transaction, as well as the identification of the responsible seller. It is especially useful for:

1. Tracking sales with Split Payments 1:N during specific periods.
2. Identifying sellers with the greatest economic impact.
3. Establishing preferential fees based on sales volume.
4. Coordinating collaborative campaigns with sellers.
5. Evaluating the prevalence of different payment methods, such as debit card and credit card.

Use this report when you need detailed financial reconciliation between two specific dates.

When integrating Split Payments 1:N, the API may return validation errors with specific codes and messages. The errors are described below by topic along with the response format.