Create order with Split Payments 1:N
To create an order with Split Payments 1:N, that divides a total payment between two or more participants, you will need to obtain the buyer's card token and send a POST request to the order creation endpoint with the data of the sellers involved.
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 in the frontend of your application, 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 request to the backend
:::
Send a POST to the endpoint POST /v1/ordersAPI, replacing {{SELLER_1_USER_ID}} and {{SELLER_2_USER_ID}} with the User IDs of the Seller-type test accounts that you can access from Your Integrations > Your application > Test accounts > Seller. See the request details in the table below the example.
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}}' \ --header 'x-meli-session-id: {{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" }, "phone": { "area_code": "+55", "number": "11987654321" }, "address": { "street_name": "Av. Paulista", "street_number": "1578", "zip_code": "01310-200", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "complement": "Apto 101" } }, "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": [ { "user_id": {{SELLER_1_USER_ID}}, "amount": "350.00", "description": "Seller 1" }, { "user_id": {{SELLER_2_USER_ID}}, "amount": "150.00", "description": "Seller 2" } ], "items": [ { "title": "Sample product", "description": "Product description", "category_id": "electronics", "quantity": 1, "unit_price": "500.00" } ], "shipment": { "address": { "zip_code": "01310-200", "street_name": "Av. Paulista", "street_number": "1578", "neighborhood": "Bela Vista", "city": "São Paulo", "complement": "Apto 101" } }, "integration_data": { "integrator_id": "dev_123", "platform_id": "1234567890" } }'
| Parameter | Type | Description | Required |
Authorization | String (Header) | test Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it in Your integrations > Application details > Test > Test credentials.Test credentials Format: Bearer {{YOUR_ACCESS_TOKEN}}. | Required |
x-idempotency-key | String (Header) | Unique identifier (UUID) to ensure request idempotency. | Required |
x-meli-session-id | String (Header) | Device ID of the buyer's device. Required to improve payment approval rates. | Required |
type | String | Order type. Use "online" for online payments. | Required |
external_reference | String | External reference that identifies the order in your system. | Required |
total_amount | String | Total order amount. The sum of splits.amount must equal this value when amount_type is "fixed", or equal 100 when it is "percentage". | Required |
processing_mode | String | Payment processing mode. Use "automatic" for automatic processing. | Required |
payer | Object | Buyer data. | Required |
payer.email | String | Payer email. For testing use test@testuser.com. | Required |
payer.first_name | String | Payer's first name. | Optional |
payer.last_name | String | Payer's last name. | Optional |
payer.entity_type | String | Entity type. Use "individual" for individuals. | Optional |
payer.identification | Object | Payer's identification type and number. | Optional |
payer.phone | Object | Payer's phone number. Includes: area_code, number. | Optional |
payer.address | Object | Payer's address. Includes: street_name, street_number, zip_code, neighborhood, city, state, complement. | Optional |
transactions | Object | Payment transactions object. | Required |
transactions.payments | Array | List of payments. | Required |
transactions.payments.amount | String | Payment amount. | Required |
transactions.payments.payment_method.id | String | Payment method identifier (e.g., "master"). | Required |
transactions.payments.payment_method.type | String | Payment method type (e.g., "credit_card"). | Required |
transactions.payments.payment_method.token | String | Card token generated by tokenization. | Required |
transactions.payments.payment_method.installments | Integer | Number of installments the payment is divided into. | Optional |
transactions.payments.payment_method.statement_descriptor | String | Name that appears on the buyer's card statement. | Optional |
config | Object | Order configuration. For split, includes split_rules. | Required |
config.split_rules.amount_type | String | Defines the unit of the values in splits.amount. The possible values are: - "fixed" for exact monetary amounts. When using this unit, the sum of splits.amount must equal total_amount. - "percentage" for percentage values. When using this unit, the sum of splits.amount must equal 100. | Required |
splits | Array | Array of objects defining the split participants. Maximum of 10 secondary sellers per order. | Required |
splits.user_id | Integer | The user_id of the Mercado Pago account of the seller receiving this part of the payment.Important: This user ID must be requested from each of the sellers participating in the transaction. The user_id of the primary seller (transaction owner) must always be present in the array. | Required |
splits.amount | String | The value assigned to this participant. Depending on the config.split_rules.amount_type parameter, this can be: - An exact monetary amount when amount_type is "fixed". - A percentage value when amount_type is "percentage" (values must be whole numbers). | Required |
splits.description | String | Description of this part of the split. | Optional |
items | Array | List of order items. Includes: title, description, category_id, quantity, unit_price. | Optional |
shipment | Object | Shipment information. Includes address with: zip_code, street_name, street_number, neighborhood, city, complement. | Optional |
integration_data | Object | Integration data. Includes: integrator_id, platform_id. | Optional |
If the request fails, the API will return a response with the corresponding HTTP status code. For the full list of errors, see Possible errors.
To confirm that the order was created correctly with the payment split, send a GET to the endpoint /v1/orders/{id}API, replacing {order_id} with the ID returned in the response when creating the order 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 > Test > Test credentials.Test credentials.
curl
curl --request GET \ --url https://api.mercadopago.com/v1/orders/{Order_id} \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
Below, you can see a response example, that will allow you to verify the order details. You must make sure returned status is "processed", the status_detail is "accredited", and that the splits array is present and correctly reflects the user_id and amount values defined when creating the order.
json
{ "id": "ORDTST01K5HQXYKPDQTS6V0DXQ3ZVSFT", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "site_id": "MLB", "user_id": "2366102316", "product_id": "CIFI5HEOD60B64QAI5O0", "capture_mode": "automatic_async", "currency": "BRL", "type": "online", "status": "processed", "status_detail": "accredited", "total_amount": "500.00", "total_paid_amount": "500.00", "created_date": "2025-09-19T19:41:30.102329483Z", "last_updated_date": "2025-09-19T19:41:41.515741076Z", "integration_data": { "application_id": "5685566486818147", "features": [ "split" ] }, "config": { "split_rules": { "amount_type": "fixed" } }, "payer": { "id": "2386426096", "type": "registered" }, "transactions": { "payments": [ { "id": "PAY01K5HQXYKPDQTS6V0DXTJ7BPVV", "status": "processed", "status_detail": "accredited", "amount": "500.00", "paid_amount": "500.00", "payment_method": { "id": "master", "type": "credit_card", "token": "f80c91b69f882f62530196cfba64289d", "installments": 1, "statement_descriptor": "MYSTORE" }, "reference": { "id": "22dvqmtdstw", "source": "transaction_intent" } } ] }, "splits": [ { "user_id": 2366102316, "amount": "350.00", "description": "Seller 1" }, { "user_id": 2366439738, "amount": "150.00", "description": "Seller 2" } ] }
After confirming the order was created correctly with the payment split, proceed to Configure notifications to track the status of your transactions in real time.