Splits

Splits permitem distribuir automaticamente uma fração do valor líquido de uma transação para outros vendedores cadastrados na plataforma — sem intervenção manual. É útil para modelos de co-venda, royalties, parcerias e repasses automáticos.

Como funciona

Ao criar uma transação, envie o campo splits com a lista de destinatários e a fração que cada um deve receber — por percentual (percentage_bps), por valor fixo (amount_cents), ou os dois combinados. Quando o pagamento for confirmado, a Buck calcula e credita automaticamente cada parcela no saldo de cada vendedor.

Valor bruto da transação
  − Taxas da plataforma
  = Valor líquido

Por split:
  (Valor líquido × percentage_bps / 10000)  +  (amount_cents / 100)  →  creditado ao parceiro

Valor líquido − soma de todos os splits  →  creditado ao dono da transação

Se um split enviar percentage_bps e amount_cents ao mesmo tempo, os dois valores são somados: o parceiro recebe a fração percentual do valor líquido mais o valor fixo — não é "valor fixo primeiro, percentual sobre o restante".

Campo splits no body

Cada item da lista splits aceita os seguintes campos:

Regras e validações

• Identificação do destinatário: informe exatamente um entre email ou id por split — nunca os dois, nunca nenhum
• Valor do split: informe ao menos um entre percentage_bps ou amount_cents por split; os dois juntos são permitidos e somados
• Mínimo de percentage_bps: 1 bp (0,01%)
• Máximo de percentage_bps por split: 9000 bp (90%)
• Mínimo de amount_cents: 1 centavo
• Soma de percentage_bps: a soma dos percentage_bps de todos os splits da transação não pode ultrapassar 9000 bp (90% do valor líquido)
• Máximo de splits por transação: 5
• Sem destinatários repetidos: o mesmo vendedor não pode aparecer mais de uma vez na mesma transação, mesmo que identificado de formas diferentes (por exemplo, email numa entrada e id do mesmo vendedor noutra)
• Vendedor de destino: precisa existir na Buck, estar com status ativo, e não pode ser o próprio vendedor que está criando a transação
• Os splits são calculados sobre o valor líquido (após taxas), não sobre o valor bruto
• Liberação do saldo: para Pix, o saldo do split fica disponível imediatamente na confirmação do pagamento; para cartão e boleto segue a janela de disponibilidade configurada do vendedor (padrão D+2 e D+1, respectivamente)

Atenção: a soma de todos os splits (mais eventuais comissões de afiliado) não pode ultrapassar o valor líquido da transação. Essa verificação acontece na confirmação do pagamento, não na criação da transação — se os valores enviados excederem o valor líquido no momento do pagamento, a distribuição inteira falha silenciosamente e nenhum saldo (nem o do dono da transação) é gerado para aquele pagamento. Da mesma forma, um destinatário duplicado só é rejeitado nesse mesmo momento, como um erro genérico — depois que a cobrança ao comprador já foi processada. Garanta que email/id sejam únicos e que a soma dos valores não ultrapasse 90% do valor líquido antes de enviar a transação.

Exemplo

Transação de R$ 100,00 com taxa de 5% e um split de 20% para um parceiro:

Request

{
  "external_id": "pedido-456",
  "payment_method": "pix",
  "amount": 10000,
  "buyer": {
    "name": "Maria Souza",
    "email": "maria@email.com"
  },
  "splits": [
    {
      "email": "parceiro@email.com",
      "percentage_bps": 2000
    }
  ]
}

Split por valor fixo (amount_cents)

Em vez de um percentual, é possível repassar um valor fixo em centavos — útil para taxas de intermediação ou royalties fixos:

{
  "splits": [
    {
      "id": "6d1b2e2a-9f3c-4a4e-8b1a-2c9b8f7a1234",
      "amount_cents": 500
    }
  ]
}

Neste caso o destinatário é identificado pelo id (UUID) do vendedor na Buck, e recebe exatamente R$ 5,00, independentemente do valor líquido da transação.

Combinando percentage_bps e amount_cents no mesmo split

{
  "splits": [
    {
      "email": "parceiro@email.com",
      "percentage_bps": 1000,
      "amount_cents": 300
    }
  ]
}

O parceiro recebe 10% do valor líquido + R$ 3,00 fixos no mesmo split.

Múltiplos splits

É possível enviar até 5 splits na mesma transação, misturando identificação por email ou id, e valor por percentage_bps ou amount_cents:

{
  "splits": [
    { "email": "parceiro-a@email.com", "percentage_bps": 1500 },
    { "id": "6d1b2e2a-9f3c-4a4e-8b1a-2c9b8f7a1234", "amount_cents": 1000 }
  ]
}

Neste caso, 15% do valor líquido vai para o parceiro A e R$ 10,00 fixos vão para o parceiro identificado por id. O vendedor principal fica com o restante.

Erros

Split sem email nem id, ou com os dois

{
  "error": {
    "message": "Invalid request body.",
    "detail": {
      "splits": ["Cada split deve ter exatamente um dos campos: 'id' ou 'email'."]
    }
  }
}

Split sem percentage_bps nem amount_cents

{
  "error": {
    "message": "Invalid request body.",
    "detail": {
      "splits": ["Cada split deve ter ao menos um dos campos: 'percentage_bps' ou 'amount_cents'."]
    }
  }
}

Mais de 5 splits na mesma transação

{
  "error": {
    "message": "Invalid request body.",
    "detail": {
      "splits": ["O máximo de splits por transação é 5."]
    }
  }
}

Soma de percentage_bps acima de 9000 (90%)

{
  "error": {
    "message": "Invalid request body.",
    "detail": {
      "splits": ["A soma dos 'percentage_bps' dos splits não pode ultrapassar 9000 (90% do valor líquido)."]
    }
  }
}

Destinatário não encontrado

{
  "error": {
    "message": "invalid_split",
    "detail": "Nenhum seller encontrado com o identificador 'parceiro@email.com'."
  }
}

Destinatário é o próprio vendedor da transação

{
  "error": {
    "message": "split_seller_not_found",
    "detail": "O identificador 'parceiro@email.com' pertence ao próprio seller e não pode receber um split."
  }
}

Vendedor inativo

{
  "error": {
    "message": "split_seller_inactive",
    "detail": "O seller com o identificador 'parceiro@email.com' não está ativo."
  }
}

Destinatário duplicado, ou soma dos splits acima do valor líquido

Essas duas condições não são detectadas na criação da transação — apenas na confirmação do pagamento, depois que o comprador já foi cobrado. Nesse caso a resposta do webhook/consulta da transação indica falha genérica de processamento, e nenhum saldo é creditado (nem para os destinatários dos splits, nem para o dono da transação). Evite reenviar o mesmo destinatário mais de uma vez e mantenha a soma dos valores dentro do valor líquido esperado.

Visualização no dashboard

• Extrato (Balances): os vendedores que receberam splits visualizam as entradas com o tipo Split (badge laranja) no extrato
• Transações: o dono da transação vê um indicador Split na listagem e, nos detalhes, o percentual e o valor total distribuído