# Pix Invoice

The Invoice resource facilitates receiving Pix payments from your clients.

Alongside specifying the invoice amount, you can customize the due date, expiration date, fines, interest, discounts, and descriptions, enabling a comprehensive billing model.

You can also reverse paid invoices partially or fully.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

InvoiceGenerate a customized Invoice to receive Pix payments.

## 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:

invoice

2.1. Via Internet Banking: 

Integrations > Webhook > New Webhook

2.2. Via API: 

Use the POST /webhook route to create the webhook

## Invoice Overview

Invoice is a resource that can be used to receive Pix payments from your clients.

In addition to choosing the Invoice amount, you will be able to include due date, expiration date, fine, interest, discount, and description for a comprehensive billing model.

In this section, we will demonstrate how to create an Invoice via API to initiate charges for your customers. To create an Invoice request, it is necessary to provide mandatory information.

 NOTE:   To ensure that the payer's taxId matches the final user's registration in your system, there are two options.

You can reverse the Invoice if the taxIds do not match, or use the rules parameter in the creation of the Invoice to restrict who can pay this invoice.

### The Invoice Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the invoice. |
| `amount` | INTEGER | Amount in cents that was received. Example: 100 (R$1.00). |
| `brcode` | STRING | BR Code for the invoice Pix payment. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `descriptions` | LIST OF OBJECTS | List of description objects with key and value. |
| `discountAmount` | INTEGER | Discount amount in cents. |
| `discounts` | LIST OF OBJECTS | List of discount objects with percentage and due. |
| `due` | STRING | Payment due datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `expiration` | INTEGER | Time in seconds from due datetime until expiration. |
| `fee` | INTEGER | Fee charged in cents. |
| `fine` | FLOAT | Percentage charged if paid after due datetime. |
| `fineAmount` | INTEGER | Fine amount in cents. |
| `interest` | FLOAT | Monthly percentage charged if paid after due datetime. |
| `interestAmount` | INTEGER | Interest amount in cents. |
| `link` | STRING | Public URL to the invoice page. |
| `name` | STRING | Payer full name. |
| `nominalAmount` | INTEGER | Invoice amount in cents without fine or interest. |
| `pdf` | STRING | Public URL to the invoice PDF. |
| `rules` | LIST OF OBJECTS | List of rule objects with key and value. |
| `splits` | LIST OF OBJECTS | List of Split objects with receiverId and amount. |
| `status` | STRING | Current invoice status. Options: "created", "paid", "canceled", "overdue", "expired". |
| `tags` | LIST OF STRINGS | Tags associated with the invoice. |
| `taxId` | STRING | Payer CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the invoice. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### The Invoice Status

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

| Status | Description |
| --- | --- |
| Created | The Invoice was successfully created in Stark Bank. |
| Paid | The Invoice was paid by the payer. |
| Canceled | The Invoice was canceled by you or by the system. |
| Overdue | The Invoice has passed the due date and is now subject to fine and interest. |
| Expired | The Invoice has passed the expiration date and can no longer be paid. |

### The Invoice Logs

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

A paid Invoice can be either partially or fully reversed back to its payer. Multiple reversals can be made for the same invoice and each time, the following flow of logs will occur:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Invoice was successfully created in Stark Bank. |
| Paid | Paid | The Invoice was paid by the payer. |
| Credited | Paid | The Invoice payment was credited to your account. |
| Canceled | Canceled | The Invoice was canceled. |
| Overdue | Overdue | The Invoice has passed the due date. |
| Voided | Canceled | The Invoice was voided. |
| Reversed | Paid | The Invoice payment was partially or fully reversed to the payer. |
| Updated | Paid | The Invoice was updated after payment (e.g., amount reduction). |
| Expired | Expired | The Invoice has passed the expiration date and can no longer be paid. |

### Creating Invoices

In order to create the Invoice, certain mandatory parameters are required for the request to be made, such as amount, taxId, and name.

In addition to these mandatory points, there are optional fields to enhance your invoice, such as due, fine, interest, expiration, discounts, descriptions, tags, and rules. For more details, you can refer to the documentation in the Invoice section.

**Request**

```python
import starkbank
from datetime import datetime

invoices = starkbank.invoice.create([
    starkbank.Invoice(
        amount=400000,
        name="Arya Stark",
        tax_id="012.345.678-90",
    )
])

for invoice in invoices:
    print(invoice)
```

**Response**

```python
Invoice(
    amount=400000,
    brcode=00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79,
    created=2020-10-26 17:10:57.261868,
    descriptions=[],
    discount_amount=0,
    discounts=[],
    due=2021-05-12 15:23:26,
    expiration=5097600,
    fee=0,
    pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    fine=2.0,
    fine_amount=0,
    id=4600131349381120,
    interest=1.3,
    interest_amount=1.0,
    name=Arya Stark,
    nominal_amount=400000,
    status=created,
    tags=[],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877
)
```

### Creating Invoice with due, fine, interest, expiration parameters

Due: By adding this parameter, you can set the due date of the requested payment in ISO format.

Example: "2020-11-25T17:59:26.000000+00:00." Default value: 2 days after creation.

Fine: By adding this parameter, you can add a fine to the invoiced amount if the customer pays after the due date and time.

Interest: By adding this parameter, you can add monthly interest, in percentage, charged if the customer pays after the due date.

Expiration: By adding this parameter, you can add time in seconds counted from the due date until the invoice expiration.

After expiration, the invoice can no longer be paid.

Default value: 5097600 (59 days).

**Request**

```python
import starkbank
from datetime import datetime

invoices = starkbank.invoice.create([
    starkbank.Invoice(
        amount=400000,
        due=datetime(2021, 5, 12, 15, 23, 26, 689377),
        expiration=123456789,
        fine=2.5,
        interest=1.3,
        name="Arya Stark",
        tax_id="012.345.678-90"
    )
])

for invoice in invoices:
    print(invoice)
```

**Response**

```python
Invoice(
    amount=400000,
    brcode=00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79,
    created=2020-10-26 17:10:57.261868,
    descriptions=[],
    discount_amount=0,
    discounts=[{'percentage': 10.0, 'due': '2021-03-12T18:23:26+00:00'}],
    due=2021-05-12 15:23:26,
    expiration=123456789,
    fee=0,
    pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    fine=2.5,
    fine_amount=0,
    id=4600131349381120,
    interest=1.3,
    interest_amount=0,
    name=Arya Stark,
    nominal_amount=400000,
    status=created,
    tags=[],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877
)
```

### Creating Invoice with discounts, description, tags parameters

Discounts: With this parameter, you can set a list of up to 5 discounts specifying the discount percentage and the deadline until the discount is valid.

Tags: By adding this parameter, you can have an array of strings to mark the entity for future queries.

All tags will be converted to uppercase.

Descriptions: With this parameter, you will have a list of up to 15 descriptions containing information to help understand the reason for the charge.

For each description, you can add a title key and a description value.

**Request**

```python
import starkbank
from datetime import datetime

invoices = starkbank.invoice.create([
    starkbank.Invoice(
        amount=400000,
        descriptions=[{'key': 'Arya', 'value': 'Not today'}],
        discounts=[{'percentage': 10, 'due': datetime(2021, 3, 12, 15, 23, 26, 689377)}],
        name="Arya Stark",
        tags=['War supply', 'Invoice #1234'],
        tax_id="012.345.678-90"
    )
])

for invoice in invoices:
    print(invoice)
```

**Response**

```python
Invoice(
    amount=400000,
    brcode=00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79,
    created=2020-10-26 17:10:57.261868,
    descriptions=[{'key': 'Arya', 'value': 'Not today'}],
    discount_amount=0,
    discounts=[{'percentage': 10.0, 'due': '2021-03-12T18:23:26+00:00'}],
    due=2021-05-12 15:23:26,
    expiration=5097600,
    fee=0,
    pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    fine=2.0,
    fine_amount=0,
    id=4600131349381120,
    interest=1.0,
    interest_amount=0,
    name=Arya Stark,
    nominal_amount=400000,
    status=created,
    tags=['War supply', 'Invoice #1234'],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877
)
```

### Creating Invoice with rules parameter

Rules: you can set a list of rules to modify the invoice's behavior.

It is possible to limit the tax IDs allowed to pay this invoice by setting this parameter using the key "allowedTaxIds".

**Request**

```python
import starkbank
from datetime import datetime

invoices = starkbank.invoice.create([
    starkbank.Invoice(
        amount=400000,
        name="Arya Stark",
        tax_id="012.345.678-90",
        rules=[
            {
                'key': 'allowedTaxIds',
                'value': [
                    '012.345.678-90',
                    '45.059.493/0001-73'
                ]
            }
        ]
    )
])

for invoice in invoices:
    print(invoice)
```

**Response**

```python
Invoice(
    amount=400000,
    brcode=00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79,
    created=2020-10-26 17:10:57.261868,
    descriptions=[],
    discount_amount=0,
    discounts=[],
    due=2021-05-12 15:23:26,
    expiration=5097600,
    fee=0,
    pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    fine=2.0,
    fine_amount=0,
    id=4600131349381120,
    interest=1.0,
    interest_amount=0,
    name=Arya Stark,
    nominal_amount=400000,
    status=created,
    tags=[],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877
)
```

### Consulting Invoices

It is possible to retrieve an invoice by its ID or even list them using parameters such as limit, after, before to filter the results, as shown in the example below:

**Request**

```python
import starkbank

invoices = starkbank.invoice.query(
    after="2020-10-1",
    before="2020-10-30",
    limit=10
)

for invoice in invoices:
    print(invoice)
```

**Response**

```python
Invoice(
    amount=400000,
    brcode=00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79,
    created=2020-10-26 17:10:57.261868,
    descriptions=[{'key': 'Arya', 'value': 'Not today'}],
    discount_amount=0,
    discounts=[{'percentage': 10.0, 'due': '2021-03-12T18:23:26+00:00'}],
    due=2021-05-12 15:23:26,
    expiration=123456789,
    fee=0,
    pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    fine=2.5,
    fine_amount=0,
    id=4600131349381120,
    interest=1.3,
    interest_amount=0,
    name=Arya Stark,
    nominal_amount=400000,
    status=created,
    tags=['War supply', 'Invoice #1234'],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877
)
```

### Updating Invoices

Resource that will update certain parameters of your Invoice

To update an Invoice, it is necessary to provide the invoice ID. Additionally, other parameters such as amount, due, expiration, and status can be included in the update process.

If the Invoice has already been paid, it is possible to reduce only the amount, resulting in the corresponding refund. For example, if a R$ 100 invoice has been paid, you can set the amount parameter to R$ 5, and the remaining R$ 95 will be refunded to the payer.

This provides greater flexibility and control over the information associated with your financial transactions.

**Request**

```python
import starkbank

updated_invoice = starkbank.invoice.update(
    "4600131349381120", 
    amount=12345,
    expiration=98765
)

print(updated_invoice)
```

**Response**

```python
Invoice(
    amount=12345,
    brcode=00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79,
    created=2020-10-26 17:10:57.261868,
    descriptions=[{'key': 'Arya', 'value': 'Not today'}],
    discount_amount=0,
    discounts=[{'percentage': 10.0, 'due': '2021-03-12T18:23:26+00:00'}],
    due=2021-05-12 15:23:26,
    expiration=98765,
    fee=0,
    pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    fine=2.5,
    fine_amount=0,
    id=4600131349381120,
    interest=1.3,
    interest_amount=0,
    name=Arya Stark,
    nominal_amount=400000,
    status=created,
    tags=['War supply', 'Invoice #1234'],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877
)
```

### Canceling an Invoice

To cancel an Invoice, you need to update the invoice status to "canceled".

Only Invoices that have not yet been paid can be canceled.

**Request**

```python
import starkbank

canceled_invoice = starkbank.invoice.update(
    "4600131349381120",
    status="canceled"
)

print(canceled_invoice)
```

**Response**

```python
Invoice(
    amount=400000,
    brcode=00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79,
    created=2020-10-26 17:10:57.261868,
    descriptions=[{'key': 'Arya', 'value': 'Not today'}],
    discount_amount=0,
    discounts=[{'percentage': 10.0, 'due': '2021-03-12T18:23:26+00:00'}],
    due=2021-05-12 15:23:26,
    expiration=123456789,
    fee=0,
    pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    fine=2.5,
    fine_amount=0,
    id=4600131349381120,
    interest=1.3,
    interest_amount=0,
    name=Arya Stark,
    nominal_amount=400000,
    status=canceled,
    tags=['War supply', 'Invoice #1234'],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877
)
```

### Reversing Partially an Invoice

To partially reverse a paid Invoice, you need to PATCH the invoice amount to a lower value. The difference between the paid amount and the new amount will be reversed to the payer.

For example, if an Invoice was paid with an amount of 400000 (R$ 4,000.00) and you patch the amount to 3000 (R$ 30.00), it means you reversed 397000 (R$ 3,970.00) back to the payer.

While the reversal is being processed, the invoice status remains paid.

**Request**

```python
import starkbank

updated_invoice = starkbank.invoice.update(
    "4600131349381120",
    amount=3000
)

print(updated_invoice)
```

**Response**

```python
Invoice(
    amount=3000,
    brcode=00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79,
    created=2020-10-26 17:10:57.261868,
    descriptions=[{'key': 'Arya', 'value': 'Not today'}],
    discount_amount=0,
    discounts=[{'percentage': 10.0, 'due': '2021-03-12T18:23:26+00:00'}],
    due=2021-05-12 15:23:26,
    expiration=123456789,
    fee=0,
    pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    fine=2.5,
    fine_amount=0,
    id=4600131349381120,
    interest=1.3,
    interest_amount=0,
    name=Arya Stark,
    nominal_amount=400000,
    status=paid,
    tags=['War supply', 'Invoice #1234'],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877
)
```

### Reversing Fully an Invoice

To fully reverse a paid Invoice, you need to PATCH the invoice amount to 0. This will reverse the entire paid amount back to the payer.

For example, if an Invoice was paid with an amount of 400000 (R$ 4,000.00) and you patch the amount to 0, the full 400000 (R$ 4,000.00) will be reversed to the payer.

After the full reversal is completed, the invoice status remains paid.

**Request**

```python
import starkbank

updated_invoice = starkbank.invoice.update(
    "4600131349381120",
    amount=0
)

print(updated_invoice)
```

**Response**

```python
Invoice(
    amount=0,
    brcode=00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79,
    created=2020-10-26 17:10:57.261868,
    descriptions=[{'key': 'Arya', 'value': 'Not today'}],
    discount_amount=0,
    discounts=[{'percentage': 10.0, 'due': '2021-03-12T18:23:26+00:00'}],
    due=2021-05-12 15:23:26,
    expiration=123456789,
    fee=0,
    pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    fine=2.5,
    fine_amount=0,
    id=4600131349381120,
    interest=1.3,
    interest_amount=0,
    name=Arya Stark,
    nominal_amount=400000,
    status=paid,
    tags=['War supply', 'Invoice #1234'],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877
)
```

### Receiving Invoice Webhook

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

Every time we change an Invoice, we create a Log. Logs are pretty useful for understanding the life cycle of each Invoice. 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: An invoice subscription is required to receive this event.

---

## Other Languages

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