Split de Pagamentos

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:

Cliente paga o valor total - Uma única transação
Valor é dividido automaticamente - Entre os participantes configurados
Cada participante recebe sua parte - Direto em sua conta
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

string

required

Access token do estabelecimento participante

string

required

Tipo do participante:

PRIMARY - Estabelecimento principal (recebe o restante)
SECONDARY - Estabelecimento secundário (recebe valor fixo/percentual)

string

required

Tipo de divisão:

PERCENTAGE - Valor em porcentagem (ex: 1500 = 15%)
FIXED - Valor fixo em centavos

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

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)

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: R $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

Apenas UM participante com chargeFee: true

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, ... }
]

Soma dos splits não pode exceder 100%

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
]

Access tokens devem ser válidos

Todos os accessToken dos participantes devem existir e estar ativos no sistema.

Valores fixos não podem exceder o total

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

Início

Guias

O que é Split de Pagamentos?

Como Funciona

Tipos de Split

Split Fixo (Configurado no BD)

Split Dinâmico (Enviado no Payload)

Split Híbrido

Estrutura do Split

Campos do Split Participant

Exemplos Práticos

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

Exemplo 2: Múltiplos Participantes

Exemplo 3: Valor Fixo + Percentual

Quem Paga as Taxas?

Vendedor Paga (Padrão)

Marketplace Paga

Cálculo do Split

Com discountGrossAmount: true

Com discountGrossAmount: false

Validações e Regras

Exemplo Completo com JavaScript

Casos de Uso

Marketplace de Produtos

Plataforma de Cursos

Delivery de Comida

Eventos e Ingressos

Próximos Passos

Criar Pagamento

Webhooks

Ambientes

Erros

​O que é Split de Pagamentos?

​Como Funciona

​Tipos de Split

​Split Fixo (Configurado no BD)

​Split Dinâmico (Enviado no Payload)

​Split Híbrido

​Estrutura do Split

​Campos do Split Participant

​Exemplos Práticos

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

​Exemplo 2: Múltiplos Participantes

​Exemplo 3: Valor Fixo + Percentual

​Quem Paga as Taxas?

​Vendedor Paga (Padrão)

​Marketplace Paga

​Cálculo do Split

​Com discountGrossAmount: true

​Com discountGrossAmount: false

​Validações e Regras

​Exemplo Completo com JavaScript

​Casos de Uso

​Marketplace de Produtos

​Plataforma de Cursos

​Delivery de Comida

​Eventos e Ingressos

​Próximos Passos

Criar Pagamento

Webhooks

Ambientes

Erros

O que é Split de Pagamentos?

Como Funciona

Tipos de Split

Split Fixo (Configurado no BD)

Split Dinâmico (Enviado no Payload)

Split Híbrido

Estrutura do Split

Campos do Split Participant

Exemplos Práticos

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

Exemplo 2: Múltiplos Participantes

Exemplo 3: Valor Fixo + Percentual

Quem Paga as Taxas?

Vendedor Paga (Padrão)

Marketplace Paga

Cálculo do Split

Com discountGrossAmount: true

Com discountGrossAmount: false

Validações e Regras

Exemplo Completo com JavaScript

Casos de Uso

Marketplace de Produtos

Plataforma de Cursos

Delivery de Comida

Eventos e Ingressos

Próximos Passos