# Pix Invoice

The Invoice resource is used to request payments from customers.

Your customer can pay it by scanning the Pix QR Code or making a deposit to the indicated account number.

You can set custom fields as fine, interest, overdue date and expiration date, for a complete charge method, much better than boleto.

If you're used to our [Boleto resource](https://docs.starkbank.com/api/v2/boleto.md), you will feel pretty familiar with the Invoice flow. In this section, we will teach you how to create and manage your Pix invoices.

You can also split the Invoice between different receivers, you need to create a [Split Receiver](https://docs.starkbank.com/api/v2/split-receiver.md), and add the receiver into the Splits array.

### The Invoice object

**Attributes**

| 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". |

### Create Invoices

`POST /v2/invoice`

Use this route to create up to 100 new invoices at a time.

**NOTE:**If you create an invoice with amount zero, we will accept any amount paid by your customer. Otherwise we will only accept the amount specified in the invoice.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | A non-negative integer that represents the amount in cents to be invoiced. When the invoice is paid, this parameter is updated with the amount actually paid. Example: 100 (R$1.00) |
| `name` | REQUIRED | Payer full name. Example: "Anthony Edward Stark" |
| `taxId` | REQUIRED | Payer CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90 |
| `descriptions` | OPTIONAL | List of up to 15 descriptions containing information to help the customer understand why he is being charged. For each description, you can add a title key and a description value. Example: ``` [{"key": "Product A", "value": "R$10,00"}, {"key": "Taxes", "value": "R$100,00"}] ``` |
| `discounts` | OPTIONAL | List of up to 5 discounts specifying the discount percentage and the limit date up to when the discount is valid. Example: ``` [{"percentage": 5, "due": "2020-11-25T17:59:26.000000+00:00"}, {"percentage": 10.5, "due": "2020-10-25T17:59:26.000000+00:00"}] ``` |
| `due` | OPTIONAL | Requested payment due datetime in ISO format. Example: "2020-11-25T17:59:26.000000+00:00". Default value: 2 days after creation. |
| `expiration` | OPTIONAL | Time in seconds counted from the due datetime until the invoice expires. After expiration, the invoice cannot be paid anymore. Default value: 5097600 (59 days) |
| `fine` | OPTIONAL | Percentage of the invoice amount charged if customer pays after the due datetime. Default value = 2.00 (2%) |
| `interest` | OPTIONAL | Monthly interest, in percentage, charged if customer pays after the due datetime. Default value = 1.00 (1%) |
| `rules` | OPTIONAL | List of rules for modifying invoice behavior. Example: ``` [{"key": "allowedTaxIds", "value": ["012.345.678-90", "45.059.493/0001-73"]}] ``` |
| `splits` | OPTIONAL | Array of Split objects to indicate payment receivers. Example: ``` [{"receiverId": "5742447426535424", "amount": 100}, {"receiverId": "5743243941642240", "amount": 200}] ``` |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**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)}],
        due=datetime(2021, 5, 12, 15, 23, 26, 689377),
        expiration=123456789,
        fine=2.5,
        interest=1.3,
        name="Arya Stark",
        tags=['War supply', 'Invoice #1234'],
        tax_id="012.345.678-90",
        rules=[
            {
                'key': 'allowedTaxIds',
                'value': [
                    '012.345.678-90',
                    '45.059.493/0001-73'
                ]
            }
        ],
        splits=[
            Split(amount=3000, receiverId="5742447426535424"), Split(amount=5000, receiverId="5743243941642240")
        ]
    )
])

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,
    splits=[
        Split(
            amount=3000,
            created=None,
            external_id=None,
            id=None,
            receiver_id=5742447426535424,
            scheduled=None,
            source=None,
            status=None,
            tags=None,
            updated=None
        ),
        Split(
            amount=5000,
            created=None,
            external_id=None,
            id=None,
            receiver_id=5743243941642240,
            scheduled=None,
            source=None,
            status=None,
            tags=None,
            updated=None
        )
    ]
)
```

### List Invoices

`GET /v2/invoice`

Get a list of invoices 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 invoices by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `transactionIds` | OPTIONAL | List of transaction IDs linked to the desired invoices. |

**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
)
```

### Get an Invoice

`GET /v2/invoice/:id`

Get a single invoice by its id.

**Parameters**

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

**Request**

```python
import starkbank

invoice = starkbank.invoice.get("4600131349381120")

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
)
```

### Update an Invoice

`PATCH /v2/invoice/:id`

Update a single invoice. If the invoice has not yet been paid, you can adjust parameters such as the requested amount, the due datetime and the expiration. If the invoice has already been paid, only the amount can be decreased, which will result in a payment reversal.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the invoice entity. |
| `amount` | OPTIONAL | New amount that should be charged on payment. If the invoice has already been paid, it is the final amount after reversal. Example: 200 (R$2.00). |
| `due` | OPTIONAL | New due datetime. Example: '2020-11-26T17:59:26.000000+00:00'. |
| `expiration` | OPTIONAL | New expiration. Example: 3600 (1 hour). |
| `status` | OPTIONAL | This can be used to cancel the invoice by passing 'canceled' as the status patch. |

**Request**

```python
import starkbank

updated_invoice = starkbank.invoice.update(
    "4600131349381120", 
    status="canceled", 
    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=canceled,
    tags=['War supply', 'Invoice #1234'],
    transaction_ids=[],
    tax_id=012.345.678-90,
    updated=2020-10-26 17:10:57.261877
)
```

### Get an Invoice QR Code

`GET /v2/invoice/:id/qrcode`

Get the invoice QR Code png file. Similarly to the Boleto PDF, we create a QR Code image file with the invoice data so that your customer can pay it through Pix.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the invoice entity. |
| `size` | OPTIONAL | Number of pixels in each 'box' of the QR code. Minimum = 1 and maximum = 50. Default value = 7. |

**Request**

```python
import starkbank

qrcode = starkbank.invoice.qrcode("4600131349381120", size=15)

with open("qrcode.png", "wb") as file:
    file.write(qrcode)
```

### Get an Invoice PDF

`GET /v2/invoice/:id/pdf`

Get the invoice PDF file. Similarly to the Boleto PDF, we create a PDF file with the invoice data and the QR Code so that your customer can pay it through Pix. The same PDF can also be accessed by the public "pdf" parameter returned in the Invoice JSON. This link is the one you should send to your customers.

**Parameters**

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

**Request**

```python
import starkbank

pdf = starkbank.invoice.pdf("4600131349381120")

with open("invoice.pdf", "wb") as file:
    file.write(pdf)
```

### List Invoice Logs

`GET /v2/invoice/log`

Get a paged list of invoice logs. A log tracks a change in the invoice 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. |
| `invoiceIds` | OPTIONAL | Array of invoice ids that are linked to the logs you desire. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.invoice.log.query(
    after="2020-10-01",
    before="2020-10-30"
)

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

**Response**

```python
Log(
    created=2020-10-27 00:30:12.141283,
    errors=[],
    id=6742710681600000,
    type=credited,
    invoice=Invoice(
        amount=120000,
        brcode=00020101021226860014br.gov.bcb.pix2564invoice-h.sandbox.starkbank.com/7e0b4b71ec924f48865a4a3d979565f65204000053039865802BR5915Stark Bank S.A.6009Sao Paulo62070503***6304365D,
        created=2020-10-27 00:24:56.372300,
        descriptions=[{'value': 'Not today', 'key': 'Arya'}],
        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=5616810774757376,
        interest=1.3,
        interest_amount=0,
        name=Arya Stark,
        nominal_amount=120000,
        status=paid,
        tags=['new sword', 'invoice #1234'],
        transaction-ids=[],
        tax_id=012.345.678-90,
        updated=2020-10-27 00:30:12.362815
    )
)
```

### Get an Invoice Log

`GET /v2/invoice/log/:id`

Get a single invoice 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.invoice.log.get("6742710681600000")

print(log)
```

**Response**

```python
Log(
    created=2020-10-27 00:30:12.141283,
    errors=[],
    id=6742710681600000,
    type=credited,
    invoice=Invoice(
        amount=120000,
        brcode=00020101021226860014br.gov.bcb.pix2564invoice-h.sandbox.starkbank.com/7e0b4b71ec924f48865a4a3d979565f65204000053039865802BR5915Stark Bank S.A.6009Sao Paulo62070503***6304365D,
        created=2020-10-27 00:24:56.372300,
        descriptions=[{'value': 'Not today', 'key': 'Arya'}],
        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=5616810774757376,
        interest=1.3,
        interest_amount=0,
        name=Arya Stark,
        nominal_amount=120000,
        status=paid,
        tags=['new sword', 'invoice #1234'],
        transaction-ids=[],
        tax_id=012.345.678-90,
        updated=2020-10-27 00:30:12.362815
    )
)
```

### Get a reversed Invoice Log PDF

`GET /v2/invoice/log/:id/pdf`

Whenever an Invoice is successfully reversed, a reversed log will be created. To retrieve a specific reversal receipt, you can request the corresponding log PDF.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log invoice entity. |

**Request**

```python
import starkbank

pdf = starkbank.invoice.log.pdf("6742710681600000")

with open("invoice-reversal.pdf", "wb") as file:
    file.write(pdf)
```

### Get an Invoice Payment information

`GET /v2/invoice/:id/payment`

Once an invoice has been paid, you can get the payment information using the Invoice. Payment sub-resource.

**Parameters**

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

**Request**

```python
import starkbank

payment = starkbank.invoice.payment("5049137766596608")

print(payment)
```

**Response**

```python
Payment(
    account_number=3352164669759737,
    account_type=checking,
    amount=566223,
    bank_code=35480428,
    branch_code=7533,
    end_to_end_id=E01709266202302150600xG8OcRCaojI,
    method=pix,
    name=Cesar Eireli,
    tax_id=54.866.319/0001-23
)
```

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