# Utility Payment

We provide the convenience of paying utility bills directly from your Stark Bank balance.

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

Utility Payments allow you to pay services such as electricity, water, gas, and other utility bills.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

Utility PaymentPay utility bills 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:

utility-payment

2.1. Via Internet Banking: 

Integrations > Webhook > New Webhook

2.2. Via API: 

Use the POST /webhook route to create the webhook

## Utility Payment Overview

Utility Payment is a resource that can be used to pay utility bills such as electricity, water, gas and other services.

To create a Utility Payment, you need to provide either the line or the barCode of the bill, along with a description.

Optional parameters include scheduled and tags.

### The Utility Payment Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the utility payment. |
| `amount` | INTEGER | Amount in cents to be paid. Example: 1234 (R$12.34). |
| `barCode` | STRING | Bar code number of the utility bill. |
| `created` | STRING | Creation datetime. Example: "2020-02-06T16:22:24.664148+00:00". |
| `description` | STRING | Custom description for the utility payment. |
| `fee` | INTEGER | Fee charged in cents. |
| `line` | STRING | Digitable line of the utility bill. |
| `scheduled` | STRING | Scheduled date for the utility payment. Example: "2020-08-14" or "2020-08-14T15:23:26+00:00". |
| `status` | STRING | Current utility payment status. Options: "created", "processing", "success", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the utility payment. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the utility payment. |
| `type` | STRING | Payment type. Example: "utility". |
| `updated` | STRING | Last update datetime. Example: "2020-02-06T16:22:24.664148+00:00". |

### The Utility Payment Status

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

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

### The Utility Payment Logs

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

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Utility Payment was successfully created in Stark Bank. |
| Processing | Processing | The Utility Payment is being sent to the banking network. |
| Success | Success | The Utility Payment was successfully completed. |
| Failed | Failed | The Utility Payment was unsuccessful. |
| Canceled | Canceled | The Utility Payment was canceled before processing. |

### Creating Utility Payments

To create a Utility Payment, provide either the line or the barCode of the utility bill, along with a description.

The payment will be processed as soon as possible unless a scheduled date is provided.

**Request**

```python
import starkbank

payments = starkbank.utilitypayment.create([
    starkbank.UtilityPayment(
        line="83640000001 1 08740138007 0 61053026111 0 08067159411 9",
        description="Electricity for the Long Night"
    )
])

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

**Response**

```python
UtilityPayment(
    amount=14390,
    bar_code=83640000001087401380076105302611108067159411,
    created=2020-02-06 16:22:24.664134,
    description=Electricity for the Long Night,
    fee=0,
    id=5412038532661248,
    line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
    scheduled=2020-02-07 10:00:00,
    status=created,
    tags=[],
    transaction_ids=[],
    type=utility,
    updated=2020-02-06 16:22:24.664148
)
```

### Creating Utility Payments with scheduled, tags parameters

Scheduled: Schedule the utility payment for a specific date.

Today is the default.

Example: "2020-08-14T15:23:26+00:00" or "2020-08-14"

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

**Request**

```python
import starkbank

payments = starkbank.utilitypayment.create([
    starkbank.UtilityPayment(
        line="83640000001 1 08740138007 0 61053026111 0 08067159411 9",
        description="Electricity for the Long Night",
        scheduled="2020-08-14",
        tags=["electricity", "invoice/1234"]
    )
])

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

**Response**

```python
UtilityPayment(
    amount=14390,
    bar_code=83640000001087401380076105302611108067159411,
    created=2020-02-06 16:22:24.664134,
    description=Electricity for the Long Night,
    fee=0,
    id=5412038532661248,
    line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
    scheduled=2020-08-14 10:00:00,
    status=created,
    tags=['electricity', 'invoice/1234'],
    transaction_ids=[],
    type=utility,
    updated=2020-02-06 16:22:24.664148
)
```

### Listing Utility Payments

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

**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=14390,
    bar_code=83640000001087401380076105302611108067159411,
    created=2020-04-24 17:49:10.225810,
    description=Electricity for the Long Night,
    fee=200,
    id=5950134772826112,
    line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
    scheduled=2020-08-14 10:00:00,
    status=processing,
    tags=['electricity', 'invoice/1234'],
    transaction_ids=['5991715760504832'],
    type=utility,
    updated=2020-04-24 17:49:10.225810
)
```

### Getting a Utility Payment

Get a single Utility Payment by its id.

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
UtilityPayment(
    amount=14390,
    bar_code=83640000001087401380076105302611108067159411,
    created=2020-04-24 17:49:10.225810,
    description=Electricity for the Long Night,
    fee=200,
    id=5950134772826112,
    line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
    scheduled=2020-08-14 10:00:00,
    status=processing,
    tags=['electricity', 'invoice/1234'],
    transaction_ids=['5991715760504832'],
    type=utility,
    updated=2020-04-24 17:49:10.225810
)
```

### Canceling Utility Payment

This method will allow the cancellation of a utility payment.

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
UtilityPayment(
    amount=14390,
    bar_code=83640000001087401380076105302611108067159411,
    created=2020-04-24 17:49:10.225810,
    description=Electricity for the Long Night,
    fee=0,
    id=6693962735681536,
    line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
    scheduled=2020-08-14 10:00:00,
    status=canceled,
    tags=['electricity', 'invoice/1234'],
    transaction_ids=[],
    type=utility,
    updated=2020-04-24 17:49:10.225810
)
```

### Receiving Utility Payment Webhook

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

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

---

## Other Languages

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