Divisão de receita (Splits)

O split divide automaticamente o dinheiro de cada pagamento entre vários recebedores. Em vez de receber tudo e repassar na mão, a PayerPix já entrega a parte certa para cada um, no momento da venda.

A ideia, com um exemplo do dia a dia 🍫

Imagine o mercado do bairro (esse é o merchant).

O dono compra caixas de bombom e entrega uma caixa para cada adolescente da vizinhança sair vendendo. O combinado é simples: quem vender ganha 50% do valor da venda, e os outros 50% voltam para o mercado.

Quando um cliente compra uma caixa por R$ 20,00, o dinheiro se divide sozinho: R$ 10,00 caem na conta do adolescente que vendeu e R$ 10,00 voltam para o mercado — na hora, sem ninguém repassar nada na mão.

Cada adolescente é um recebedor da regra. Dá para ter vários (até 10 por regra) — por exemplo, ainda separar uma fatia para quem indicou o vendedor.

Do exemplo para os conceitos

Basis points: percentuais são medidos em basis points — 10000 = 100%, 5000 = 50%, 250 = 2,5%. Isso evita arredondamentos.

Exemplo com 3 recebedores

Venda de R$ 20,00 (2000 centavos):

A soma sempre fecha 100%: o recebedor marcado como remainder leva exatamente o que sobrou.

Como configurar

As regras de split vão na própria cobrança Pix, dentro do objeto merchant, no campo recipients. Cada item é um recebedor:

{
  "amount": 2000,
  "callbackUrl": "https://sualoja.com/webhooks/payerpix",
  "merchant": {
    "externalId": "mercado-do-bairro",
    "name": "Mercado do Bairro",
    "recipients": [
      { "recipientType": "USER", "recipientId": "<UUID_VENDEDOR>", "splitValue": 5000 },
      { "recipientType": "USER", "recipientId": "<UUID_INDICOU>", "splitValue": 1000 },
      { "recipientType": "MERCHANT", "recipientId": "<UUID_MERCADO>", "isRemainder": true, "splitValue": 1 }
    ]
  }
}

São aceitos de 1 a 10 recebedores por cobrança. Com a regra no objeto merchant, toda venda que você criar com aquele merchant já entra dividida — sem repasse manual.