Split payments

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`
Static QR code	`POST /v2/in/pix/qrcodes/static`
Boleto	`POST /v2/in/boletos`

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:

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

For a received amount of BRL 100.00:

┌──────────────────────────────────────────────┐
│ Received amount              BRL 100.00        │
├──────────────────────────────────────────────┤
│ Recipient A   percentage 70  → BRL 70.00       │
│ Recipient B   percentage 30  → BRL 30.00       │
└──────────────────────────────────────────────┘

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.

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

{
  "tax_number": "12345678910",
  "name": "Recipient Name",
  "ref_type": "pix_key",
  "pix_key": "05964110000197"
}

Bank account recipient

{
  "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.

{
  "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.

"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

{
  "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

{
  "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 guide.

Next steps

Fees: charge an extra amount on top of the receivable; it works together with splits.
Cash in: create your first dynamic QR code.
Create a boleto: the full boleto request body.
Receivables overview: all cash-in guides.

Onboarding

Receivables

Payments

Operations

Trio MCP

Trio SDK

Where it applies

Configure a split

Create a split recipient

Pix key recipient

Bank account recipient

Response

Register the merchant

Complete examples

Dynamic QR code with split

Boleto with split

Next steps

​Where it applies

​Configure a split

​Create a split recipient

​Pix key recipient

​Bank account recipient

​Response

​Register the merchant

​Complete examples

​Dynamic QR code with split

​Boleto with split

​Next steps

Where it applies

Configure a split

Create a split recipient

Pix key recipient

Bank account recipient

Response

Register the merchant

Complete examples

Dynamic QR code with split

Boleto with split

Next steps