> ## Documentation Index
> Fetch the complete documentation index at: https://docs.purin.cash/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`.

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.purin.cash/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": "data:image/png;base64,iVBORw0KGgo..."
  },
  "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.

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

> [!NOTE]
>
> 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.

**1. O cliente paga o valor cheio**

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

**2. Os beneficiários recebem sobre o bruto**

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

**3. A taxa desconta da sua fatia**

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

**4. Você fica com o resto**

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

> [!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.

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

## Recebendo o aviso

Cobrança com split avisa pelo **mesmo evento** de qualquer outra cobrança PIX,
`charge.paid`. É o mesmo fato do domínio, e o handler que você já tem continua valendo. O
que distingue vem no corpo: o `paymentId` começa com `psplit_` e chegam `gatewayFeeCents`,
`netAmountCents` e o array `splits` com o que cada um recebeu: os mesmos números do `GET`
acima, sem precisar consultar.

O corpo também traz quem pagou (`payer`, `cpf`, `bank`) quando o banco de origem
informa.

> [card] [Corpo completo do evento](https://docs.purin.cash/webhooks/pagamentos.md#cobrança-com-split)
>
> Campo a campo, com exemplo.

> [!WARNING]
>
> O `callbackUrl` da cobrança com split só passou a disparar recentemente. Se você integrou
> antes e concluiu que o campo não fazia nada, o evento agora chega. Confira se o seu
> handler não vai tratar `psplit_` como cobrança desconhecida.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.