# Tax Payment

Tax Payments allow you to pay taxes such as ISS, DAS, and other tax-related boletos using your Stark Bank balance. For federal taxes without bar codes (DARFs), use the Darf Payment resource.

In the document below, we will detail the processes related to creating and managing Tax Payments and Darf Payments, providing a clear and comprehensive understanding of the operation and how to manage the lifecycle of these resources.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

Tax PaymentPay taxes with bar codes using your Stark Bank balanceDarf PaymentPay federal taxes without bar codes (DARFs) 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:

tax-payment

darf-payment

2.1. Via Internet Banking: 

Integrations > Webhook > New Webhook

2.2. Via API: 

Use the POST /webhook route to create the webhook

## Tax Payment Overview

Tax Payment is a resource that can be used to pay taxes such as ISS, DAS, and other tax-related boletos using your Stark Bank balance.

To create a Tax Payment, you need to provide the mandatory parameters: barCode (or line) and description.

Optional parameters include scheduled and tags.

### The Tax Payment Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the tax payment. |
| `amount` | INTEGER | Amount automatically calculated from the barCode. Example: 500365 (R$5,003.65). |
| `barCode` | STRING | Tax barCode. Example: "81660000005003657010074119002551100010601813". |
| `created` | STRING | Creation datetime. Example: "2020-04-18T16:22:24.664148+00:00". |
| `description` | STRING | Text to be displayed in your statement. Example: "fix the road". |
| `fee` | INTEGER | Fee charged in cents. |
| `line` | STRING | Tax payment line (digits only). Example: "81660000005 0036570100 74119002551 10001060181". |
| `scheduled` | STRING | Scheduled date or datetime for the payment. Example: "2020-04-20" or "2020-04-20T15:23:26+00:00". |
| `status` | STRING | Current payment status. Options: "created", "processing", "success", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the tax payment. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the tax payment. |
| `type` | STRING | Tax type. Example: "iss", "das". |
| `updated` | STRING | Last update datetime. Example: "2020-04-18T16:22:24.664148+00:00". |

### The Tax Payment Status

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

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

### The Tax Payment Logs

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

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

### Creating Tax Payments

To create a Tax Payment, fill in the mandatory parameters: barCode (or line) and description.

The amount is automatically calculated from the barCode.

**Request**

```python
import starkbank

payments = starkbank.taxpayment.create([
    starkbank.TaxPayment(
        bar_code="81660000005003657010074119002551100010601813",
        description="fix the road"
    )
])

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

**Response**

```python
TaxPayment(
    amount=500365,
    bar_code=81660000005003657010074119002551100010601813,
    created=2020-04-18 16:22:24.664148,
    description=fix the road,
    fee=0,
    id=5412038532661248,
    line=81660000005 0036570100 74119002551 10001060181,
    scheduled=2020-04-18 16:22:24.664148,
    status=created,
    tags=[],
    transaction_ids=[],
    type=iss,
    updated=2020-04-18 16:22:24.664148
)
```

### Creating Tax Payments with scheduled, tags parameters

Scheduled: Schedule the tax payment for a specific date.

Today is the default.

Example: "2020-04-20T15:23:26+00:00" or "2020-04-20"

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

**Request**

```python
import starkbank

payments = starkbank.taxpayment.create([
    starkbank.TaxPayment(
        bar_code="81660000005003657010074119002551100010601813",
        description="fix the road",
        scheduled="2020-04-20",
        tags=["taxes", "iss"]
    )
])

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

**Response**

```python
TaxPayment(
    amount=500365,
    bar_code=81660000005003657010074119002551100010601813,
    created=2020-04-18 16:22:24.664148,
    description=fix the road,
    fee=0,
    id=5738709764800512,
    line=81660000005 0036570100 74119002551 10001060181,
    scheduled=2020-04-20 00:00:00,
    status=created,
    tags=['taxes', 'iss'],
    transaction_ids=[],
    type=iss,
    updated=2020-04-18 16:22:24.664148
)
```

### Listing Tax Payments

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

**Request**

```python
import starkbank

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

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

**Response**

```python
TaxPayment(
    amount=500365,
    bar_code=81660000005003657010074119002551100010601813,
    created=2020-04-18 16:22:24.664148,
    description=fix the road,
    fee=200,
    id=5950134772826112,
    line=81660000005 0036570100 74119002551 10001060181,
    scheduled=2020-04-20 00:00:00,
    status=processing,
    tags=['taxes', 'iss'],
    transaction_ids=['5991715760504832'],
    type=iss,
    updated=2020-04-20 10:22:24.664148
)
```

### Getting a Tax Payment

Get a single Tax Payment by its id.

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
TaxPayment(
    amount=500365,
    bar_code=81660000005003657010074119002551100010601813,
    created=2020-04-18 16:22:24.664148,
    description=fix the road,
    fee=200,
    id=5950134772826112,
    line=81660000005 0036570100 74119002551 10001060181,
    scheduled=2020-04-20 00:00:00,
    status=processing,
    tags=['taxes', 'iss'],
    transaction_ids=['5991715760504832'],
    type=iss,
    updated=2020-04-20 10:22:24.664148
)
```

### Canceling Tax Payment

This method will allow the cancellation of a Tax Payment.

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
TaxPayment(
    amount=500365,
    bar_code=81660000005003657010074119002551100010601813,
    created=2020-04-18 16:22:24.664148,
    description=fix the road,
    fee=0,
    id=6693962735681536,
    line=81660000005 0036570100 74119002551 10001060181,
    scheduled=2020-04-20 00:00:00,
    status=canceled,
    tags=['taxes', 'iss'],
    transaction_ids=[],
    type=iss,
    updated=2020-04-18 18:12:10.225810
)
```

### Receiving Tax Payment Webhook

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

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

## Darf Payment Overview

Darf Payment is a resource that can be used to pay federal taxes without bar codes (DARFs) using your Stark Bank balance.

To create a Darf Payment, you need to provide the mandatory parameters: revenueCode, taxId, competence, nominalAmount, fineAmount, interestAmount, due, and description.

Optional parameters include scheduled, referenceNumber, and tags.

### The Darf Payment Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the DARF payment. |
| `amount` | INTEGER | Total payment amount in cents (nominalAmount + fineAmount + interestAmount). |
| `competence` | STRING | Competence month of the service. Example: "2020-03-10". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `description` | STRING | Text displayed in the bank statement. |
| `due` | STRING | Due date for payment. Example: "2020-03-10". |
| `fee` | INTEGER | Fee charged in cents. |
| `fineAmount` | INTEGER | Fixed fine amount in cents. |
| `interestAmount` | INTEGER | Interest amount in cents. |
| `nominalAmount` | INTEGER | Amount due in cents without fee or interest. |
| `referenceNumber` | STRING | Number assigned to the region of the tax. |
| `revenueCode` | STRING | 4-digit tax code assigned by Federal Revenue. Example: "5948". |
| `scheduled` | STRING | Scheduled payment date. Example: "2020-04-23". |
| `status` | STRING | Current payment status. Options: "created", "processing", "success", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the DARF payment. |
| `taxId` | STRING | Payer CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the payment. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### The Darf Payment Status

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

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

### The Darf Payment Logs

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

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

### Creating Darf Payments

To create a Darf Payment, fill in the mandatory parameters: revenueCode, taxId, competence, nominalAmount, fineAmount, interestAmount, due, and description.

The total amount is automatically calculated as nominalAmount + fineAmount + interestAmount.

**Request**

```python
import starkbank

payments = starkbank.darfpayment.create([
    starkbank.DarfPayment(
        revenue_code="1240",
        tax_id="012.345.678-90",
        competence="2023-09-01",
        nominal_amount=1234,
        fine_amount=12,
        interest_amount=34,
        due="2023-10-01",
        description="DARF Payment for revenue code 1240"
    )
])

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

**Response**

```python
DarfPayment(
    amount=1280,
    competence=2023-09-01 02:59:59.999999,
    created=2023-09-15 16:22:24.664148,
    description=DARF Payment for revenue code 1240,
    due=2023-10-01 02:59:59.999999,
    fee=0,
    fine_amount=12,
    id=5412038532661248,
    interest_amount=34,
    nominal_amount=1234,
    reference_number=,
    revenue_code=1240,
    scheduled=2023-09-15 16:22:24.664148,
    status=created,
    tags=[],
    tax_id=012.345.678-90,
    transaction_ids=[],
    updated=2023-09-15 16:22:24.664148
)
```

### Creating Darf Payments with scheduled, tags parameters

Scheduled: Schedule the DARF payment for a specific date.

Today is the default.

Example: "2020-04-20"

Tags: Array of strings to tag the entity for future queries. All tags will be converted to lowercase. Example: ["darf", "federal-tax"]

Reference Number: Number assigned to the region of the tax. Example: "08.1.17.00-4"

**Request**

```python
import starkbank

payments = starkbank.darfpayment.create([
    starkbank.DarfPayment(
        revenue_code="1240",
        tax_id="012.345.678-90",
        competence="2023-09-01",
        nominal_amount=1234,
        fine_amount=12,
        interest_amount=34,
        due="2023-10-01",
        description="DARF Payment for revenue code 1240",
        scheduled="2023-10-15",
        tags=["darf", "revenue-1240"]
    )
])

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

**Response**

```python
DarfPayment(
    amount=1280,
    competence=2023-09-01 02:59:59.999999,
    created=2023-09-15 16:22:24.664148,
    description=DARF Payment for revenue code 1240,
    due=2023-10-01 02:59:59.999999,
    fee=0,
    fine_amount=12,
    id=5738709764800512,
    interest_amount=34,
    nominal_amount=1234,
    reference_number=,
    revenue_code=1240,
    scheduled=2023-10-15 00:00:00,
    status=created,
    tags=['darf', 'revenue-1240'],
    tax_id=012.345.678-90,
    transaction_ids=[],
    updated=2023-09-15 16:22:24.664148
)
```

### Listing Darf Payments

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

**Request**

```python
import starkbank

payments = starkbank.darfpayment.query(
    after="2023-09-01",
    before="2023-09-30",
)

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

**Response**

```python
DarfPayment(
    amount=1280,
    competence=2023-09-01 02:59:59.999999,
    created=2023-09-15 16:22:24.664148,
    description=DARF Payment for revenue code 1240,
    due=2023-10-01 02:59:59.999999,
    fee=200,
    fine_amount=12,
    id=5950134772826112,
    interest_amount=34,
    nominal_amount=1234,
    reference_number=,
    revenue_code=1240,
    scheduled=2023-10-15 00:00:00,
    status=processing,
    tags=['darf', 'revenue-1240'],
    tax_id=012.345.678-90,
    transaction_ids=['5991715760504832'],
    updated=2023-10-15 10:22:24.664148
)
```

### Getting a Darf Payment

Get a single Darf Payment by its id.

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
DarfPayment(
    amount=1280,
    competence=2023-09-01 02:59:59.999999,
    created=2023-09-15 16:22:24.664148,
    description=DARF Payment for revenue code 1240,
    due=2023-10-01 02:59:59.999999,
    fee=200,
    fine_amount=12,
    id=5950134772826112,
    interest_amount=34,
    nominal_amount=1234,
    reference_number=,
    revenue_code=1240,
    scheduled=2023-10-15 00:00:00,
    status=processing,
    tags=['darf', 'revenue-1240'],
    tax_id=012.345.678-90,
    transaction_ids=['5991715760504832'],
    updated=2023-10-15 10:22:24.664148
)
```

### Canceling Darf Payment

This method will allow the cancellation of a Darf Payment.

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
DarfPayment(
    amount=1280,
    competence=2023-09-01 02:59:59.999999,
    created=2023-09-15 16:22:24.664148,
    description=DARF Payment for revenue code 1240,
    due=2023-10-01 02:59:59.999999,
    fee=0,
    fine_amount=12,
    id=6693962735681536,
    interest_amount=34,
    nominal_amount=1234,
    reference_number=,
    revenue_code=1240,
    scheduled=2023-10-15 00:00:00,
    status=canceled,
    tags=['darf', 'revenue-1240'],
    tax_id=012.345.678-90,
    transaction_ids=[],
    updated=2023-09-15 18:12:10.225810
)
```

### Receiving Darf Payment Webhook

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

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

---

## Other Languages

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