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

# Dividir o valor de uma venda (split)

> Repasse parte de cada cobrança Pix para outras contas NyxPag no momento da aprovação, por valor fixo ou percentual, com limites e erros.

O split divide o valor de uma venda entre a sua conta e outras contas NyxPag. Você manda a lista de recebedores na própria cobrança, e a NyxPag credita cada um assim que o Pix é aprovado, sem você fazer transferência nenhuma depois.

## Como funciona

<Steps>
  <Step title="Você cria a cobrança com split">
    O campo `split` entra no mesmo `POST /transactions` da cobrança normal.
  </Step>

  <Step title="O pagador paga o Pix">
    O valor da venda não muda para ele.
  </Step>

  <Step title="A NyxPag credita cada recebedor">
    Na aprovação, o valor de cada recebedor entra no **saldo disponível** dele, na hora.
  </Step>

  <Step title="Você recebe o líquido">
    A comissão sai do **seu** líquido, ao lado da tarifa da NyxPag. O que sobra é o `netAmount`.
  </Step>
</Steps>

<Note>
  O recebedor precisa ter conta na NyxPag. Quem não tem conta não recebe split.
</Note>

## Criando uma cobrança com split

Cada item de `split` tem um recebedor e **um** modo de cálculo: `amount` (valor fixo em reais) ou `percent` (percentual sobre o valor da venda). Nunca os dois no mesmo item.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.nyxpag.com.br/v1/transactions \
    -H "Authorization: Bearer $NYXPAG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 100.00,
      "externalId": "PEDIDO-2001",
      "payer": { "name": "Maria Silva", "document": "52998224725" },
      "split": [
        { "recipient": "parceiro@empresa.com", "percent": 10, "description": "Comissão do parceiro" },
        { "recipient": "12345678909", "amount": 5.00, "description": "Taxa de indicação" }
      ]
    }'
  ```

  ```javascript JavaScript theme={"dark"}
  const res = await fetch("https://api.nyxpag.com.br/v1/transactions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NYXPAG_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 100.0,
      externalId: "PEDIDO-2001",
      payer: { name: "Maria Silva", document: "52998224725" },
      split: [
        { recipient: "parceiro@empresa.com", percent: 10, description: "Comissão do parceiro" },
        { recipient: "12345678909", amount: 5.0, description: "Taxa de indicação" },
      ],
    }),
  });

  const { data } = await res.json();
  console.log(data.splitAmount, data.split);
  ```

  ```python Python theme={"dark"}
  import os
  import requests

  res = requests.post(
      "https://api.nyxpag.com.br/v1/transactions",
      headers={"Authorization": f"Bearer {os.environ['NYXPAG_API_KEY']}"},
      json={
          "amount": 100.00,
          "externalId": "PEDIDO-2001",
          "payer": {"name": "Maria Silva", "document": "52998224725"},
          "split": [
              {"recipient": "parceiro@empresa.com", "percent": 10, "description": "Comissão do parceiro"},
              {"recipient": "12345678909", "amount": 5.00, "description": "Taxa de indicação"},
          ],
      },
      timeout=15,
  )
  data = res.json()["data"]
  print(data["splitAmount"], data["split"])
  ```

  ```php PHP theme={"dark"}
  <?php
  $ch = curl_init('https://api.nyxpag.com.br/v1/transactions');
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer ' . getenv('NYXPAG_API_KEY'),
          'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'amount' => 100.00,
          'externalId' => 'PEDIDO-2001',
          'payer' => ['name' => 'Maria Silva', 'document' => '52998224725'],
          'split' => [
              ['recipient' => 'parceiro@empresa.com', 'percent' => 10, 'description' => 'Comissão do parceiro'],
              ['recipient' => '12345678909', 'amount' => 5.00, 'description' => 'Taxa de indicação'],
          ],
      ]),
  ]);
  $data = json_decode(curl_exec($ch), true)['data'];
  var_dump($data['splitAmount'], $data['split']);
  ```
</CodeGroup>

### Campos de cada item

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `recipient` | string | Sim | E-mail, CPF/CNPJ ou ID da conta NyxPag que recebe |
| `amount` | number | Um dos dois | Valor fixo em reais. Mínimo `0.01` |
| `percent` | number | Um dos dois | Percentual sobre o valor da venda, de `0.01` a `100` |
| `description` | string | Não | Até 140 caracteres |

## Resposta

A transação volta com `splitAmount` (total descontado) e `split` (uma linha por recebedor). O `netAmount` já sai descontado do split.

```json theme={"dark"}
{
  "success": true,
  "idempotent": false,
  "data": {
    "id": "txn_mabc123_0123456789abcdef",
    "externalId": "PEDIDO-2001",
    "status": "pending",
    "amount": 100,
    "fee": 0.5,
    "netAmount": 84.5,
    "splitAmount": 15,
    "split": [
      { "origin": "api", "amount": 10, "description": "Comissão do parceiro" },
      { "origin": "api", "amount": 5, "description": "Taxa de indicação" }
    ]
  },
  "requestId": "req_01H..."
}
```

<Note>
  Os valores são ilustrativos: a tarifa (`fee`) depende da sua conta. A conta do exemplo seria: R\$ 100,00 − R\$ 0,50 de tarifa − R\$ 15,00 de split = R\$ 84,50 de líquido. Em `split`, `origin: "api"` são os recebedores que você enviou. Contas ligadas a uma parceria da NyxPag também podem ter uma linha `origin: "partner"`, aplicada automaticamente.
</Note>

## Limites

| Regra | Valor |
| - | - |
| Recebedores por venda | Até **10** |
| Teto do split | O total não passa de **90%** do valor da venda |
| Seu líquido | Sempre sobra ao menos R\$ 0,01 depois da tarifa e do split |
| Recebedor repetido | Cada conta aparece uma só vez por venda |
| Recebedor igual a você | Não pode: a conta que vende não é recebedora do próprio split |

## Erros

| Código | HTTP | Quando |
| - | - | - |
| `SPLIT_INVALID` | 400 | Item sem `amount` nem `percent`, com os dois, ou valor inválido |
| `SPLIT_RECIPIENT_INVALID` | 400 | `recipient` não é e-mail, CPF/CNPJ ou ID de conta válido |
| `SPLIT_TOO_MANY_RECIPIENTS` | 400 | Mais de 10 recebedores |
| `SPLIT_RECIPIENT_NOT_FOUND` | 404 | Não existe conta NyxPag para esse recebedor, ou ela está bloqueada |
| `SPLIT_RECIPIENT_SELF` | 409 | O recebedor é a própria conta que vende |
| `SPLIT_RECIPIENT_DUPLICATED` | 409 | A mesma conta aparece mais de uma vez |
| `SPLIT_EXCEEDS_SALE` | 422 | O total do split não cabe nesta venda |

<Warning>
  O split entra na verificação de [idempotência](/guides/idempotencia). Reenviar a mesma `Idempotency-Key` ou `externalId` com um `split` diferente retorna `409 idempotency_conflict`.
</Warning>

## coverFee e split

Com `coverFee: false` (padrão), a tarifa e o split saem do seu líquido, como no exemplo acima. Com `coverFee: true`, o valor do Pix gerado fica maior que o `amount` enviado.

<Warning>
  Ao combinar `coverFee: true` com `split`, crie antes uma cobrança de R\$ 1,00 e confira `amount`, `fee`, `splitAmount` e `netAmount` na resposta. O `amount` da resposta é o valor que o pagador paga. Veja [coverFee](/guides/pix/receber#coverfee).
</Warning>

## Quando o recebedor vê o dinheiro

O crédito acontece quando a cobrança é **aprovada**, e vai para o saldo disponível do recebedor, sem reserva. Se a cobrança expirar ou falhar, ninguém é creditado. O crédito é idempotente: um webhook repetido não credita duas vezes.

<CardGroup cols={2}>
  <Card title="Receber por Pix" icon="qr-code" href="/guides/pix/receber">
    Todos os campos da cobrança e como apresentar o QR Code.
  </Card>

  <Card title="Criar cobrança Pix" icon="code" href="/api-reference/pagamentos/criar-cobrança-pix">
    Referência completa do endpoint.
  </Card>
</CardGroup>


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