> ## Documentation Index
> Fetch the complete documentation index at: https://docs.econpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Split de Pagamentos

> Como dividir pagamentos entre múltiplos participantes

## 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.

<Warning>
  **Importante:** Deve haver exatamente **UM** participante com `chargeFee: true` (que pagará as taxas operacionais).
</Warning>

## Estrutura do Split

### Campos do Split Participant

<ParamField body="accessToken" type="string" required>
  Access token do estabelecimento participante
</ParamField>

<ParamField body="merchantType" type="string" required>
  Tipo do participante:

  * `PRIMARY` - Estabelecimento principal (recebe o restante)
  * `SECONDARY` - Estabelecimento secundário (recebe valor fixo/percentual)
</ParamField>

<ParamField body="type" type="string" required>
  Tipo de divisão:

  * `PERCENTAGE` - Valor em porcentagem (ex: 1500 = 15%)
  * `FIXED` - Valor fixo em centavos
</ParamField>

<ParamField body="chargeFee" type="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`
</ParamField>

<ParamField body="discountGrossAmount" type="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)
</ParamField>

<ParamField body="amountSplit" type="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)
</ParamField>

## Exemplos Práticos

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

**Cenário:** Marketplace cobra 15% de comissão do vendedor

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Apenas UM participante com chargeFee: true">
    Você não pode ter múltiplos participantes pagando taxas. Apenas um deve ter `chargeFee: true`.

    ❌ **Errado:**

    ```json theme={null}
    [
      { "chargeFee": true, ... },
      { "chargeFee": true, ... }  // ERRO!
    ]
    ```

    ✅ **Correto:**

    ```json theme={null}
    [
      { "chargeFee": true, ... },
      { "chargeFee": false, ... }
    ]
    ```
  </Accordion>

  <Accordion title="Soma dos splits não pode exceder 100%">
    A soma de todos os percentuais não pode ultrapassar 10000 (100%).

    ❌ **Errado:**

    ```json theme={null}
    [
      { "type": "PERCENTAGE", "amountSplit": 6000 },  // 60%
      { "type": "PERCENTAGE", "amountSplit": 5000 }   // 50% = 110% total!
    ]
    ```

    ✅ **Correto:**

    ```json theme={null}
    [
      { "type": "PERCENTAGE", "amountSplit": 6000 },  // 60%
      { "type": "PERCENTAGE", "amountSplit": 3000 }   // 30% = 90% total
    ]
    ```
  </Accordion>

  <Accordion title="Access tokens devem ser válidos">
    Todos os `accessToken` dos participantes devem existir e estar ativos no sistema.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Exemplo Completo com JavaScript

```javascript theme={null}
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: 'joao@exemplo.com',
        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

<CardGroup cols={2}>
  <Card title="Criar Pagamento" icon="credit-card" href="/api-reference/payments/create-payment">
    Ver documentação completa da API
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Receber notificações de pagamentos
  </Card>

  <Card title="Ambientes" icon="flask" href="/guides/environments">
    Testar split em sandbox
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/guides/errors">
    Códigos de erro do split
  </Card>
</CardGroup>