Skip to main content

​
O que é Split de Pagamentos?

Split de pagamentos permite dividir o valor de uma transação entre múltiplos participantes (estabelecimentos). É ideal para marketplaces, plataformas e negócios que precisam distribuir valores automaticamente.

​
Como Funciona

Quando um pagamento é processado com split:
  1. Cliente paga o valor total - Uma única transação
  2. Valor é dividido automaticamente - Entre os participantes configurados
  3. Cada participante recebe sua parte - Direto em sua conta
  4. Taxas são distribuídas - Conforme configuração

​
Tipos de Split

​
Split Fixo (Configurado no BD)

Participantes configurados previamente no banco de dados. São aplicados automaticamente em todos os pagamentos do estabelecimento. Configuração: Via dashboard ou API de configuração

​
Split Dinâmico (Enviado no Payload)

Participantes enviados diretamente na requisição de pagamento. Permite flexibilidade para cada transação. Configuração: Campo splitParticipants no payload

​
Split Híbrido

Combina participantes fixos + dinâmicos. Os participantes dinâmicos se somam aos fixos.
Importante: Deve haver exatamente UM participante com chargeFee: true (que pagará as taxas operacionais).

​
Estrutura do Split

​
Campos do Split Participant

​
accessToken
string
required
Access token do estabelecimento participante
​
merchantType
string
required
Tipo do participante:
  • PRIMARY - Estabelecimento principal (recebe o restante)
  • SECONDARY - Estabelecimento secundário (recebe valor fixo/percentual)
​
type
string
required
Tipo de divisão:
  • PERCENTAGE - Valor em porcentagem (ex: 1500 = 15%)
  • FIXED - Valor fixo em centavos
​
chargeFee
boolean
required
Se este participante paga as taxas operacionais
  • true - Este participante paga as taxas
  • false - Não paga taxas
Regra: Apenas UM participante pode ter chargeFee: true
​
discountGrossAmount
boolean
required
Se desconta do valor bruto ou líquido
  • true - Desconta do valor bruto (antes das taxas)
  • false - Desconta do valor líquido (após taxas)
​
amountSplit
number
required
Valor da divisão:
  • Se type: PERCENTAGE - Valor em centavos representando % (1500 = 15%)
  • Se type: FIXED - Valor fixo em centavos (5000 = R$ 50,00)

​
Exemplos Práticos

​
Exemplo 1: Marketplace Simples (15% de comissão)

Cenário: Marketplace cobra 15% de comissão do vendedor 
{
  "access_token": "token_vendedor",
  "customer": { ... },
  "items": [{
    "name": "Produto",
    "quantity": 1,
    "price": 10000  // R$ 100,00
  }],
  "payment": {
    "type": "pix",
    "installments": 1
  },
  "subtotal": 10000,
  "total": 10000,
  "splitParticipants": [
    {
      "accessToken": "token_marketplace",
      "merchantType": "SECONDARY",
      "type": "PERCENTAGE",
      "chargeFee": false,
      "discountGrossAmount": true,
      "amountSplit": 1500  // 15%
    }
  ]
}
Resultado:
  • Marketplace recebe: R$ 15,00 (15%)
  • Vendedor recebe: R$ 85,00 (85%)

​
Exemplo 2: Múltiplos Participantes

Cenário: Venda com afiliado + marketplace 
{
  "access_token": "token_vendedor",
  "customer": { ... },
  "items": [{
    "name": "Curso Online",
    "quantity": 1,
    "price": 50000  // R$ 500,00
  }],
  "payment": {
    "type": "credit",
    "installments": 3,
    "credit_card": { ... }
  },
  "subtotal": 50000,
  "total": 50000,
  "splitParticipants": [
    {
      "accessToken": "token_afiliado",
      "merchantType": "SECONDARY",
      "type": "PERCENTAGE",
      "chargeFee": false,
      "discountGrossAmount": true,
      "amountSplit": 2000  // 20% para afiliado
    },
    {
      "accessToken": "token_marketplace",
      "merchantType": "SECONDARY",
      "type": "PERCENTAGE",
      "chargeFee": false,
      "discountGrossAmount": true,
      "amountSplit": 1000  // 10% para marketplace
    }
  ]
}
Resultado:
  • Afiliado recebe: R$ 100,00 (20%)
  • Marketplace recebe: R$ 50,00 (10%)
  • Vendedor recebe: R$ 350,00 (70%)

​
Exemplo 3: Valor Fixo + Percentual

Cenário: Taxa fixa de entrega + comissão percentual 
{
  "access_token": "token_restaurante",
  "customer": { ... },
  "items": [{
    "name": "Refeição",
    "quantity": 1,
    "price": 8000  // R$ 80,00
  }],
  "payment": {
    "type": "pix",
    "installments": 1
  },
  "shipping": {
    "name": "Entrega",
    "price": 1000  // R$ 10,00
  },
  "subtotal": 8000,
  "total": 9000,
  "splitParticipants": [
    {
      "accessToken": "token_entregador",
      "merchantType": "SECONDARY",
      "type": "FIXED",
      "chargeFee": false,
      "discountGrossAmount": false,
      "amountSplit": 1000  // R$ 10,00 fixo
    },
    {
      "accessToken": "token_plataforma",
      "merchantType": "SECONDARY",
      "type": "PERCENTAGE",
      "chargeFee": false,
      "discountGrossAmount": true,
      "amountSplit": 1500  // 15%
    }
  ]
}
Resultado:
  • Entregador recebe: R$ 10,00 (fixo)
  • Plataforma recebe: R13,50(15 13,50 (15% de R 90,00)
  • Restaurante recebe: R$ 66,50

​
Quem Paga as Taxas?

Use o campo chargeFee para definir quem paga as taxas de processamento:

​
Vendedor Paga (Padrão)

{
  "splitParticipants": [
    {
      "accessToken": "token_marketplace",
      "merchantType": "SECONDARY",
      "type": "PERCENTAGE",
      "chargeFee": false,  // Marketplace NÃO paga
      "discountGrossAmount": true,
      "amountSplit": 1500
    }
  ]
}
O vendedor (access_token principal) paga as taxas.

​
Marketplace Paga

{
  "splitParticipants": [
    {
      "accessToken": "token_marketplace",
      "merchantType": "SECONDARY",
      "type": "PERCENTAGE",
      "chargeFee": true,  // Marketplace PAGA
      "discountGrossAmount": true,
      "amountSplit": 1500
    }
  ]
}
O marketplace assume as taxas de processamento.

​
Cálculo do Split

​
Com discountGrossAmount: true

Desconta do valor bruto (antes das taxas): 
Valor Total: R$ 100,00
Taxa (3%): R$ 3,00
Split 15%: R$ 15,00 (15% de R$ 100,00)

Participante 1: R$ 15,00
Participante 2: R$ 82,00 (R$ 100 - R$ 15 - R$ 3)

​
Com discountGrossAmount: false

Desconta do valor líquido (após taxas): 
Valor Total: R$ 100,00
Taxa (3%): R$ 3,00
Valor Líquido: R$ 97,00
Split 15%: R$ 14,55 (15% de R$ 97,00)

Participante 1: R$ 14,55
Participante 2: R$ 82,45

​
Validações e Regras

Você não pode ter múltiplos participantes pagando taxas. Apenas um deve ter chargeFee: true.❌ Errado:
[
  { "chargeFee": true, ... },
  { "chargeFee": true, ... }  // ERRO!
]
✅ Correto:
[
  { "chargeFee": true, ... },
  { "chargeFee": false, ... }
]
A soma de todos os percentuais não pode ultrapassar 10000 (100%).❌ Errado:
[
  { "type": "PERCENTAGE", "amountSplit": 6000 },  // 60%
  { "type": "PERCENTAGE", "amountSplit": 5000 }   // 50% = 110% total!
]
✅ Correto:
[
  { "type": "PERCENTAGE", "amountSplit": 6000 },  // 60%
  { "type": "PERCENTAGE", "amountSplit": 3000 }   // 30% = 90% total
]
Todos os accessToken dos participantes devem existir e estar ativos no sistema.
Se usar type: FIXED, a soma dos valores fixos não pode ser maior que o valor total da transação.

​
Exemplo Completo com JavaScript

async function createPaymentWithSplit() {
  const response = await fetch('https://api.econpay.com.br/payments/order', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      access_token: 'token_vendedor_principal',
      customer: {
        name: 'João da Silva',
        email: '[email protected]',
        document: '12345678900',
        phone: {
          country_code: '55',
          area_code: '11',
          number: '999999999'
        }
      },
      items: [{
        name: 'Produto Marketplace',
        quantity: 1,
        price: 10000  // R$ 100,00
      }],
      payment: {
        type: 'pix',
        installments: 1
      },
      shipping: {
        name: 'Digital',
        price: 0
      },
      subtotal: 10000,
      total: 10000,
      // SPLIT: Marketplace fica com 15%
      splitParticipants: [
        {
          accessToken: 'token_marketplace',
          merchantType: 'SECONDARY',
          type: 'PERCENTAGE',
          chargeFee: false,
          discountGrossAmount: true,
          amountSplit: 1500  // 15%
        }
      ]
    })
  });
  
  const payment = await response.json();
  
  if (payment.success) {
    console.log('✅ Pagamento criado com split');
    console.log('Pedido:', payment.transaction.order_number);
    console.log('QR Code PIX:', payment.transaction.pix_qr_code);
  }
}

​
Casos de Uso

​
Marketplace de Produtos

  • Vendedor recebe 85%
  • Marketplace recebe 15%

​
Plataforma de Cursos

  • Instrutor recebe 70%
  • Afiliado recebe 20%
  • Plataforma recebe 10%

​
Delivery de Comida

  • Restaurante recebe valor da comida
  • Entregador recebe taxa de entrega (fixo)
  • Plataforma recebe comissão (%)

​
Eventos e Ingressos

  • Produtor recebe 80%
  • Plataforma recebe 15%
  • Promoter recebe 5%

​
Próximos Passos

Criar Pagamento

Ver documentação completa da API

Webhooks

Receber notificações de pagamentos

Ambientes

Testar split em sandbox

Erros

Códigos de erro do split