Cálculo de split

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.

Todos os valores nesta página são inteiros em centavos. Um pagamento de R$ 100,00 é 10000. Veja Convenções.

Como o split chega à transação. O split se liga por pagamento, ao criar a transação (POST /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.

Anatomia de um item de split

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

string

required

ID do recebedor que recebe esta fatia (rec_...). O recebedor precisa existir e estar vinculado ao gateway usado no pagamento.

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

string

required

Como interpretar value. Um de:

percentage — value é um percentual.
fixed — value é um valor fixo em centavos.

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

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.

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.

Regras de validação

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

A lista precisa ter pelo menos 1 item

config não pode ser vazia.

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%”.

Exatamente 1 item com processingFee

Nem zero, nem dois. Exatamente um item da lista deve ter processingFee: true.

Exatamente 1 item com liable

Mesma regra: exatamente um item deve ter liable: true.

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.

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

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.

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

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.

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.

{
  "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.

{
  "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`

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.

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

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.

{
  "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.

Erros comuns

Situação	Status	Onde ver
Soma de percentuais diferente de 100%	400	Erros
Nenhum ou mais de um item com `processingFee`	400	Erros
Nenhum ou mais de um item com `liable`	400	Erros
Recebedor sem vínculo no gateway do pagamento	400	Erros

Veja também

Referência: Splits

CRUD de configurações de split e consulta dos splits de um pagamento.

Recebedores

Cadastre os recebedores (rec_) que entram no split.

Visão geral de valores

Como taxas, split e liquidação se encaixam.

Liquidação

Quando e como cada fatia é liquidada para o recebedor.

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Anatomia de um item de split

Regras de validação

Como o valor de cada fatia é calculado

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

Arredondamento via responsável (sobra)

Exemplo 1 — Split percentual simples (60/40)

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

Exemplo 3 — Valores fixos com vários recebedores

Quando existe `platform_fee`

Exemplo 4 — Marketplace com `platform_fee`

Onde o split aparece depois

Erros comuns

Veja também

Referência: Splits

Recebedores

Visão geral de valores

Liquidação

​Anatomia de um item de split

​Regras de validação

​Como o valor de cada fatia é calculado

​processingFee e liable, em uma frase cada

​Arredondamento via responsável (sobra)

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

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

​Exemplo 3 — Valores fixos com vários recebedores

​Quando existe platform_fee

​Exemplo 4 — Marketplace com platform_fee

​Onde o split aparece depois

​Erros comuns

​Veja também

Referência: Splits

Recebedores

Visão geral de valores

Liquidação

Anatomia de um item de split

Regras de validação

Como o valor de cada fatia é calculado

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

Arredondamento via responsável (sobra)

Exemplo 1 — Split percentual simples (60/40)

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

Exemplo 3 — Valores fixos com vários recebedores

Quando existe `platform_fee`

Exemplo 4 — Marketplace com `platform_fee`

Onde o split aparece depois

Erros comuns

Veja também