# Boleto Payment

We provide the convenience of paying registered boletos directly from your Stark Bank balance.

In the document below, we will detail the processes related to creating and managing Boleto Payments, providing a clear and comprehensive understanding of the operation and how to manage the lifecycle of this resource.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

Boleto PaymentPay registered boletos using your Stark Bank balance

## 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 in your desired URL:

boleto-payment

2.1. Via Internet Banking: 

Integrations > Webhook > New Webhook

2.2. Via API: 

Use the POST /webhook route to create the webhook

## Boleto Payment Overview

Boleto Payment is a resource that can be used to pay registered boletos from Stark Bank or other institutions.

To create a Boleto Payment, you need to provide the mandatory parameters: line, taxId and description.

Optional parameters include scheduled and tags.

### The Boleto Payment Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the boleto payment. |
| `amount` | INTEGER | Amount automatically calculated from the line or barCode. Example: 11631 (R$116.31). |
| `barCode` | STRING | Bar code number of the boleto. Example: "34198846600000116313109105447947307154464000". |
| `created` | STRING | Creation datetime. Example: "2020-02-06T16:22:24.664148+00:00". |
| `description` | STRING | Text to be displayed in your statement. Example: "Payment for killing white walkers". |
| `fee` | INTEGER | Fee charged in cents. |
| `line` | STRING | Number sequence that describes the payment. Example: "34191.09107 05447.947309 71544.640008 8 84660000011631". |
| `scheduled` | STRING | Scheduled date for the payment. Example: "2020-08-14". |
| `status` | STRING | Current payment status. Options: "created", "processing", "success", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the boleto payment. |
| `taxId` | STRING | Tax ID (CPF or CNPJ) of the payer. Example: "38.435.677/0001-25". |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the boleto payment. |

### The Boleto Payment Status

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

| Status | Description |
| --- | --- |
| Created | The Boleto Payment was successfully created in Stark Bank. |
| Processing | The Boleto Payment is being processed by Stark Bank. |
| Success | The Boleto Payment was successfully completed. |
| Failed | The Boleto Payment was unsuccessful. |
| Canceled | The Boleto Payment was canceled before processing. |

### The Boleto Payment Logs

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

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Boleto Payment was successfully created in Stark Bank. |
| Processing | Processing | The Boleto Payment is being processed. |
| Success | Success | The Boleto Payment was successfully completed. |
| Failed | Failed | The Boleto Payment was unsuccessful. |
| Canceling | Processing | The Boleto Payment cancellation is being processed. |
| Canceled | Canceled | The Boleto Payment was canceled before processing. |

### Creating Boleto Payments

To create a Boleto Payment, fill in the mandatory parameters: line, taxId and description.

The amount is automatically calculated from the line or barCode provided.

**Request**

```python
import starkbank

payments = starkbank.boletopayment.create([
    starkbank.BoletoPayment(
        line="34191.09107 05447.947309 71544.640008 8 84660000011631",
        tax_id="38.435.677/0001-25",
        description="Payment for killing white walkers"
    )
])

for payment in payments:
    print(payment)
```

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116313109105447947307154464000,
    created=2020-02-06 16:22:24.664134,
    description=Payment for killing white walkers,
    fee=0,
    id=5412038532661248,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-02-07 10:00:00,
    status=created,
    tags=[],
    tax_id=38.435.677/0001-25,
    transaction_ids=[]
)
```

### Creating Boleto Payments with scheduled, tags parameters

Scheduled: Schedule the payment for a specific date.

Today is the default.

Boleto Payments scheduled for today will be accepted until 16:00 (BRT) and will be pushed to the next business day afterwards.

Example: "2020-08-14"

Tags: Array of strings to tag the entity for future queries. All tags will be converted to lowercase. Example: ["war", "invoice/1234"]

**Request**

```python
import starkbank

payments = starkbank.boletopayment.create([
    starkbank.BoletoPayment(
        line="34191.09107 05447.947309 71544.640008 8 84660000011631",
        tax_id="38.435.677/0001-25",
        description="Payment for killing white walkers",
        scheduled="2020-08-14",
        tags=["war", "invoice/1234"]
    )
])

for payment in payments:
    print(payment)
```

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116313109105447947307154464000,
    created=2020-02-06 16:22:24.664134,
    description=Payment for killing white walkers,
    fee=0,
    id=5412038532661248,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-08-14 10:00:00,
    status=created,
    tags=['war', 'invoice/1234'],
    tax_id=38.435.677/0001-25,
    transaction_ids=[]
)
```

### Listing Boleto Payments

Get a list of Boleto Payments using filters such as after, before, status and tags to narrow the results.

**Request**

```python
import starkbank

payments = starkbank.boletopayment.query(
    after="2020-04-01",
    before="2020-04-30",
)

for payment in payments:
    print(payment)
```

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116313109105447947307154464000,
    created=2020-04-24 17:49:10.225810,
    description=Payment for killing white walkers,
    fee=0,
    id=5950134772826112,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-08-14 10:00:00,
    status=processing,
    tags=['war', 'invoice/1234'],
    tax_id=38.435.677/0001-25,
    transaction_ids=['5991715760504832']
)
```

### Getting a Boleto Payment

Get a single Boleto Payment by its id.

You can use it to check the current status of a Boleto Payment.

**Request**

```python
import starkbank

payment = starkbank.boletopayment.get("5950134772826112")

print(payment)
```

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116313109105447947307154464000,
    created=2020-04-24 17:49:10.225810,
    description=Payment for killing white walkers,
    fee=0,
    id=5950134772826112,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-08-14 10:00:00,
    status=processing,
    tags=['war', 'invoice/1234'],
    tax_id=38.435.677/0001-25,
    transaction_ids=['5991715760504832']
)
```

### Canceling Boleto Payment

This method will allow the cancellation of a boleto payment.

It's important to note that it's only possible to cancel boleto payments before the start of processing.

**Request**

```python
import starkbank

payment = starkbank.boletopayment.delete("6693962735681536")

print(payment)
```

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116313109105447947307154464000,
    created=2020-04-24 17:49:10.225810,
    description=Payment for killing white walkers,
    fee=0,
    id=6693962735681536,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-08-14 10:00:00,
    status=canceled,
    tags=['war', 'invoice/1234'],
    tax_id=38.435.677/0001-25,
    transaction_ids=[]
)
```

### Receiving Boleto Payment Webhook

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

Every time we change a Boleto Payment, we create a Log. Logs are pretty useful for understanding the life cycle of each Boleto Payment. 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-payment subscription is required to receive this event.

---

## Other Languages

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