Crear Order con Split de Pagos 1:N
Para crear una order con Split de Pagos 1:N, que divide un pago total entre dos o más participantes, será necesario obtener el token de la tarjeta del comprador y enviar una solicitud POST al endpoint de creación de orders con los datos de los vendedores involucrados.
El campo token del body de la solicitud es una representación segura de los datos de la tarjeta, generada con MercadoPago.js. Asegúrate de haber configurado el ambiente de desarrollo antes de continuar.
Para generar el token en el frontend de tu aplicación, utiliza el método createCardToken de la instancia de MercadoPago.js:
javascript
const token = await mp.fields.createCardToken({ cardholderName: "APRO", identificationType: "DNI", identificationNumber: "12345678" }); // Usa token.id como valor del campo "token" en la solicitud al backend
Envía un POST al endpoint POST /v1/ordersAPI, reemplazando {{SELLER_1_USER_ID}} y {{SELLER_2_USER_ID}} por los User IDs de las cuentas de prueba del tipo Vendedor a las que puedes acceder desde Tus Integraciones > Tu aplicación > Cuentas de prueba > Vendedor. Consulta el detalle de la requisición en la tabla debajo del ejemplo.
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": "DNI", "number": "12345678" }, "phone": { "area_code": "+549", "number": "1166439815" }, "address": { "street_name": "Av. Corrientes", "street_number": "3003", "zip_code": "1426", "neighborhood": "Palermo", "city": "CABA", "state": "Bs As", "complement": "Apto 303" } }, "transactions": { "payments": [ { "amount": "500.00", "payment_method": { "id": "master", "type": "credit_card", "token": "your_card_token_here", "installments": 1, "statement_descriptor": "MITIENDA" } } ] }, "config": { "split_rules": { "amount_type": "fixed" } }, "splits": [ { "user_id": {{SELLER_1_USER_ID}}, "amount": "350.00", "description": "Vendedor 1" }, { "user_id": {{SELLER_2_USER_ID}}, "amount": "150.00", "description": "Vendedor 2" } ], "items": [ { "title": "Producto de ejemplo", "description": "Descripción del producto", "category_id": "electronics", "quantity": 1, "unit_price": "500.00" } ], "shipment": { "address": { "zip_code": "1515", "street_name": "Av. Cordoba", "street_number": "3003", "neighborhood": "Palermo", "city": "CABA", "complement": "Apto 123" } }, "integration_data": { "integrator_id": "dev_123", "platform_id": "1234567890" } }'
| Parámetro | Tipo | Descripción | Obligatoriedad |
Authorization | String (Header) | Token de acceso de pruebaClave privada de la aplicación creada en Mercado Pago, utilizada en el backend. Puedes acceder a ella en Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba.Credenciales de prueba Formato: Bearer {{YOUR_ACCESS_TOKEN}}. | Obligatorio |
x-idempotency-key | String (Header) | Identificador único (UUID) para garantizar la idempotencia de la solicitud. | Obligatorio |
x-meli-session-id | String (Header) | Device ID del dispositivo del comprador. Necesario para mejorar la aprobación de pagos. | Obligatorio |
type | String | Tipo de order. Usa "online" para pagos en línea. | Obligatorio |
external_reference | String | Referencia externa que identifica la order en tu sistema. | Obligatorio |
total_amount | String | Monto total de la order. La suma de los splits.amount debe ser igual a este valor cuando amount_type sea "fixed", o igual a 100 cuando sea "percentage". | Obligatorio |
processing_mode | String | Modo de procesamiento del pago. Usa "automatic" para procesamiento automático. | Obligatorio |
payer | Object | Datos del comprador. | Obligatorio |
payer.email | String | Email del pagador. Para pruebas usa test@testuser.com. | Obligatorio |
payer.first_name | String | Nombre del pagador. | Opcional |
payer.last_name | String | Apellido del pagador. | Opcional |
payer.entity_type | String | Tipo de entidad. Usa "individual" para personas físicas. | Opcional |
payer.identification | Object | Tipo y número de identificación del pagador. | Opcional |
payer.phone | Object | Teléfono del pagador. Incluye: area_code, number. | Opcional |
payer.address | Object | Dirección del pagador. Incluye: street_name, street_number, zip_code, neighborhood, city, state, complement. | Opcional |
transactions | Object | Objeto de transacciones de pago. | Obligatorio |
transactions.payments | Array | Lista de pagos. | Obligatorio |
transactions.payments.amount | String | Monto del pago. | Obligatorio |
transactions.payments.payment_method.id | String | Identificador del medio de pago (ej: "master"). | Obligatorio |
transactions.payments.payment_method.type | String | Tipo de medio de pago (ej: "credit_card"). | Obligatorio |
transactions.payments.payment_method.token | String | Token de la tarjeta generado por la tokenización. | Obligatorio |
transactions.payments.payment_method.installments | Integer | Número de cuotas en que se divide el pago. | Opcional |
transactions.payments.payment_method.statement_descriptor | String | Nombre que aparece en el resumen de la tarjeta del comprador. | Opcional |
config | Object | Configuración de la order. Para split, incluye split_rules. | Obligatorio |
config.split_rules.amount_type | String | Define la unidad de los valores informados en splits.amount. Los valores posibles son: - "fixed" para valores monetarios exactos. Al usar esta unidad, la suma de los splits.amount debe ser igual al total_amount. - "percentage" para valores porcentuales. Al usar esta unidad, la suma de los splits.amount debe ser igual a 100. | Obligatorio |
splits | Array | Array de objetos que definen a los participantes del split. Máximo de 10 vendedores secundarios por order. | Obligatorio |
splits.user_id | Integer | El user_id de la cuenta de Mercado Pago del vendedor que recibe esta parte del pago.Importante: Este ID de usuario debe ser solicitado a cada uno de los vendedores que participan en la transacción. El user_id del vendedor principal (owner de la transacción) debe estar siempre presente en el array. | Obligatorio |
splits.amount | String | El valor asignado a este participante. Dependiendo del parámetro config.split_rules.amount_type, esto puede ser: - Un valor monetario exacto cuando amount_type es "fixed". - Un valor porcentual cuando amount_type es "percentage" (los valores deben ser números enteros). | Obligatorio |
splits.description | String | Descripción de esta parte del split. | Opcional |
items | Array | Lista de ítems de la order. Incluye: title, description, category_id, quantity, unit_price. | Opcional |
shipment | Object | Información de envío. Incluye address con: zip_code, street_name, street_number, neighborhood, city, complement. | Opcional |
integration_data | Object | Datos de integración. Incluye: integrator_id, platform_id. | Opcional |
En caso de error en la solicitud, la API devolverá una respuesta con el código de estado HTTP correspondiente. A continuación se muestran dos ejemplos de errores frecuentes:
Error 400 — Suma de montos inválida
json
{ "status": 400, "message": "the sum of the amounts for the receivers must be equal to the total amount of the split", "errors": [] }
Error 422 — Validación de usuario
json
{ "status": 422, "message": "user validation error", "errors": [] }
Si la solicitud falla, la API devolverá una respuesta con el código de estado HTTP correspondiente. Para ver la lista completa de errores, accede a Posibles errores.
Para confirmar que la order se creó correctamente con el split de pagos, envía un GET al endpoint /v1/orders/{id}API, reemplazando {order_id} por el ID retornado en la respuesta de la creación de la order y utilizando tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, que se utiliza en el backend. Puedes acceder a ella en Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba.Credenciales de prueba.
curl
curl --request GET \ --url https://api.mercadopago.com/v1/orders/{Order_id} \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
A continuación, puedes ver un ejemplo de respuesta, que te permitirá verificar los detalles de la order. Debes asegurarte de que el status retornado sea "processed", el status_detail sea "accredited", y que el array splits esté presente y refleje correctamente los user_id y los amount definidos al crear la order.
Recibirás una respuesta similar al siguiente ejemplo:
json
{ "id": "ORDTST01K5HQXYKPDQTS6V0DXQ3ZVSFT", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "site_id": "MLA", "user_id": "2366102316", "product_id": "CIFI5HEOD60B64QAI5O0", "capture_mode": "automatic_async", "currency": "ARS", "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": "MITIENDA" }, "reference": { "id": "22dvqmtdstw", "source": "transaction_intent" } } ] }, "splits": [ { "user_id": 2366102316, "amount": "350.00", "description": "Vendedor 1" }, { "user_id": 2366439738, "amount": "150.00", "description": "Vendedor 2" } ] }
Tras confirmar la creación correcta de la order con el split de pagos, avanza a Configurar notificaciones para hacer seguimiento en tiempo real del estado de tus transacciones.