Criar order com Split de Pagamentos 1:N
Para criar uma order com Split de Pagamentos 1:N, que divide um pagamento total entre dois ou mais participantes, será necessário obter o token do cartão do comprador e enviar uma requisição POST ao endpoint de criação de orders com os dados dos vendedores envolvidos.
O campo token do body da solicitação é uma representação segura dos dados do cartão, gerada com MercadoPago.js. Certifique-se de ter configurado o ambiente de desenvolvimento antes de continuar.
Para gerar o token no frontend da sua aplicação, utilize o método createCardToken da instância do MercadoPago.js:
javascript
const token = await mp.fields.createCardToken({ cardholderName: "APRO", identificationType: "DNI", identificationNumber: "12345678" }); // Use token.id como valor do campo "token" na solicitação ao backend
Envie um POST ao endpoint POST /v1/ordersAPI, substituindo {{SELLER_1_USER_ID}} e {{SELLER_2_USER_ID}} pelos User IDs das contas de teste do tipo Vendedor que você pode acessar em Suas Integrações > Sua aplicação > Contas de teste > Vendedor. Consulte o detalhe da requisição na tabela abaixo do exemplo.
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": "MINHALOJA" } } ] }, "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": "Produto de exemplo", "description": "Descrição do produto", "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 | Descrição | Obrigatoriedade |
Authorization | String (Header) | token de acesso de testeChave privada da aplicação criada no Mercado Pago, utilizada no backend. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste.Credenciais de teste Formato: Bearer {{YOUR_ACCESS_TOKEN}}. | Obrigatório |
x-idempotency-key | String (Header) | Identificador único (UUID) para garantir idempotência da solicitação. | Obrigatório |
x-meli-session-id | String (Header) | Device ID do dispositivo do comprador. Necessário para melhorar a aprovação de pagamentos. | Obrigatório |
type | String | Tipo da order. Use "online" para pagamentos online. | Obrigatório |
external_reference | String | Referência externa que identifica a order no seu sistema. | Obrigatório |
total_amount | String | Valor total da order. A soma dos splits.amount deve ser igual a este valor quando amount_type for "fixed", ou igual a 100 quando for "percentage". | Obrigatório |
processing_mode | String | Modo de processamento do pagamento. Use "automatic" para processamento automático. | Obrigatório |
payer | Object | Dados do comprador. | Obrigatório |
payer.email | String | E-mail do pagador. Para testes, use test@testuser.com. | Obrigatório |
payer.first_name | String | Primeiro nome do pagador. | Opcional |
payer.last_name | String | Sobrenome do pagador. | Opcional |
payer.entity_type | String | Tipo de entidade. Use "individual" para pessoa física. | Opcional |
payer.identification | Object | Tipo e número de identificação do pagador. | Opcional |
payer.phone | Object | Telefone do pagador. Inclui: area_code, number. | Opcional |
payer.address | Object | Endereço do pagador. Inclui: street_name, street_number, zip_code, neighborhood, city, state, complement. | Opcional |
transactions | Object | Objeto de transações de pagamento. | Obrigatório |
transactions.payments | Array | Lista de pagamentos. | Obrigatório |
transactions.payments.amount | String | Valor do pagamento. | Obrigatório |
transactions.payments.payment_method.id | String | Identificador do meio de pagamento (ex: "master"). | Obrigatório |
transactions.payments.payment_method.type | String | Tipo do meio de pagamento (ex: "credit_card"). | Obrigatório |
transactions.payments.payment_method.token | String | Token do cartão gerado pela tokenização. | Obrigatório |
transactions.payments.payment_method.installments | Integer | Número de parcelas em que o pagamento é dividido. | Opcional |
transactions.payments.payment_method.statement_descriptor | String | Nome que aparece na fatura do cartão do comprador. | Opcional |
config | Object | Configuração da order. Para split, inclui split_rules. | Obrigatório |
config.split_rules.amount_type | String | Define a unidade dos valores informados em splits.amount. Os valores possíveis são: - "fixed" para valores monetários exatos. Ao usar esta unidade, a soma dos splits.amount deve ser igual ao total_amount. - "percentage" para valores percentuais. Ao usar esta unidade, a soma dos splits.amount deve ser igual a 100. | Obrigatório |
splits | Array | Array de objetos que definem os participantes do split. Máximo de 10 vendedores secundários por order. | Obrigatório |
splits.user_id | Integer | O user_id da conta do Mercado Pago do vendedor que recebe esta parte do pagamento.Importante: Este ID de usuário deve ser solicitado a cada um dos vendedores que participam na transação. O user_id do vendedor principal (owner da transação) deve estar sempre presente no array. | Obrigatório |
splits.amount | String | O valor atribuído a este participante. Dependendo do parâmetro config.split_rules.amount_type, isto pode ser: - Um valor monetário exato quando amount_type é "fixed". - Um valor percentual quando amount_type é "percentage" (os valores devem ser números inteiros). | Obrigatório |
splits.description | String | Descrição desta parte do split. | Opcional |
items | Array | Lista de itens da order. Inclui: title, description, category_id, quantity, unit_price. | Opcional |
shipment | Object | Informação de envio. Inclui address com: zip_code, street_name, street_number, neighborhood, city, complement. | Opcional |
integration_data | Object | Dados de integração. Inclui: integrator_id, platform_id. | Opcional |
Em caso de erro na solicitação, a API retornará uma resposta com o código de status HTTP correspondente. A seguir são apresentados dois exemplos de erros frequentes:
Erro 400 — Soma de valores 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": [] }
Erro 422 — Validação de usuário
json
{ "status": 422, "message": "user validation error", "errors": [] }
Se a solicitação falhar, a API retornará uma resposta com o código de status HTTP correspondente. Para ver a lista completa de erros, acesse Possíveis erros.
Para confirmar que a order foi criada corretamente com o split de pagamentos, envie um GET ao endpoint /v1/orders/{id}API, substituindo {order_id} pelo ID retornado na resposta da criação da order e utilizando seu Access Token de testeChave privada da aplicação criada no Mercado Pago, utilizada no backend. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste.Credenciais de teste.
curl
curl --request GET \ --url https://api.mercadopago.com/v1/orders/{Order_id} \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
Abaixo, você pode ver um exemplo de resposta, que permitirá verificar os detalhes do order. Você deve garantir que o status retornado seja "processed", o status_detail seja "accredited", e que o array splits esteja presente e reflita corretamente os user_id e os amount definidos na criação do order.
Você receberá uma resposta semelhante ao exemplo a seguir:
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": "MINHALOJA" }, "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" } ] }
Após confirmar a criação correta da order com o split de pagamentos, avance para Configurar notificações para acompanhar em tempo real o status das suas transações.