# Split

The Split resource allows you to distribute Invoice and Boleto payments among multiple receivers automatically.

First, configure the Split Profile to define the default behavior for transferring funds. Then, register Split Receivers with their bank account details. Finally, create Invoices or Boletos with the splits parameter to split payments among your receivers.

When a payment with splits is received, a Split entity is created for each receiver. You can track these Splits to confirm when each receiver's share has been transferred.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

Split ProfileConfigure the default behavior for split transfers.Split ReceiverRegister a bank account to receive split payments.SplitSet the amount and receivers to split Invoice and Boleto payments.

## Split Profile Overview

The Split Profile defines the default behavior for transferring funds from your Workspace to the Split Receivers.

Two parameters are essential for the transfer to occur: the Interval and the Delay.

### Setting up a Split Profile

Use the Split Profile to configure how and when split funds are transferred to receivers.

Interval

The period during which the transfer of funds from the Workspace to the receiver's destination account will be conducted.

You can choose from four methods to execute the interval:

| Period | When |
| --- | --- |
| Instantaneous | - |
| Daily | Everyday at 7a.m |
| Weekly | Mondays at 7a.m |
| Monthly | Every 1st at 7a.m |

Delay

The period during which the value will be "retained" in the main Workspace until it is transferred to the receiver's destination account.

The Delay is configured by the client, allowing it to determine how long the value should be "retained" before the transfer occurs.

For clients who do not configure the Split Profile rules for interval and delay as desired, by default, the Payment Split will have the following properties:

Interval - monthly

Delay - 7 days

**Request**

```python
import starkbank

payload ={
    "interval": "day",
    "delay": 0
}
splitprofile = starkbank.splitprofile.update([payload])

for profile in splitprofile:
  print(profile)
```

**Response**

```python
SplitProfile(
  created=2023-10-24 00:23:08.831127,
  delay=0,
  id=6206954716266496,
  interval=day,
  status=created,
  tags=[],
  updated=2024-02-26 17:56:13.304200
)
```

## Split Receiver Overview

Before creating an Invoice or Boleto with splits, you need to create a Split Receiver for each party that will receive part of the payment.

Provide the receiver's name, tax ID (CPF or CNPJ), and bank account details.

### Creating a Split Receiver

Create a Split Receiver by providing the receiver's bank account details. You can create multiple receivers at once.

**Request**

```python
import starkbank

receiver = starkbank.splitreceiver.create(
      receiver=starkbank.SplitReceiver(
        name="Daenerys Targaryen Stormborn",
        tax_id="594.739.480-42",
        bank_code="665",
        branch_code="2201",
        account_number="76543-8",
        account_type="salary"
    )
)

print(receiver)
```

**Response**

```python
SplitReceiver(
    account_number=76543-8,
    account_type=salary,
    bank_code=665,
    branch_code=2201,
    created=2024-01-30 20:17:12.586145,
    id=5710191014182912,
    name=Daenerys Targaryen Stormborn,
    status=created,
    tags=[],
    tax_id=594.739.480-42,
    updated=2024-01-30 20:17:12.586152
)
```

### Listing Split Receivers

You can list all Split Receivers that match your filters.

**Request**

```python
import starkbank

receivers = starkbank.splitreceiver.query(limit=1)

for receiver in receivers:
    print(receiver)
```

**Response**

```python
SplitReceiver(
    account_number=73068305-0,
    account_type=salary,
    bank_code=18236120,
    branch_code=250,
    created=2024-01-30 20:17:12.586344,
    id=5147241060761600,
    name=Lucille Jette,
    status=created,
    tags=[],
    tax_id=949.887.518-99,
    updated=2024-01-30 20:17:13.685002
)
```

### Getting a Split Receiver

You can get a specific Split Receiver by its ID.

**Request**

```python
import starkbank

receiver = starkbank.splitreceiver.get("5155165527080960")

print(receiver)
```

**Response**

```python
SplitReceiver(
    account_number=73068305-0,
    account_type=salary,
    bank_code=18236120,
    branch_code=250,
    created=2024-01-30 20:17:12.586344,
    id=5155165527080960,
    name=Lucille Jette,
    status=created,
    tags=[],
    tax_id=949.887.518-99,
    updated=2024-01-30 20:17:13.685002
)
```

### Listing Split Receiver Logs

You can list all Split Receiver Logs to track status changes.

**Request**

```python
import starkbank

log = starkbank.splitreceiver.log.get(
    after="2024-10-30",
    before="2024-10-01"
)

print(log)
```

**Response**

```python
Log(
    created=2024-01-30 20:17:12.611535,
    errors=None,
    id=4865766084050944,
    receiver=SplitReceiver(
        account_number=73068305-0,
        account_type=salary,
        bank_code=18236120,
        branch_code=250,
        created=2024-01-30 20:17:12.586344,
        id=5147241060761600,
        name=Lucille Jette,
        status=created,
        tags=[],
        tax_id=949.887.518-99,
        updated=2024-01-30 20:17:13.712424
    ),
    type=created
)
```

### Getting a Split Receiver Log

You can get a specific Split Receiver Log by its ID.

**Request**

```python
import starkbank

log = starkbank.splitreceiver.log.get("5155165527080960")

print(log)
```

**Response**

```python
Log(
    created=2024-01-30 20:17:12.611535,
    errors=None,
    id=5155165527080960,
    receiver=SplitReceiver(
        account_number=73068305-0,
        account_type=salary,
        bank_code=18236120,
        branch_code=250,
        created=2024-01-30 20:17:12.586344,
        id=5147241060761600,
        name=Lucille Jette,
        status=created,
        tags=[],
        tax_id=949.887.518-99,
        updated=2024-01-30 20:17:13.712424
    ),
    type=created
)
```

## Split Overview

When an Invoice or Boleto with splits is paid, a Split entity is created for each receiver. You can track these Splits to confirm when each receiver's share has been transferred.

### Creating an Invoice with Split

After creating your Split Receivers, you can create an Invoice with the splits parameter.

Each split entry includes a receiver ID and the amount they should receive.

**Request**

```python
import starkbank
from datetime import datetime

invoices = starkbank.invoice.create([
    starkbank.Invoice(
        amount=400000,
        descriptions=[{'key': 'Arya', 'value': 'Not today'}],
        discounts=[{'percentage': 10, 'due': datetime(2021, 3, 12, 15, 23, 26, 689377)}],
        due=datetime(2021, 5, 12, 15, 23, 26, 689377),
        expiration=123456789,
        fine=2.5,
        interest=1.3,
        name="Arya Stark",
        tags=['War supply', 'Invoice #1234'],
        tax_id="012.345.678-90",
        splits=[
            Split(
                amount=3000,
                receiverId="5742447426535424"
            ),
            Split(
                amount=5000,
                receiverId="5743243941642240"
            )
        ]
    )
])

for invoice in invoices:
    print(invoice)
```

**Response**

```python
Invoice(
    amount=400000,
    brcode=00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79,
    created=2020-10-26 17:10:57.261868,
    descriptions=[{'key': 'Arya', 'value': 'Not today'}],
    discount_amount=0,
    discounts=[{'percentage': 10.0, 'due': '2021-03-12T18:23:26+00:00'}],
    due=2021-05-12 15:23:26,
    expiration=123456789,
    fee=0,
    pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    fine=2.5,
    fine_amount=0,
    id=4600131349381120,
    interest=1.3,
    interest_amount=0,
    name=Arya Stark,
    nominal_amount=400000,
    status=created,
    tags=['War supply', 'Invoice #1234'],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877,
    splits=[
        Split(
            amount=3000,
            receiver_id=5742447426535424
        ),
        Split(
            amount=5000,
            receiver_id=5743243941642240
        )
    ]
)
```

### Creating a Boleto with Split

You can also create a Boleto with the splits parameter. Each split entry includes a receiver ID and the amount they should receive.

If there are 3 parties in the transaction, include 3 entries — each with the receiver ID and their share.

**Request**

```python
import starkbank

boletos = starkbank.boleto.create([
    starkbank.Boleto(
        amount=400000,
        due="2020-05-20",
        name="Iron Bank S.A.",
        tax_id="20.018.183/0001-80",
        fine=2.5,
        interest=1.3,
        overdue_limit=5,
        street_line_1="Av. Faria Lima, 1844",
        street_line_2="CJ 13",
        district="Itaim Bibi",
        city="São Paulo",
        state_code="SP",
        zip_code="01500-000",
        tags=["War supply", "Invoice #1234"],
        discounts=[
            {"percentage": 10, "date": "2020-04-25"}
        ],
        splits=[
            Split(
                amount=3000,
                receiverId="5742447426535424"
            ),
            Split(
                amount=5000,
                receiverId="5743243941642240"
            )
        ]
    )
])

for boleto in boletos:
    print(boleto)
```

**Response**

```python
Boleto(
    id=6655767935451136,
    amount=400000,
    bar_code=34191826100004000001091007175647307144464000,
    city=São Paulo,
    created=2020-04-23 23:36:08.129614,
    descriptions=[],
    discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
    district=Itaim Bibi,
    due=2020-05-21,
    fee=0,
    fine=2.5,
    interest=1.3,
    line=34191.09107 07175.647309 71444.640008 1 82610000400000,
    name=Iron Bank S.A.,
    our_number=10445145,
    transaction_ids=[],
    overdue_limit=5,
    receiver_name=Winterfell S. A.,
    receiver_tax_id=71.735.814/0001-12,
    state_code=SP,
    status=created,
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=CJ 13,
    tags=['war supply', 'invoice #1234'],
    tax_id=20.018.183/0001-80,
    zip_code=01500-000,
    workspace_id=5083989094170624,
    splits=[
        Split(
            amount=3000,
            receiver_id=5742447426535424
        ),
        Split(
            amount=5000,
            receiver_id=5743243941642240
        )
    ]
)
```

### Listing Splits

You can list all Splits that match your filters. Use the after and before parameters to filter by creation date.

**Request**

```python
import starkbank

splits = starkbank.split.query(
    after="2024-01-30",
    before="2024-02-01",
    limit=1
)

for split in splits:
    print(split)
```

**Response**

```python
Split(
    amount=10000,
    created=2024-01-30 16:10:59.874663,
    external_id=invoice/5163468596445184/receiver/5143677177430016,
    id=5745664021495808,
    receiver_id=5143677177430016,
    scheduled=2024-01-30 16:10:59.840821,
    source=invoice/5163468596445184,
    status=created,
    tags=['invoice/5163468596445184'],
    updated=2024-01-30 16:21:03.973723
)
```

### Getting a Split

You can get a specific Split by its ID.

**Request**

```python
import starkbank

split = starkbank.split.get("5155165527080960")

print(split)
```

**Response**

```python
Split(
    amount=10000,
    created=2024-01-30 16:10:59.874824,
    external_id=invoice/5163468596445184/receiver/5706627130851328,
    id=5155165527080960,
    receiver_id=5706627130851328,
    scheduled=2024-01-30 16:10:59.840821,
    source=invoice/5163468596445184,
    status=created,
    tags=['invoice/5163468596445184'],
    updated=2024-01-30 16:10:59.874829
)
```

### Listing Split Logs

You can list all Split Logs to track status changes throughout the transaction lifecycle.

**Request**

```python
import starkbank

logs = starkbank.split.log.query(
    after="2020-10-01",
    before="2020-10-30"
)
for log in logs:
  print(log)
```

**Response**

```python
Log(
    created=2024-01-30 16:21:03.459601,
    errors=None,
    id=5659211052613632,
    split=Split(
        amount=10000,
        created=2024-01-30 16:10:59.874663,
        external_id=invoice/5163468596445184/receiver/5143677177430016,
        id=5745664021495808,
        receiver_id=5143677177430016,
        scheduled=2024-01-30 16:10:59.840821,
        source=invoice/5163468596445184,
        status=created,
        tags=['invoice/5163468596445184'],
        updated=2024-01-30 16:21:04.002158
    ),
    type=created
)
```

### Getting a Split Log

You can get a specific Split Log by its ID.

**Request**

```python
import starkbank

log = starkbank.split.log.get("5729450050191360")

print(log)
```

**Response**

```python
Log(
    created=2024-01-30 16:21:03.459601,
    errors=None,
    id=5729450050191360,
    split=Split(
        amount=10000,
        created=2024-01-30 16:10:59.874663,
        external_id=invoice/5163468596445184/receiver/5143677177430016,
        id=5745664021495808,
        receiver_id=5143677177430016,
        scheduled=2024-01-30 16:10:59.840821,
        source=invoice/5163468596445184,
        status=success,
        tags=['invoice/5163468596445184'],
        updated=2024-01-30 16:21:04.002158
    ),
    type=success
)
```

---

## Other Languages

- [Python](https://docs.starkbank.com/get-started/split-python.md)
- [Node.js](https://docs.starkbank.com/get-started/split-node.md)
- [PHP](https://docs.starkbank.com/get-started/split-php.md)
- [Java](https://docs.starkbank.com/get-started/split-java.md)
- [Ruby](https://docs.starkbank.com/get-started/split-ruby.md)
- [Elixir](https://docs.starkbank.com/get-started/split-elixir.md)
- [.NET](https://docs.starkbank.com/get-started/split-dotnet.md)
- [Go](https://docs.starkbank.com/get-started/split-go.md)
- [Clojure](https://docs.starkbank.com/get-started/split-clojure.md)
- [cURL](https://docs.starkbank.com/get-started/split-curl.md)