# Utility Payment

Here we will teach you how to create and manage utility payments, such as electricity and water bills.

### The Utility Payment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the utility 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 utility payment. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the payment. |
| `type` | STRING | Type of the utility payment. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Utility Payments

`POST /v2/utility-payment`

Use this route to pay utility bills 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. |
| `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.utilitypayment.create([
    starkbank.UtilityPayment(
        line="83640000001 1 08740138007 0 61053026111 0 08067159411 9",
        tags=["Energy", "Winterfell"],
        description="Electricity for the Long Night",
        scheduled="2020-04-25"
    )
])

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

**Response**

```python
UtilityPayment(
    amount=10874,
    bar_code=83640000001087401380076105302611108067159411,
    created=2020-04-24 18:03:18.662638,
    description=Electricity for the Long Night,
    fee=0,
    id=5949004768608256,
    line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
    scheduled=2020-04-25 15:00:00,
    status=created,
    tags=['energy', 'winterfell'],
    transaction_ids=[],
    type=utility,
    updated=2020-04-24 18:03:18.662638,
)
```

### List Utility Payments

`GET /v2/utility-payment`

Get a list of non-deleted utility 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 utility payments by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

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

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

**Response**

```python
UtilityPayment(
    amount=10874,
    bar_code=83640000001087401380076105302611108067159411,
    created=2020-04-24 18:03:18.662638,
    description=Electricity for the Long Night,
    fee=0,
    id=5949004768608256,
    line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
    scheduled=2020-04-25 15:00:00,
    status=created,
    tags=['energy', 'winterfell'],
    transaction_ids=[],
    type=utility,
    updated=2020-04-24 18:03:18.662638,
)
```

### Get a Utility Payment

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

Get a single utility payment by its id.

**Parameters**

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

**Request**

```python
import starkbank

payment = starkbank.utilitypayment.get("5949004768608256")

print(payment)
```

**Response**

```python
UtilityPayment(
  amount=10874,
  bar_code=83640000001087401380076105302611108067159411,
  created=2020-04-24 18:03:18.662638,
  description=Electricity for the Long Night,
  fee=0,
  id=5949004768608256,
  line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
  scheduled=2020-04-25 15:00:00,
  status=created,
  tags=['energy', 'winterfell'],
  transaction_ids=[],
  type=utility,
  updated=2020-04-24 18:03:18.662638,
)
```

### Delete a Utility Payment

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

Cancel a scheduled utility payment. You can only cancel utility 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 utility payment entity. |

**Request**

```python
import starkbank

payment = starkbank.utilitypayment.delete("5949004768608256")

print(payment)
```

**Response**

```python
UtilityPayment(
  amount=10874,
  bar_code=83640000001087401380076105302611108067159411,
  created=2020-04-24 18:03:18.662638,
  description=Electricity for the Long Night,
  fee=0,
  id=5949004768608256,
  line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
  scheduled=2020-04-25 15:00:00,
  status=canceled,
  tags=['energy', 'winterfell'],
  transaction_ids=[],
  type=utility,
  updated=2020-04-24 18:03:18.662638,
)
```

### Get a Utility Payment PDF

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

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

**Request**

```python
import starkbank

pdf = starkbank.utilitypayment.pdf("5949004768608256")

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

### List Utility Payment Logs

`GET /v2/utility-payment/log`

Get a paged list of all utility 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.utilitypayment.log.query(
    payment_ids=["5949004768608256"]
)

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

**Response**

```python
Log(
    id=5369811349536768,
    created=2020-04-24 18:03:18.733424,
    errors=[],
    type=created,
    payment=UtilityPayment(
        amount=10874,
        bar_code=83640000001087401380076105302611108067159411,
        created=2020-04-24 18:03:18.662638,
        description=Electricity for the Long Night,
        fee=0,
        id=5949004768608256,
        line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
        scheduled=2020-04-25 15:00:00,
        status=created,
        tags=['energy', 'winterfell'],
        transaction_ids=[],
        type=utility,
        updated=2020-04-24 18:03:18.662638,
    )
)
```

### Get a Utility Payment Log

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

Get a single utility 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.utilitypayment.log.get("5369811349536768")

print(log)
```

**Response**

```python
  Log(
    id=5369811349536768,
    created=2020-04-24 18:03:18.733424,
    errors=[],
    type=created,
    payment=UtilityPayment(
        amount=10874,
        bar_code=83640000001087401380076105302611108067159411,
        created=2020-04-24 18:03:18.662638,
        description=Electricity for the Long Night,
        fee=0,
        id=5949004768608256,
        line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
        scheduled=2020-04-25 15:00:00,
        status=created,
        tags=['energy', 'winterfell'],
        transaction_ids=[],
        type=utility,
        updated=2020-04-24 18:03:18.662638,
    )
)
```

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