# Boleto Payment

Here we will teach you how to create and manage boleto payments.

### The Boleto Payment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the boleto payment. |
| `amount` | INTEGER | Payment amount in cents. |
| `barCode` | STRING | Bar code number that describes the payment. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `description` | STRING | Text displayed in the bank statement. |
| `fee` | INTEGER | Fee charged in cents. |
| `line` | STRING | Number sequence that describes the payment. |
| `scheduled` | STRING | Scheduled payment date. Example: "2020-04-23". |
| `status` | STRING | Current payment status. Options: "created", "processing", "confirmed", "success", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the boleto payment. |
| `taxId` | STRING | Receiver CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the payment. |

### Create Boleto Payments

`POST /v2/boleto-payment`

Use this route to pay registered boletos generated at Stark Bank or at other financial institutions using the available balance in your Stark Bank account.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `description` | REQUIRED | Text to be displayed in your statement. Min length = 10. |
| `taxId` | REQUIRED | Receiver CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90. |
| `amount` | OPTIONAL | Amount to be paid. If none is informed, the current boleto value will be used. Example: 23456 (= R$ 234.56) |
| `barCode` | CONDITIONALLY REQUIRED | Bar code number that describes the payment. Either "line" or "barCode" parameters are required. If both are sent, they must match. |
| `line` | CONDITIONALLY REQUIRED | Number sequence that describes the payment. Either "line" or "barCode" parameters are required. If both are sent, they must match. |
| `scheduled` | OPTIONAL | Schedule the payment for a specific date. Default value is the current day. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**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",
        tags=["little girl", "no one"],
        description="Payment for killing white walkers",
        scheduled="2020-04-25"
    )
])

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

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116311091005447947307154464000,
    created=2020-04-24 17:58:32.007153,
    description=Payment for killing white walkers,
    fee=0,
    id=6693962735681536,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-04-25 15:00:00,
    status=created,
    tags=['little girl', 'no one'],
    transaction_ids=[],
    tax_id=38.435.677/0001-25
)
```

### List Boleto Payments

`GET /v2/boleto-payment`

Get a list of non-deleted boleto payments in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter boleto payments by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**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=34198846600000116311091005447947307154464000,
    created=2020-04-24 17:58:32.007153,
    description=Payment for killing white walkers,
    fee=0,
    id=6693962735681536,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-04-25 15:00:00,
    status=created,
    tags=['little girl', 'no one'],
    transaction_ids=[],
    tax_id=38.435.677/0001-25
)
```

### Get a Boleto Payment

`GET /v2/boleto-payment/:id`

Get a single boleto payment by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the boleto payment entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116311091005447947307154464000,
    created=2020-04-24 17:58:32.007153,
    description=Payment for killing white walkers,
    fee=0,
    id=6693962735681536,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-04-25 15:00:00,
    status=created,
    tags=['little girl', 'no one'],
    transaction_ids=[],
    tax_id=38.435.677/0001-25
)
```

### Delete a Boleto Payment

`DELETE /v2/boleto-payment/:id`

Cancel a scheduled boleto payment. You can only cancel boleto payments before they start being processed.

**NOTE:**Payments that have already been processed can be deleted, but not cancelled.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the boleto payment entity. |

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116311091005447947307154464000,
    created=2020-04-24 17:58:32.007153,
    description=Payment for killing white walkers,
    fee=0,
    id=6693962735681536,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-04-25 15:00:00,
    status=canceled,
    tags=['little girl', 'no one'],
    transaction_ids=[],
    tax_id=38.435.677/0001-25
)
```

### Get a Boleto Payment PDF

`GET /v2/boleto-payment/:id/pdf`

Get a boleto payment PDF receipt. You can only get a receipt for payments whose status are either success, processing or created.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the boleto payment entity |

**Request**

```python
import starkbank

pdf = starkbank.boletopayment.pdf("6693962735681536")

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

### List Boleto Payment Logs

`GET /v2/boleto-payment/log`

Get a paged list of all boleto payment logs. A log tracks a change in the payment entity according to its life cycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `paymentIds` | OPTIONAL | Array of payment ids linked to the desired logs. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.boletopayment.log.query(
    payment_ids=["6693962735681536"]
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id=5260913007394816,
    created=2020-04-24 17:58:32.075347,
    errors=[],
    type=created,
    payment=BoletoPayment(
        amount=11631,
        bar_code=34198846600000116311091005447947307154464000,
        created=2020-04-24 17:58:32.007153,
        description=Payment for killing white walkers,
        fee=0,
        id=6693962735681536,
        line=34191.09107 05447.947309 71544.640008 8 84660000011631,
        scheduled=2020-04-25 15:00:00,
        status=created,
        tags=['little girl', 'no one'],
        transaction_ids=[],
        tax_id=38.435.677/0001-25
    )
)
```

### Get a Boleto Payment Log

`GET /v2/boleto-payment/log/:id`

Get a single boleto payment log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log entity |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

log = starkbank.boletopayment.log.get("5260913007394816")

print(log)
```

**Response**

```python
Log(
    id=5260913007394816,
    created=2020-04-24 17:58:32.075347,
    errors=[],
    type=created,
    payment=BoletoPayment(
        amount=11631,
        bar_code=34198846600000116311091005447947307154464000,
        created=2020-04-24 17:58:32.007153,
        description=Payment for killing white walkers,
        fee=0,
        id=6693962735681536,
        line=34191.09107 05447.947309 71544.640008 8 84660000011631,
        scheduled=2020-04-25 15:00:00,
        status=created,
        tags=['little girl', 'no one'],
        transaction_ids=[],
        tax_id=38.435.677/0001-25
    )
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

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