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

# Split payments

> Distribute the amount of a receivable among split recipients on QR codes and boletos.

A split distributes the amount received by a receivable among one or more split recipients. It is configured the same way on dynamic QR codes, static QR codes and boletos. All examples use fictitious data and the sandbox base URL `https://api.sandbox.trio.com.br`.

## Where it applies

| Receivable | Create endpoint |
| - | - |
| Dynamic QR code | [`POST /v2/in/pix/qrcodes`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/qrcode-dynamic/post) |
| Static QR code | [`POST /v2/in/pix/qrcodes/static`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/qrcode-static/post) |
| Boleto | [`POST /v2/in/boletos`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/boletos/post) |

Splits are optional. When you omit the `splits` array, the receivable is created without any split.

## Configure a split

Send the top-level `splits` array in the create request:

```json theme={null}
"splits": [
  {
    "type": "percentage",
    "value": 70,
    "counterparty_recipient_id": "0198aaaa-1111-2222-3333-444444444444"
  },
  {
    "type": "percentage",
    "value": 30,
    "counterparty_recipient_id": "0198bbbb-5555-6666-7777-888888888888"
  }
]
```

Each item describes one portion of the split:

| Field | Required | Description |
| - | - | - |
| `type` | Yes | How `value` is interpreted: `percentage` or `fixed`. |
| `value` | Yes | Percentage (`0` to `100`) when `type` is `percentage`, or a fixed amount in cents (BRL 100.00 = `10000`) when `type` is `fixed`. |
| `counterparty_recipient_id` | Yes | UUID of the split recipient that receives this portion. See [Create a split recipient](#create-a-split-recipient). |

For a received amount of BRL 100.00:

```text theme={null}
┌──────────────────────────────────────────────┐
│ Received amount              BRL 100.00        │
├──────────────────────────────────────────────┤
│ Recipient A   percentage 70  → BRL 70.00       │
│ Recipient B   percentage 30  → BRL 30.00       │
└──────────────────────────────────────────────┘
```

> [!NOTE]
>
> **Coming from V1?** The array is named `splits` in V2; V1 called it `split`.

## Create a split recipient

A split entry always references a `counterparty_recipient_id`: the identifier of a split recipient that you create beforehand with [`POST /v2/counterparty_recipients`](https://docs.trio.com.br/v2/api-reference/banking-api/counterparties/recipients/create-counterparty-recipient).

```http theme={null}
POST /v2/counterparty_recipients
```

The recipient carries the counterparty identity (`tax_number`, `name`) and a reference selected by `ref_type`. Send the reference fields at the top level of the body; which ones are required depends on `ref_type`.

| Field | Required | Description |
| - | - | - |
| `tax_number` | Always | Counterparty CPF or CNPJ. |
| `name` | Always | Counterparty name. |
| `ref_type` | Always | `pix_key` or `bank_account_detailed`. |
| `pix_key` | When `ref_type` is `pix_key` | Pix key of the recipient. |
| `ispb` | When `ref_type` is `bank_account_detailed` | Bank ISPB. |
| `branch` | When `ref_type` is `bank_account_detailed` | Branch. |
| `number` | When `ref_type` is `bank_account_detailed` | Account number. |
| `digit` | When `ref_type` is `bank_account_detailed` | Account digit. |
| `type` | When `ref_type` is `bank_account_detailed` | Account type: `checking`, `payment`, `salary` or `savings`. |

### Pix key recipient

```json theme={null}
{
  "tax_number": "12345678910",
  "name": "Recipient Name",
  "ref_type": "pix_key",
  "pix_key": "05964110000197"
}
```

### Bank account recipient

```json theme={null}
{
  "tax_number": "12345678910",
  "name": "Recipient Name",
  "ref_type": "bank_account_detailed",
  "ispb": "12345678",
  "branch": "0001",
  "number": "87654321",
  "digit": "1",
  "type": "checking"
}
```

### Response

The response returns the recipient `id`. Use it as `counterparty_recipient_id` in your split configurations.

```json theme={null}
{
  "data": {
    "id": "1fb05245-a185-0ec1-2661-3390353a35e3",
    "ref_type": "pix_key",
    "pix_key": "05964110000197",
    "bank_account": null,
    "counterparty": {
      "id": "018df099-093e-cfd1-4500-4c9392eb5d8a",
      "name": "Recipient Name",
      "tax_number": "12345678910"
    }
  }
}
```

## Register the merchant

When a receivable is split, you can also register the merchant that owns the split with the `merchant` object. When sent, it is saved as the organization's split merchant.

```json theme={null}
"merchant": {
  "name": "Merchant Name",
  "tax_number": "12345678000199"
}
```

| Field | Required | Description |
| - | - | - |
| `name` | Yes | Merchant name. |
| `tax_number` | Yes | Merchant CPF or CNPJ. |

## Complete examples

### Dynamic QR code with split

```json theme={null}
{
  "amount": 10000,
  "external_id": "qr-demo-2026-001",
  "bank_account_id": "019f0000-1234-5678-9abc-000000000001",
  "counterparty": {
    "name": "Payer Name",
    "tax_number": "12345678901"
  },
  "description": "Pedido 12345",
  "options": {
    "allow_change_the_amount_on_payment": false,
    "show_qrcode_image": true
  },
  "splits": [
    {
      "type": "percentage",
      "value": 70,
      "counterparty_recipient_id": "0198aaaa-1111-2222-3333-444444444444"
    },
    {
      "type": "percentage",
      "value": 30,
      "counterparty_recipient_id": "0198bbbb-5555-6666-7777-888888888888"
    }
  ],
  "merchant": {
    "name": "Merchant Name",
    "tax_number": "12345678000199"
  }
}
```

### Boleto with split

```json theme={null}
{
  "amount": 10000,
  "external_id": "boleto-demo-2026-001",
  "bank_account_id": "019f0000-1234-5678-9abc-000000000001",
  "invoice_type": "invoice",
  "wallet_type": "book_entry_electronic_bloquete",
  "expiration_date": "2026-10-30",
  "counterparty": {
    "name": "Maria Silva",
    "tax_number": "12345678901",
    "address": "Rua das Flores, 100",
    "district": "Centro",
    "city": "Sao Paulo",
    "state": "SP",
    "postal_code": "01001000"
  },
  "due_detail": {
    "due_date": "2026-08-17"
  },
  "splits": [
    {
      "type": "percentage",
      "value": 70,
      "counterparty_recipient_id": "0198aaaa-1111-2222-3333-444444444444"
    },
    {
      "type": "percentage",
      "value": 30,
      "counterparty_recipient_id": "0198bbbb-5555-6666-7777-888888888888"
    }
  ],
  "merchant": {
    "name": "Merchant Name",
    "tax_number": "12345678000199"
  }
}
```

For the remaining boleto fields (discounts, fine, interest, boleto type), see the [Create a boleto](https://docs.trio.com.br/v2/guides/boleto/create-boleto.md) guide.

## Next steps

* [Fees](https://docs.trio.com.br/v2/guides/receivables/fees.md): charge an extra amount on top of the receivable; it works together with splits.
* [Cash in](https://docs.trio.com.br/v2/guides/receivables/cash-in.md): create your first dynamic QR code.
* [Create a boleto](https://docs.trio.com.br/v2/guides/boleto/create-boleto.md): the full boleto request body.
* [Receivables overview](https://docs.trio.com.br/v2/guides/receivables/overview.md): all cash-in guides.


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