Split de Pagamentos

Como funciona

Ao gerar um QR Code, inclua o array split no payload. Quando a transacao for paga, o valor liquido e distribuido automaticamente entre os recebedores definidos, sem nenhuma acao adicional da sua parte.

O split incide sobre o valor liquido da cobranca, ou seja, depois da taxa da plataforma. A taxa fica com a plataforma e o valor liquido restante fica automaticamente com o dono da cobranca.

Voce pode distribuir o split de duas formas:

Por percentual, usando percentageSplit
Por valor fixo em centavos, usando fixedAmountCents

Tambem e possivel misturar os dois modos no mesmo array. Percentuais sempre sao calculados sobre o valor liquido total, nao sobre o saldo restante depois dos valores fixos.

Campos do split

Campo	Tipo	Descricao
`username`	`string`	Username da conta StylePay que recebera a fatia.
`percentageSplit`	`string` ou `number`	Percentual a ser repassado. Aceita decimais, por exemplo `"10.5"`.
`fixedAmountCents`	`number`	Valor fixo em centavos. Deve ser inteiro, por exemplo `300` para R$ 3,00.

Cada item do split deve informar exatamente um modo: percentageSplit ou fixedAmountCents. Nao envie os dois no mesmo item e nao deixe os dois ausentes.

Regras

Percentual minimo por destinatario: 0.1%
Percentual maximo por destinatario: 95%
Valor fixo minimo por destinatario: 1 centavo
Soma total do split: maximo de 95% do valor liquido
O mesmo username nao pode aparecer duas vezes no array
Todos os destinatarios precisam ter conta ativa na StylePay
O dono da cobranca nao pode ser destinatario explicito do split
fixedAmount, valor em reais decimal, string monetaria e float nao sao aceitos para valor fixo

Exemplo com percentual

Inclua o objeto split junto ao payload normal de criacao de QR Code:

{
  "amount": 100,
  "external_id": "pedido-2026",
  "payer": {
    "name": "Monkey D. Luffy",
    "document": "",
    "email": ""
  },
  "postbackUrl": "",
  "split": [
    {
      "username": "parceiro1",
      "percentageSplit": "20"
    },
    {
      "username": "parceiro2",
      "percentageSplit": "10"
    }
  ]
}

Exemplo com valor fixo e percentual

Neste exemplo, a cobranca bruta e de R$ 15,00, a taxa da plataforma e R$ 1,00 e o valor liquido e R$ 14,00.

{
  "amount": 15,
  "external_id": "pedido-2026-001",
  "payer": {
    "name": "Monkey D. Luffy",
    "document": "",
    "email": ""
  },
  "postbackUrl": "",
  "split": [
    {
      "username": "alice",
      "fixedAmountCents": 300
    },
    {
      "username": "bob",
      "percentageSplit": "10"
    }
  ]
}

Calculo

Recebedor	Regra	Valor
Plataforma	Taxa	R$ 1,00
`alice`	R$ 3,00 fixo	R$ 3,00
`bob`	10% do liquido total	R$ 1,40
Dono da cobranca	Liquido restante	R$ 9,60

Exemplos invalidos

Nao envie fixedAmount; use somente fixedAmountCents:

{
  "username": "alice",
  "fixedAmount": 300
}

Nao envie valor fixo como decimal em reais, string monetaria ou float:

{
  "username": "alice",
  "fixedAmountCents": "R$ 3,00"
}

{
  "username": "alice",
  "fixedAmountCents": 300.5
}

Nao envie percentual e valor fixo no mesmo item:

{
  "username": "alice",
  "percentageSplit": "10",
  "fixedAmountCents": 300
}

Resposta

Quando o split e aceito, a resposta inclui um resumo detalhado de como o valor sera distribuido:

{
  "statusCode": 200,
  "message": "QR Code gerado com sucesso.",
  "data": {
    "payment_id": "1e6c9f53-fddb-4994-bc02-fd6fe61007fa",
    "qrcode": "00020101021226870014br.gov.bcb.pix...",
    "qrcode_image": "iVBORw0KGgoAAAANS...",
    "status": "PENDING",
    "split": {
      "mode": "MIXED",
      "total_percentage": 10,
      "total_fixed_amount_cents": 300,
      "split_amount_cents": 440,
      "owner_amount_cents": 960,
      "recipients": [
        {
          "username": "alice",
          "allocation_type": "FIXED",
          "percentage": null,
          "fixedAmountCents": 300,
          "amount_cents": 300
        },
        {
          "username": "bob",
          "allocation_type": "PERCENTAGE",
          "percentage": 10,
          "fixedAmountCents": null,
          "amount_cents": 140
        }
      ]
    }
  }
}

Os valores em amount_cents, fixedAmountCents, split_amount_cents e owner_amount_cents estao em centavos. Quando houver arredondamento em splits percentuais, a distribuicao usa o metodo Largest Remainder para garantir que nenhum centavo seja perdido.

Inicio

Pagamentos

Wallet

Webhooks

Como funciona

Campos do split

Regras

Exemplo com percentual

Exemplo com valor fixo e percentual

Calculo

Exemplos invalidos

Resposta

​Como funciona

​Campos do split

​Regras

​Exemplo com percentual

​Exemplo com valor fixo e percentual

​Calculo

​Exemplos invalidos

​Resposta

Como funciona

Campos do split

Regras

Exemplo com percentual

Exemplo com valor fixo e percentual

Calculo

Exemplos invalidos

Resposta