> ## Documentation Index
> Fetch the complete documentation index at: https://docs.purincash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dividir o valor (split)

> Marketplace, comissão e sociedade resolvidos no instante em que o dinheiro entra.

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

<Warning>
  **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`.
</Warning>

Isso tem duas consequências práticas:

1. A soma das `percentage` precisa ser **menor que 100**, nunca igual.
2. 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

```bash theme={null}
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" }
  }'
```

```json Resposta 201 theme={null}
{
  "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_`.

<Note>
  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.
</Note>

## 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.

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

## 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.

<Steps>
  <Step title="O cliente paga o valor cheio">
    R\$ 100,00, ou seja, 10000 centavos.
  </Step>

  <Step title="Os beneficiários recebem sobre o bruto">
    O sócio com 30% leva R\$ 30,00.
  </Step>

  <Step title="A taxa desconta da sua fatia">
    Supondo 2% + R\$ 0,50, a taxa é R\$ 2,50.
  </Step>

  <Step title="Você fica com o resto">
    10000 − 3000 − 250 = 6750 centavos, ou R\$ 67,50.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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:

```json theme={null}
{
  "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"
}
```

<Tip>
  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.
</Tip>

## 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.