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

# Cálculo de split

> Como a Z2Pay divide o valor de um pagamento entre vários recebedores, com exemplos numéricos em centavos.

Split é a divisão do valor de um pagamento entre dois ou mais recebedores (`rec_`). Você define uma
configuração de split (percentual ou valores fixos), e a Z2Pay calcula quanto cada recebedor recebe,
quem arca com a taxa de processamento e quem é o responsável financeiro pela transação.

Esta página explica **como o cálculo funciona**, com exemplos numéricos. Para criar, editar e listar
configurações de split (o CRUD da API), veja [Referência: Splits](/pt-BR/splits).

<Note>
  Todos os valores nesta página são **inteiros em centavos**. Um pagamento de R\$ 100,00 é `10000`.
  Veja [Convenções](/pt-BR/convencoes).
</Note>

<Note>
  **Como o split chega à transação.** O split se liga por **pagamento**, ao criar a transação
  ([`POST /transactions`](/pt-BR/transactions)): cada item de `payments[]` aceita `splitId`
  (referência a uma configuração de split salva, prefixo `spl_`) **ou** `split` (a mesma `config`
  inline). Os dois são **mutuamente exclusivos**. Para o CRUD das configurações, veja
  [Referência: Splits](/pt-BR/splits).
</Note>

***

## Anatomia de um item de split

Uma configuração de split é uma lista (`config`) de **itens**. Cada item descreve a fatia de um
recebedor:

<ParamField path="recipientId" type="string" required>
  ID do recebedor que recebe esta fatia (`rec_...`). O recebedor precisa existir e estar vinculado ao
  gateway usado no pagamento.
</ParamField>

<ParamField path="value" type="number" required>
  Valor da fatia. Mínimo `0.01`. Quando `valueType` é `percentage`, é o percentual (ex.: `60` = 60%).
  Quando é `fixed`, é o valor em **centavos** (ex.: `3000` = R\$ 30,00).
</ParamField>

<ParamField path="valueType" type="string" required>
  Como interpretar `value`. Um de:

  * `percentage` — `value` é um percentual.
  * `fixed` — `value` é um valor fixo em centavos.
</ParamField>

<ParamField path="type" type="string" default="sale">
  Natureza da fatia. Um de:

  * `sale` — fatia de venda (padrão).
  * `interest` — fatia de juros/acréscimo.
  * `platform_fee` — fatia da plataforma (taxa de marketplace). Tem efeito especial no cálculo (veja
    [Quando existe `platform_fee`](#quando-existe-platform_fee)).
</ParamField>

<ParamField path="processingFee" type="boolean">
  Indica que este recebedor arca com a taxa de processamento (MDR/adquirência) do pagamento.
  **Opcional no item**, mas a configuração inteira precisa ter **exatamente um** item com
  `processingFee: true`.
</ParamField>

<ParamField path="liable" type="boolean">
  Indica que este recebedor é o **responsável financeiro** da transação — quem responde por
  estornos e chargebacks. **Opcional no item**, mas a configuração inteira precisa ter
  **exatamente um** item com `liable: true`.
</ParamField>

***

## Regras de validação

Ao salvar ou usar uma configuração de split, a Z2Pay valida:

<AccordionGroup>
  <Accordion title="A lista precisa ter pelo menos 1 item">
    `config` não pode ser vazia.
  </Accordion>

  <Accordion title="Se for percentual, a soma precisa ser 100%">
    Quando os itens usam `valueType: "percentage"`, a soma de todos os `value` deve ser exatamente
    `100` (tolerância de 0.01). Caso contrário, a requisição é rejeitada com a mensagem
    "Soma dos percentuais deve ser 100%".
  </Accordion>

  <Accordion title="Exatamente 1 item com processingFee">
    Nem zero, nem dois. Exatamente um item da lista deve ter `processingFee: true`.
  </Accordion>

  <Accordion title="Exatamente 1 item com liable">
    Mesma regra: exatamente um item deve ter `liable: true`.
  </Accordion>
</AccordionGroup>

<Warning>
  As regras de `processingFee` e `liable` valem para a configuração como um todo. Se você montar a
  lista sem nenhum (ou com mais de um) item marcado, a validação falha. Erros de validação de
  payload retornam **400** (`VALIDATION_ERROR`); veja [Erros](/pt-BR/erros).
</Warning>

***

## Como o valor de cada fatia é calculado

O valor (`amount`) de cada item, em centavos, depende do `valueType`:

| `valueType`  | Fórmula                                 | Observação                                  |
| ------------ | --------------------------------------- | ------------------------------------------- |
| `percentage` | `floor(valorDoPagamento × value / 100)` | Arredonda **para baixo** (trunca centavos). |
| `fixed`      | `value`                                 | Usado tal qual (já está em centavos).       |

<Info>
  O arredondamento de percentuais é sempre **para baixo** (`floor`). Por isso a soma das fatias pode
  ficar **alguns centavos abaixo** do valor total — essa sobra é tratada na próxima seção.
</Info>

***

## `processingFee` e `liable`, em uma frase cada

* **`processingFee`** → quem **paga a taxa de processamento** (MDR/adquirência) daquele pagamento
  **e absorve a sobra de arredondamento** (os centavos que sobraram do `floor`).
* **`liable`** → quem é o **responsável financeiro**: responde por **estornos e chargebacks**.

***

## Arredondamento via responsável (sobra)

Quando a soma das fatias não bate exatamente com o valor do pagamento (efeito do `floor` nos
percentuais), a diferença restante é somada à fatia do **responsável pela taxa**. Assim o split
sempre fecha com o valor total, ao centavo.

<Tip>
  Na prática: o recebedor que arca com a taxa de processamento é também quem recebe (ou perde) os
  centavos de arredondamento. Isso mantém a conta exata sem distribuir frações entre todos.
</Tip>

***

## Exemplo 1 — Split percentual simples (60/40)

Pagamento de **R\$ 100,00** (`10000` centavos), dividido entre dois recebedores: 60% para o lojista,
40% para um parceiro. O lojista arca com a taxa e é o responsável.

```json theme={null}
{
  "name": "Lojista + parceiro 60/40",
  "config": [
    {
      "recipientId": "rec_lojista",
      "type": "sale",
      "value": 60,
      "valueType": "percentage",
      "processingFee": true,
      "liable": true
    },
    {
      "recipientId": "rec_parceiro",
      "type": "sale",
      "value": 40,
      "valueType": "percentage"
    }
  ]
}
```

Cálculo sobre `10000`:

| Recebedor      | Percentual | `floor(10000 × %)` | Após sobra  |
| -------------- | ---------- | ------------------ | ----------- |
| `rec_lojista`  | 60%        | `6000`             | `6000`      |
| `rec_parceiro` | 40%        | `4000`             | `4000`      |
| **Total**      | 100%       | **`10000`**        | **`10000`** |

Neste caso não há sobra: `6000 + 4000 = 10000`.

***

## Exemplo 2 — Arredondamento (sobra vai pro responsável)

Pagamento de **R\$ 100,01** (`10001` centavos), mesmo split 60/40.

| Recebedor      | Percentual | `floor(10001 × %)`       | Após sobra          |
| -------------- | ---------- | ------------------------ | ------------------- |
| `rec_lojista`  | 60%        | `floor(6000,6)` = `6000` | `6000 + 1` = `6001` |
| `rec_parceiro` | 40%        | `floor(4000,4)` = `4000` | `4000`              |
| **Total**      | 100%       | `10000` (falta `1`)      | **`10001`**         |

`6000 + 4000 = 10000`, faltou `1` centavo para fechar os `10001`. Como `rec_lojista` é quem arca com
a taxa (`processingFee: true`), ele **absorve a sobra** e recebe `6001`. O split fecha exato.

***

## Exemplo 3 — Valores fixos com vários recebedores

Pagamento de **R\$ 150,00** (`15000` centavos), dividido em valores fixos para três recebedores. O
primeiro arca com a taxa e é o responsável.

```json theme={null}
{
  "name": "Três fornecedores (fixo)",
  "config": [
    {
      "recipientId": "rec_fornecedorA",
      "type": "sale",
      "value": 10000,
      "valueType": "fixed",
      "processingFee": true,
      "liable": true
    },
    { "recipientId": "rec_fornecedorB", "type": "sale", "value": 3000, "valueType": "fixed" },
    { "recipientId": "rec_fornecedorC", "type": "sale", "value": 2000, "valueType": "fixed" }
  ]
}
```

| Recebedor         | `value` (centavos) | Recebe      |
| ----------------- | ------------------ | ----------- |
| `rec_fornecedorA` | `10000`            | `10000`     |
| `rec_fornecedorB` | `3000`             | `3000`      |
| `rec_fornecedorC` | `2000`             | `2000`      |
| **Total**         | —                  | **`15000`** |

<Warning>
  Em split **fixo**, a soma dos valores é responsabilidade sua — a Z2Pay não força que ela bata com o
  valor do pagamento. Se a soma das fatias fixas não fechar com o total, a diferença vai para a fatia
  do responsável pela taxa (mesmo mecanismo de sobra do Exemplo 2). Garanta que os fixos somem o que
  você espera.
</Warning>

<Note>
  Você **não pode misturar** percentual e fixo na lógica de soma: se houver itens `percentage`, a
  soma deles precisa ser 100%. Mantenha a configuração consistente (todos percentuais somando 100, ou
  valores fixos coerentes com o pagamento).
</Note>

***

## Quando existe `platform_fee`

Se algum item da configuração tem `type: "platform_fee"`, a **plataforma** (dona da `platform_fee`)
assume automaticamente o papel de responsável, independentemente dos flags individuais:

* A fatia `platform_fee` passa a ser quem **arca com a taxa de processamento**.
* A fatia `platform_fee` passa a ser a **`liable`** (responsável financeira).
* A fatia `platform_fee` **absorve a sobra de arredondamento**.

Ou seja: existindo `platform_fee`, os flags `processingFee`/`liable` dos demais itens não mudam quem
assume taxa/responsabilidade no cálculo — a plataforma assume. Use `platform_fee` para modelar a taxa
do marketplace.

### Exemplo 4 — Marketplace com `platform_fee`

Pagamento de **R\$ 100,00** (`10000` centavos): 90% para o vendedor, 10% de taxa da plataforma.

```json theme={null}
{
  "name": "Marketplace 90/10",
  "config": [
    {
      "recipientId": "rec_vendedor",
      "type": "sale",
      "value": 90,
      "valueType": "percentage",
      "processingFee": true,
      "liable": true
    },
    {
      "recipientId": "rec_plataforma",
      "type": "platform_fee",
      "value": 10,
      "valueType": "percentage"
    }
  ]
}
```

| Recebedor        | Tipo           | `floor(10000 × %)` | Papel no cálculo                       |
| ---------------- | -------------- | ------------------ | -------------------------------------- |
| `rec_vendedor`   | `sale`         | `9000`             | Recebe `9000`                          |
| `rec_plataforma` | `platform_fee` | `1000`             | Arca com taxa, `liable`, absorve sobra |
| **Total**        | —              | **`10000`**        | —                                      |

Mesmo que `rec_vendedor` tenha `processingFee: true` e `liable: true` no JSON, como existe um item
`platform_fee` é a **plataforma** que assume taxa e responsabilidade no cálculo das regras enviadas
ao gateway. A configuração ainda precisa respeitar a regra de "exatamente 1 `processingFee` e 1
`liable`" na hora de salvar.

***

## Onde o split aparece depois

Cada pagamento processado com split gera registros de **split de pagamento** (um por recebedor),
com o `amount` calculado em centavos, o `type`, o `valueType`, e os flags `processingFee`/`liable`
efetivos. Você consulta esses registros pela [Referência: Splits](/pt-BR/splits).

***

## Erros comuns

| Situação                                      | Status | Onde ver              |
| --------------------------------------------- | ------ | --------------------- |
| Soma de percentuais diferente de 100%         | 400    | [Erros](/pt-BR/erros) |
| Nenhum ou mais de um item com `processingFee` | 400    | [Erros](/pt-BR/erros) |
| Nenhum ou mais de um item com `liable`        | 400    | [Erros](/pt-BR/erros) |
| Recebedor sem vínculo no gateway do pagamento | 400    | [Erros](/pt-BR/erros) |

***

## Veja também

<CardGroup cols={2}>
  <Card title="Referência: Splits" icon="git-fork" href="/pt-BR/splits">
    CRUD de configurações de split e consulta dos splits de um pagamento.
  </Card>

  <Card title="Recebedores" icon="users" href="/pt-BR/recipients">
    Cadastre os recebedores (`rec_`) que entram no split.
  </Card>

  <Card title="Visão geral de valores" icon="calculator" href="/pt-BR/valores/visao-geral">
    Como taxas, split e liquidação se encaixam.
  </Card>

  <Card title="Liquidação" icon="banknote" href="/pt-BR/valores/liquidacao">
    Quando e como cada fatia é liquidada para o recebedor.
  </Card>
</CardGroup>