# Boleto

Learn how to charge your customers using Boletos on the Stark Bank platform.

A Boleto is a Brazilian payment slip that lets you collect payments from anyone with a bank account. You create it with an amount and payer details, and your customer pays it through their bank — online or at a physical location.

You can track each Boleto through its full life cycle: from creation to payment, expiration, or cancellation. Set up a webhook to receive updates automatically.

For advanced use cases, you can investigate payment status updates with Boleto Holmes.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

BoletoThe payment slip you generate to charge your customer.Boleto HolmesInvestigates Boleto status updates in less than an hour.

## Setup

For each environment (Sandbox or Production):

1. Create an account at Stark Bank.

2. Create a webhook with the following subscriptions to receive events at your desired URL:

boleto

2.1. Via Internet Banking:

Integrations > Webhook > New Webhook

2.2. Via API:

Use the POST /webhook route to create the webhook

## Sandbox

The Sandbox environment simulates the full Boleto flow — creation, payment, and cancellation — without real money. Use it to test your integration before going live.

Sandbox vs Production: Stark Bank uses separate workspaces for each environment, each with its own URL and API keys. Changes in one environment don't affect the other.

If you don't have a Sandbox workspace yet, create one here:

Create a Workspace in Sandbox

## Boleto Overview

A Boleto is a registered bar code used to receive payments from your customers. You provide the amount and the payer's details, and Stark Bank registers it with the central system (CIP/Núclea).

You can customize Boletos with due dates, fines, interest rates, discounts, descriptions, and tags. You can also specify a custom receiver name and tax ID.

### The Boleto Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the boleto. |
| `amount` | INTEGER | Amount in cents to be charged. Example: 100 (R$1.00). |
| `barCode` | STRING | Boleto bar code. |
| `city` | STRING | Customer city name. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `descriptions` | LIST OF OBJECTS | List of description objects. |
| `discounts` | LIST OF OBJECTS | List of discount objects. |
| `district` | STRING | Customer district name. |
| `due` | STRING | Due date of the boleto. Example: "2020-04-23". |
| `fee` | INTEGER | Fee charged in cents. |
| `fine` | FLOAT | Percentage charged if paid after due date. |
| `interest` | FLOAT | Monthly percentage charged if paid after due date. |
| `line` | STRING | Boleto line number. |
| `name` | STRING | Customer full name. |
| `ourNumber` | STRING | Boleto control number (nosso numero). |
| `overdueLimit` | INTEGER | Number of days after due date until boleto expires. |
| `receiverName` | STRING | Name of the credit receiver (Sacador Avalista). |
| `receiverTaxId` | STRING | Tax ID of the credit receiver. |
| `stateCode` | STRING | Customer state code. |
| `status` | STRING | Current boleto status. Options: "created", "overdue", "paid", "canceled". |
| `streetLine1` | STRING | Customer street address. |
| `streetLine2` | STRING | Customer street address complement. |
| `tags` | LIST OF STRINGS | Tags associated with the boleto. |
| `taxId` | STRING | Customer CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the boleto. |
| `workspaceId` | STRING | ID of the workspace that created the boleto. |
| `zipCode` | STRING | Customer zip code. |

### The Boleto Status

Each Boleto has a status that can change over time according to its life cycle:

| Status | Description |
| --- | --- |
| Created | The Boleto was successfully created and is waiting to be registered. |
| Registered | The Boleto was registered with CIP and can now be paid. |
| Overdue | The Boleto has passed its due date and may now incur fines and interest. |
| Paid | The Boleto was paid by the payer. |
| Canceled | The Boleto was canceled and can no longer be paid. |
| Failed | The Boleto registration with CIP failed. |

### The Boleto Logs

Every time either you or Stark Bank makes a change to a Boleto, we create a Log. Logs are pretty useful for understanding the life cycle of each Boleto and the changes that happened to it. Here you can see the flow of possible logs:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Boleto was successfully created in Stark Bank. |
| Registered | Registered | The Boleto was registered with CIP and is ready to be paid. |
| Failed | Failed | The Boleto registration with CIP failed. |
| Overdue | Overdue | The Boleto has passed its due date. |
| Paid | Paid | The Boleto was paid by the payer. |
| Credited | Paid | The Boleto payment was credited to your account. |
| Canceling | Canceled | The Boleto is being canceled at CIP. |
| Canceled | Canceled | The Boleto was successfully canceled. |

### Creating a Boleto

To create a Boleto, provide the required parameters: amount (in cents), the payer's name, tax ID (CPF or CNPJ), and full address.

You can also include optional parameters such as due date, fine, interest, overdue limit, receiver details, discounts, descriptions, and tags.

**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",
        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"]
    )
])

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=[],
    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,
    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,
    transaction_ids=[],
    zip_code=01500-000,
    workspace_id=5083989094170624
)
```

### Setting Due Date, Fine, and Interest

You can set a due date for the Boleto in ISO format. The default due date is 2 days after creation.

Use fine to charge a percentage if the customer pays after the due date. Use interest to add monthly interest. Use overdueLimit to set how many seconds after the due date the Boleto stays valid (default: 5,097,600 seconds, or 59 days).

**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"]
    )
])

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=[],
    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,
    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,
    transaction_ids=[],
    zip_code=01500-000,
    workspace_id=5083989094170624
)
```

### Setting Receiver Name and Tax ID

You can set a custom receiver name and tax ID (Sacador Avalista) for the Boleto. If not provided, the workspace owner's name and tax ID are used.

Both receiverName and receiverTaxId must be provided together.

**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",
        receiver_name="Night King",
        receiver_tax_id="012.345.678-90",
        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"]
    )
])

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=[],
    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,
    overdue_limit=5,
    receiver_name=Night King,
    receiver_tax_id=012.345.678-90,
    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,
    transaction_ids=[],
    zip_code=01500-000,
    workspace_id=5083989094170624
)
```

### Adding Discounts, Descriptions, and Tags

Use discounts to offer up to 5 early-payment discounts, each with a percentage and a deadline.

Use tags to label the Boleto for easier filtering and organization. Tags are converted to lowercase.

Use descriptions to add up to 15 key-value pairs that explain the reason for the charge.

**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",
        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"}
        ]
    )
])

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,
    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,
    transaction_ids=[],
    zip_code=01500-000,
    workspace_id=5083989094170624
)
```

### Getting a Boleto PDF

You can download a Boleto as a PDF file using its ID. This is useful for sending the payment slip to your customer by email or displaying it on your website.

**Request**

```python
import starkbank

pdf = starkbank.boleto.pdf("6655767935451136")

with open("boleto.pdf", "wb") as file:
    file.write(pdf)
```

### Listing Boletos

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

**Request**

```python
import starkbank

boletos = starkbank.boleto.query(
    after="2020-04-01",
    before="2020-05-01",
    limit=1
)

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=[],
    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,
    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,
    transaction_ids=[],
    zip_code=01500-000,
    workspace_id=5083989094170624
)
```

### Canceling a Boleto

You can cancel a Boleto by its ID. This sends a cancellation request to CIP. Once canceled, the Boleto can no longer be paid.

**Request**

```python
import starkbank

boleto = starkbank.boleto.delete("6655767935451136")

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=[],
    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,
    overdue_limit=5,
    receiver_name=Winterfell S. A.,
    receiver_tax_id=71.735.814/0001-12,
    state_code=SP,
    status=canceled,
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=CJ 13,
    tags=["war supply", "invoice #1234"],
    tax_id=20.018.183/0001-80,
    transaction_ids=[],
    zip_code=01500-000,
    workspace_id=5083989094170624
)
```

### Receiving Boleto Webhook

After creation, you can use asynchronous Webhooks to monitor status changes of the entity. The Boleto will follow the following life cycle:

Every time we change a Boleto, we create a Log. Logs are pretty useful for understanding the life cycle of each Boleto. Whenever a new Log is created, we will fire a Webhook to your registered URL.

NOTE: Check the Webhook Get Started for more details on how to receive and process Webhook events.

NOTE: A boleto subscription is required to receive this event.

## Boleto Holmes Overview

Boleto Holmes lets you investigate a Boleto's current status with CIP (the Brazilian payment clearing house) in less than an hour. This is useful when you need faster status updates than the standard notification flow.

Since results are delivered asynchronously, set up a boleto-holmes webhook subscription to receive investigation results.

### Creating a Boleto Holmes

Create a Boleto Holmes by providing the Boleto ID you want to investigate. The investigation starts with status solving and changes to solved once complete.

After a Holmes is solved, it does not update again. Create a new one if you need a fresh investigation.

**Request**

```python
import starkbank

holmes = starkbank.boletoholmes.create([
    starkbank.BoletoHolmes(
        boleto_id="5656565656565656",
        tags=["sherlock", "holmes"],
    )
])

for holmes in holmes:
    print(holmes)
```

**Response**

```python
BoletoHolmes(
    boleto_id=5656565656565656,
    created=2020-07-23 00:07:51.069587,
    id=3232323232323232,
    result=,
    status=solving,
    tags=["sherlock", "holmes"],
    updated=2020-07-23 00:07:51.069597
)
```

---

## Other Languages

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