# Darf Payment

Here we will explain how to manually pay DARFs without bar codes.

### The Darf Payment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the DARF payment. |
| `amount` | INTEGER | Total payment amount in cents. |
| `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. |
| `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 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". |

### Create Darf payments

`POST /v2/darf-payment`

Use this route to pay Darfs using the available balance in your Stark Bank account.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `competence` | REQUIRED | Competence month of the service. Example: '2020-03-10' |
| `description` | REQUIRED | Text to be displayed in your statement (min. 10 characters). Example: "payment ABC" |
| `due` | REQUIRED | Due date for payment. Example: '2020-03-10' |
| `fineAmount` | REQUIRED | Fixed amount due in cents for fines. Example: 234 (= R$ 2.34) |
| `interestAmount` | REQUIRED | Amount due in cents for interest. Example: 456 (= R$ 4.56) |
| `nominalAmount` | REQUIRED | Amount due in cents without fee or interest. Example: 23456 (= R$ 234.56) |
| `revenueCode` | REQUIRED | 4-digit tax code assigned by Federal Revenue. Example: "5948" |
| `taxId` | REQUIRED | Payer CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90 |
| `referenceNumber` | OPTIONAL | Number assigned to the region of the tax. Example: "08.1.17.00-4" |
| `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.darfpayment.create([
    starkbank.DarfPayment(
        revenue_code="1240",
        tax_id="12.345.678/0001-95",
        competence="2021-03-01",
        reference_number="2340978970",
        nominal_amount=1234,
        fine_amount=12,
        interest_amount=34,
        due="2021-05-12",
        scheduled="2021-03-12",
        tags=["DARF", "making money"],
        description="take my money",
    )
])

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

**Response**

```python
DarfPayment(
    amount=1280,
    competence=2021-03-01 02:59:59.999999,
    created=2021-02-20 14:39:15.565841,
    description=take my money,
    due=2021-05-12 02:59:59.999999,
    fee=0,
    fine_amount=12,
    id=5116552814788608,
    interest_amount=34,
    nominal_amount=1234,
    reference_number=2340978970,
    revenue_code=1240,
    scheduled=2021-03-012 15:00:00,
    status=created,
    tags=['darf', 'making money'],
    tax_id=12.345.678/0001-95,
    transaction_ids=[],
    updated=2021-02-20 14:39:15.565841
)
```

### List Darf Payments

`GET /v2/darf-payment`

Get a list of non-deleted Darf 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. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter Darfs by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

payments = starkbank.darfpayment.query(
    after="2021-02-01",
    before="2021-02-28"
)

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

**Response**

```python
DarfPayment(
    amount=1280,
    competence=2021-03-01 02:59:59.999999,
    created=2021-02-20 14:39:15.565841,
    description=take my money,
    due=2021-05-12 02:59:59.999999,
    fee=0,
    fine_amount=12,
    id=5116552814788608,
    interest_amount=34,
    nominal_amount=1234,
    reference_number=2340978970,
    revenue_code=1240,
    scheduled=2021-03-012 15:00:00,
    status=created,
    tags=['darf', 'making money'],
    tax_id=12.345.678/0001-95,
    transaction_ids=[],
    updated=2021-02-20 14:39:15.565841
)
```

### Get a Darf Payment

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

Get a single Darf payment by its id.

**Parameters**

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
DarfPayment(
    amount=1280,
    competence=2021-03-01 02:59:59.999999,
    created=2021-02-20 14:39:15.565841,
    description=take my money,
    due=2021-05-12 02:59:59.999999,
    fee=0,
    fine_amount=12,
    id=5116552814788608,
    interest_amount=34,
    nominal_amount=1234,
    reference_number=2340978970,
    revenue_code=1240,
    scheduled=2021-03-012 15:00:00,
    status=created,
    tags=['darf', 'making money'],
    tax_id=12.345.678/0001-95,
    transaction_ids=[],
    updated=2021-02-20 14:39:15.565841
)
```

### Delete a Darf Payment

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

Cancel a scheduled Darf payment. You can only cancel a Darf payment while its status is still "created", before backend processing begins.

**NOTE:**Once processing has started, the payment can no longer be canceled or deleted.

**Parameters**

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
DarfPayment(
    amount=1280,
    competence=2021-03-01 02:59:59.999999,
    created=2021-02-20 14:39:15.565841,
    description=take my money,
    due=2021-05-12 02:59:59.999999,
    fee=0,
    fine_amount=12,
    id=5116552814788608,
    interest_amount=34,
    nominal_amount=1234,
    reference_number=2340978970,
    revenue_code=1240,
    scheduled=2021-03-012 15:00:00,
    status=canceled,
    tags=['darf', 'making money'],
    tax_id=12.345.678/0001-95,
    transaction_ids=[],
    updated=2021-02-20 14:39:15.565841
)
```

### Get a Darf Payment PDF

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

Get a Darf 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 Darf payment entity |

**Request**

```python
import starkbank

pdf = starkbank.darfpayment.pdf("5116552814788608")

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

### List Darf Payment Logs

`GET /v2/darf-payment/log`

Get a paged list of all Darf 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. |
| `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.darfpayment.log.query(
    payment_ids=["5116552814788608"]
)

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

**Response**

```python
Log(
    created=2021-02-20 14:39:15.565841,
    errors=[],
    id=5146850856271872,
    payment=DarfPayment(
        amount=1280,
        competence=2021-03-01 02:59:59.999999,
        created=2021-02-20 14:39:15.565841,
        description=take my money,
        due=2021-05-12 02:59:59.999999,
        fee=0,
        fine_amount=12,
        id=5116552814788608,
        interest_amount=34,
        nominal_amount=1234,
        reference_number=2340978970,
        revenue_code=1240,
        scheduled=2021-03-012 15:00:00,
        status=created,
        tags=['darf', 'making money'],
        tax_id=12.345.678/0001-95,
        transaction_ids=[],
        updated=2021-02-20 14:39:15.565841
    ),
    type=created
)
```

### Get a Darf Payment Log

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

Get a single Darf 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.darfpayment.log.get("5146850856271872")

print(log)
```

**Response**

```python
Log(
    created=2021-02-20 14:39:15.565841,
    errors=[],
    id=5146850856271872,
    payment=DarfPayment(
        amount=1280,
        competence=2021-03-01 02:59:59.999999,
        created=2021-02-20 14:39:15.565841,
        description=take my money,
        due=2021-05-12 02:59:59.999999,
        fee=0,
        fine_amount=12,
        id=5116552814788608,
        interest_amount=34,
        nominal_amount=1234,
        reference_number=2340978970,
        revenue_code=1240,
        scheduled=2021-03-012 15:00:00,
        status=created,
        tags=['darf', 'making money'],
        tax_id=12.345.678/0001-95,
        transaction_ids=[],
        updated=2021-02-20 14:39:15.565841
    ),
    type=created
)
```

## 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/darf-payment-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/darf-payment-node.md)
- [PHP](https://docs.starkbank.com/api/v2/darf-payment-php.md)
- [Java](https://docs.starkbank.com/api/v2/darf-payment-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/darf-payment-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/darf-payment-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/darf-payment-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/darf-payment-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/darf-payment-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/darf-payment-curl.md)