Dividir o valor (split)

Split é uma cobrança PIX comum com uma lista de beneficiários. Quando o cliente paga, o valor já cai partido na carteira de cada conta, com evento financeiro auditável. Você não precisa receber tudo e repassar depois. Funciona em POST /v1/charges com o campo splits, ou em POST /v1/split-charges, que é o mesmo endpoint com outro nome.

A regra que confunde todo mundo

Você não entra na lista. O splits leva só os outros beneficiários. Como dono da chave de API, você é participante implícito e fica com o que sobrar: 100 - soma das percentages.

Isso tem duas consequências práticas:

A soma das percentage precisa ser menor que 100, nunca igual.
A sua fatia precisa ser estritamente a maior de todas. Se sobrar para você menos do que para algum beneficiário, a criação é rejeitada com 400.

Criando

curl -X POST https://api.purincash.com/v1/charges \
  -H "Authorization: Bearer $PURINCASH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 10000,
    "description": "Venda compartilhada",
    "callbackUrl": "https://minhaloja.com/webhooks/purincash",
    "splits": [
      { "recipientEmail": "socio@exemplo.com", "percentage": 30 }
    ],
    "customer": { "name": "Cliente", "email": "cliente@exemplo.com" }
  }'

Resposta 201

{
  "paymentId": "psplit_a1b2c3d4",
  "status": "pending",
  "amountCents": 10000,
  "currency": "BRL",
  "environment": "live",
  "pix": {
    "brCode": "00020126360014BR.GOV.BCB.PIX...",
    "qrCodeImage": null
  },
  "splits": [
    { "recipientEmail": "vo***@exemplo.com", "percentage": 70, "isOwner": true },
    { "recipientEmail": "so***@exemplo.com", "percentage": 30, "isOwner": false }
  ],
  "expiresAt": "2026-05-28T12:30:00.000Z"
}

Repare que a resposta devolve três coisas que você não mandou: a sua própria fatia (isOwner: true), os e-mails mascarados e o prefixo psplit_.

E-mail de beneficiário vem sempre mascarado, em toda resposta e todo webhook. Se você precisa exibir o parceiro na sua interface, guarde o e-mail do seu lado no momento em que criou a cobrança.

Validações

Regra	Limite
Quantidade de beneficiários	1 a 9, além de você (10 no total)
`percentage` de cada um	0.01 a 99.99
Soma das `percentage`	Menor que 100.00
Sua fatia	Estritamente a maior
`recipientEmail`	Conta PurinCash existente, única na lista, diferente da sua
`amountCents`	80 a 500000 (R$ 0,80 a R$ 5.000,00)

Qualquer uma quebrada devolve 400 na criação. Nada é criado pela metade.

O teto de R$ 5.000 vale só para cobrança com split. Cobrança PIX comum não tem esse limite.

Quem paga a taxa

A taxa do gateway sai inteira da sua parte. Os outros beneficiários recebem a porcentagem cheia sobre o valor bruto.

O cliente paga o valor cheio

R$ 100,00, ou seja, 10000 centavos.

Os beneficiários recebem sobre o bruto

O sócio com 30% leva R$ 30,00.

A taxa desconta da sua fatia

Supondo 2% + R$ 0,50, a taxa é R$ 2,50.

Você fica com o resto

10000 − 3000 − 250 = 6750 centavos, ou R$ 67,50.

Se a taxa for maior que a sua fatia, você recebe 0. Nunca fica negativo, mas fica em zero. Vale conferir isso quando a sua margem é apertada e o valor da cobrança é baixo.

Arredondamento

Cada beneficiário recebe floor(bruto × percentage). O resto é seu, o que garante que a soma creditada mais a taxa feche exatamente com o bruto, sem centavo sumido. Um caso com dízima, para deixar concreto. Cobrança de R$ 100,00, taxa de R$ 2,50, dois beneficiários com 33.33% cada, você com 33.34%:

Quem	Conta	Recebe
Beneficiário A	`floor(10000 × 0.3333)`	3333 centavos
Beneficiário B	`floor(10000 × 0.3333)`	3333 centavos
Você	`10000 − 3333 − 3333 − 250`	3084 centavos

3333 + 3333 + 3084 + 250 = 10000. Fecha.

Consultando o resultado

GET /v1/charges/{paymentId} com um ID psplit_ traz o detalhamento de cada fatia, com o valor em centavos que foi creditado e quando:

{
  "paymentId": "psplit_a1b2c3d4",
  "status": "paid",
  "amountCents": 10000,
  "gatewayFeeCents": 250,
  "netAmountCents": 9750,
  "splits": [
    {
      "recipientEmail": "vo***@exemplo.com",
      "percentage": 70,
      "isOwner": true,
      "amountCents": 6750,
      "creditedAt": "2026-05-28T12:15:00.000Z"
    },
    {
      "recipientEmail": "so***@exemplo.com",
      "percentage": 30,
      "isOwner": false,
      "amountCents": 3000,
      "creditedAt": "2026-05-28T12:15:00.000Z"
    }
  ],
  "paidAt": "2026-05-28T12:15:00.000Z"
}

Use amountCents de cada split, e não percentage × total recalculado por você. O arredondamento já foi decidido no crédito, e refazer a conta gera divergência de um centavo no seu relatório.

Limitação conhecida

metadata não é aceito em cobrança com splits. Se você precisa amarrar a cobrança a um pedido interno, guarde o paymentId do seu lado na hora da criação.

Comece por aqui

Receber

Produtos e entrega

Dinheiro na conta

Referência rápida

Dividir o valor (split)

A regra que confunde todo mundo

Criando

Validações

Quem paga a taxa

Arredondamento

Consultando o resultado

Limitação conhecida

​A regra que confunde todo mundo

​Criando

​Validações

​Quem paga a taxa

​Arredondamento

​Consultando o resultado

​Limitação conhecida

A regra que confunde todo mundo

Criando

Validações

Quem paga a taxa

Arredondamento

Consultando o resultado

Limitação conhecida