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

# Split de Pagamentos (Multi-Recebedores)

> Divisão automática e atômica de valores entre múltiplos parceiros na mesma cobrança PIX.

O **Split de Pagamentos** da KavroPay permite que plataformas, marketplaces, SaaS e infoprodutores dividam automaticamente o valor de uma cobrança entre duas ou mais contas no exato instante em que o cliente efetua o pagamento PIX.

A liquidação é **100% atômica e auditada**: o saldo é creditado em tempo real no saldo disponível de cada parceiro através do motor contábil da KavroPay, gerando registros de conciliação para cada participante.

```mermaid theme={null}
flowchart LR
    A[Comprador Paga R$ 150,00] --> B(KavroPay Gateway)
    B -->|Taxa 2,99% + R$ 0,50| C[Processamento Gateway]
    B -->|Split 20%: R$ 30,00| D[Conta Parceiro A]
    B -->|Split 10%: R$ 15,00| E[Conta Parceiro B]
    B -->|Saldo Líquido Restante| F[Conta Vendedor Principal]
```

***

## Como Funciona o Split

Você pode definir as regras de divisão diretamente no momento da criação da cobrança via `POST /v1/charges` adicionando o array `split`:

* **Divisão por Porcentagem (`percentage`):** Define a fatia percentual do valor bruto (ex: `20` para 20%, `10` para 10%). A soma de todas as porcentagens de uma cobrança **não pode ultrapassar 100%**.
* **Divisão por Valor Fixo (`amount` ou `amountCents`):** Define uma quantia exata em Reais (ex: `"15.00"` ou `1500`). A soma dos valores fixos não pode ultrapassar o saldo líquido da cobrança.
* **Quem Paga a Taxa da Gateway (`chargeProcessingFee`):**
  * `false` *(Padrão)*: O vendedor principal (originador) absorve a taxa integral da gateway, e o parceiro recebe o valor bruto do split.
  * `true`: A taxa da gateway é dividida proporcionalmente e debitada da fatia do recebedor.

<Warning>
  **Regra de Uniformidade:** Em uma mesma cobrança, todas as regras de split devem seguir o **mesmo modelo** (ou **todas por porcentagem**, ou **todas por valor fixo**). Não é permitido misturar regras percentuais e valores fixos no mesmo pagamento para evitar conflitos de precedência.
</Warning>

***

## Parâmetros do Objeto `split`

Cada item dentro do array `split` suporta os seguintes campos:

| Campo                 | Tipo             | Obrigatório | Descrição                                                                                   |
| :-------------------- | :--------------- | :---------- | :------------------------------------------------------------------------------------------ |
| `recipientId`         | string (UUID)    | **Sim**     | ID da empresa cadastrada na KavroPay que receberá a cota (`companyId`).                     |
| `percentage`          | number \| string | Opcional\*  | Percentual bruto destinado ao parceiro (ex: `15` para 15%, `25.5` para 25,5%).              |
| `amount`              | string \| number | Opcional\*  | Valor fixo decimal com duas casas (ex: `"25.00"` ou `"25,00"`).                             |
| `amountCents`         | integer          | Opcional\*  | Valor fixo expresso em centavos inteiros (ex: `2500` = R\$ 25,00).                          |
| `chargeProcessingFee` | boolean          | Opcional    | Se `true`, desconta a cota proporcional da taxa do gateway do recebedor. Padrão: `false`.   |
| `description`         | string           | Opcional    | Texto descritivo para identificação no extrato do parceiro (ex: `"Comissão Afiliado #99"`). |

<Note>
  \*Cada regra deve especificar **`percentage`** OU **`amount` / `amountCents`**. A soma das porcentagens não pode ultrapassar 100,00%, e a soma dos valores fixos não pode ultrapassar o valor da cobrança.
</Note>

***

## Exemplo: Criar Cobrança PIX com Split

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.kavropay.online/v1/charges \
    -H "Authorization: Bearer sk_live_sua_chave_aqui" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": "150.00",
      "description": "Pedido Marketplace #9842",
      "split": [
        {
          "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
          "percentage": 20,
          "chargeProcessingFee": false,
          "description": "Comissão Vendedor Loja 02"
        },
        {
          "recipientId": "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
          "percentage": 10,
          "chargeProcessingFee": true,
          "description": "Comissão Co-produtor"
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  async function createChargeWithSplit() {
    const response = await axios.post('https://api.kavropay.online/v1/charges', {
      amount: "150.00",
      description: "Pedido Marketplace #9842",
      split: [
        {
          recipientId: "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
          percentage: 20,
          chargeProcessingFee: false,
          description: "Comissão Vendedor Loja 02"
        },
        {
          recipientId: "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
          percentage: 10,
          chargeProcessingFee: true,
          description: "Comissão Co-produtor"
        }
      ]
    }, {
      headers: {
        'Authorization': 'Bearer sk_live_sua_chave_aqui',
        'Content-Type': 'application/json'
      }
    });

    console.log('Cobrança gerada com Split:', response.data);
  }

  createChargeWithSplit();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.kavropay.online/v1/charges"
  headers = {
      "Authorization": "Bearer sk_live_sua_chave_aqui",
      "Content-Type": "application/json"
  }

  payload = {
      "amount": "150.00",
      "description": "Pedido Marketplace #9842",
      "split": [
          {
              "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
              "percentage": 20,
              "chargeProcessingFee": False,
              "description": "Comissão Vendedor Loja 02"
          },
          {
              "recipientId": "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
              "percentage": 10,
              "chargeProcessingFee": True,
              "description": "Comissão Co-produtor"
          }
      ]
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $payload = [
    "amount" => "150.00",
    "description" => "Pedido Marketplace #9842",
    "split" => [
      [
        "recipientId" => "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "percentage" => 20,
        "chargeProcessingFee" => false,
        "description" => "Comissão Vendedor Loja 02"
      ],
      [
        "recipientId" => "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
        "percentage" => 10,
        "chargeProcessingFee" => true,
        "description" => "Comissão Co-produtor"
      ]
    ]
  ];

  $ch = curl_init("https://api.kavropay.online/v1/charges");
  curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer sk_live_sua_chave_aqui",
      "Content-Type: application/json"
    ]
  ]);

  $result = curl_exec($ch);
  curl_close($ch);
  echo $result;
  ```
</CodeGroup>

### Resposta com o Detalhamento do Split (HTTP 201 Created)

```json theme={null}
{
  "id": "PAY8F7A1B2C3D4E5F6G",
  "amount": 150.00,
  "fee": 4.99,
  "net": 145.01,
  "status": "waiting_payment",
  "pix_copy_paste": "00020126580014br.gov.bcb.pix...",
  "qr_code_base64": "iVBORw0KGgoAAAANSUhEUg...",
  "split": {
    "totalNet": 145.01,
    "originator": {
      "companyId": "a0000000-0000-0000-0000-000000000001",
      "companyName": "Minha Plataforma LTDA",
      "net": 101.01
    },
    "recipients": [
      {
        "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "recipientName": "Loja Parceira 02",
        "type": "percentage",
        "percentage": 20,
        "amount": 30.00,
        "fee": 0.00,
        "net": 30.00,
        "chargeProcessingFee": false,
        "description": "Comissão Vendedor Loja 02",
        "status": "pending"
      },
      {
        "recipientId": "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
        "recipientName": "Co-produtor",
        "type": "percentage",
        "percentage": 10,
        "amount": 15.00,
        "fee": 0.50,
        "net": 14.50,
        "chargeProcessingFee": true,
        "description": "Comissão Co-produtor",
        "status": "pending"
      }
    ]
  },
  "expires_at": "2026-09-28T14:00:00.000Z",
  "created_at": "2026-09-28T13:00:00.000Z"
}
```

***

## Simulador / Calculadora de Split

<api-endpoint method="POST" path="/v1/splits/calculate" />

Permite que sua aplicação faça uma prévia exata do rateio financeiro antes de submeter uma nova cobrança aos clientes.

```bash cURL theme={null}
curl -X POST https://api.kavropay.online/v1/splits/calculate \
  -H "Authorization: Bearer sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "split": [
      {
        "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "percentage": 25
      }
    ]
  }'
```

***

## Consultar Extrato de Splits

<api-endpoint method="GET" path="/v1/splits" />

Lista todos os splits enviados ou recebidos pela sua empresa.

### Parâmetros de Query String

* `role`: `'all'` (padrão), `'originator'` (splits gerados pela sua empresa) ou `'recipient'` (splits que sua empresa recebeu).
* `page`: Número da página (padrão: 1).
* `limit`: Itens por página (máx: 100).

```bash cURL theme={null}
curl -X GET "https://api.kavropay.online/v1/splits?role=recipient&page=1&limit=20" \
  -H "Authorization: Bearer sk_live_sua_chave_aqui"
```

***

## Notificações e Webhooks de Split

Assim que a cobrança PIX é liquidada:

1. O saldo líquido de cada recebedor é creditado instantaneamente em sua conta (`available`).
2. Uma notificação é gerada no painel de cada empresa recebedora.
3. Um registro de transferência interna é gerado para conciliação contábil em tempo real.

<CardGroup cols={2}>
  <Card title="Cobranças PIX" icon="arrow-left" horizontal href="/cobrancas-pix">
    Criar cobranças simples e links de checkout
  </Card>

  <Card title="Status Unificado" icon="arrow-right" horizontal href="/status-unificado">
    Consultar status em menos de 10ms
  </Card>
</CardGroup>