Pular para o conteúdo principal
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 o 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 Core API · Splits.
Todos os valores nesta página são inteiros em centavos. Um pagamento de R$ 100,00 é 10000. Veja Convenções.

​
Anatomia de um item de split

Uma configuração de split é uma lista (config) de itens. Cada item descreve a fatia de um recebedor:
​
recipientId
string
obrigatório
ID do recebedor que recebe esta fatia (rec_...). O recebedor precisa existir e estar vinculado ao gateway usado no pagamento.
​
value
number
obrigatório
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).
​
valueType
string
obrigatório
Como interpretar value. Um de:
  • percentage — value é um percentual.
  • fixed — value é um valor fixo em centavos.
​
type
string
padrão:"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).
​
processingFee
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.
​
liable
boolean
Indica que este recebedor é o responsável financeiro da transação — quem responde por estornos, chargebacks e absorve sobras de arredondamento. 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, o Z2Pay valida:
config não pode ser vazia.
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%”.
Nem zero, nem dois. Exatamente um item da lista deve ter processingFee: true.
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:
valueTypeFórmulaObservação
percentagefloor(valorDoPagamento × value / 100)Arredonda para baixo (trunca centavos).
fixedvalueUsado 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.
  • liable → quem é o responsável financeiro: responde por estornos/chargebacks e absorve a sobra de arredondamento (os centavos que sobraram do floor).

​
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:
RecebedorPercentualfloor(10000 × %)Após sobra
rec_lojista60%60006000
rec_parceiro40%40004000
Total100%1000010000
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.
RecebedorPercentualfloor(10001 × %)Após sobra
rec_lojista60%floor(6000,6) = 60006000 + 1 = 6001
rec_parceiro40%floor(4000,4) = 40004000
Total100%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" }
  ]
}
Recebedorvalue (centavos)Recebe
rec_fornecedorA1000010000
rec_fornecedorB30003000
rec_fornecedorC20002000
Total—15000
Em split fixo, a soma dos valores é responsabilidade sua — o 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"
    }
  ]
}
RecebedorTipofloor(10000 × %)Papel no cálculo
rec_vendedorsale9000Recebe 9000
rec_plataformaplatform_fee1000Arca 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 Core API · Splits.

​
Erros comuns

SituaçãoStatusOnde ver
Soma de percentuais diferente de 100%400Erros
Nenhum ou mais de um item com processingFee400Erros
Nenhum ou mais de um item com liable400Erros
Recebedor sem vínculo no gateway do pagamento422Erros

​
Veja também

Core API · 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.