# API Reference

This is our second API version. It is another small step towards launching the product we want to create for you, but it's a giant leap for the brazilian financial market. We created the first banking API in Brazil and we are proud of it.

Our API is RESTFul. This means we use predictable, resource-oriented URLs to do banking operations. The API itself speaks exclusively in JSON, including errors, but our SDK libraries convert responses to appropriate language-specific objects.

Want to check our OpenAPI 3.1 specification? You can download our yaml file right here.

You can also try our Postman collection. Download it here.

**Production URL:** `https://api.starkbank.com`

**Sandbox URL:** `https://sandbox.api.starkbank.com`

**Install (Python)**

```python
pip install starkbank
```

**SDK Repository:** https://github.com/starkbank/sdk-python

## Tech Support

If you have any questions about our API or SDKs, feel free to email us. We will respond to you quickly, pinky promise.

We are here to help you integrate with us ASAP. We also love feedback, so don't be shy about sharing your thoughts with us.

**CONTACT US**

help@starkbank.com

## Testing in Sandbox

In order to send any request to Stark Bank, you first need to create a digital account with us. We call our accounts workspaces. Feel free to test our services in Sandbox by creating your workspace here (no need to contact us):

Create a Workspace in Sandbox

Your initial balance is zero. You can add balance by creating Boletos, as 90% of the created Boletos in the Sandbox environment will be paid automatically within one hour. So, just create a few boletos and wait around a bit to load your balance.

**BASE URL - Sandbox**

https://sandbox.api.starkbank.com

## Moving to Production

Sandbox and Production share the same code but are isolated from each other as they are running in separate servers and access different databases. Switching to Production requires you to change the base url and the credentials only. The SDKs select the base url according to the environment you choose.

Note 1: Since we will be talking about real money here, we strongly recommend integrating in Sandbox first.

Note 2: The response times are different in each environment as we emulate the results in Sandbox, while in Production we depend on other financial institutions to operate. For example, if you create a new boleto in Sandbox, we will process its payment and credit within one hour, while in Production the credit will only be available in D+1 after the payment.

You can request an account in Production here:

Create a Workspace in Production

**BASE URL - Production**

https://api.starkbank.com

## Versioning

We avoid breaking changes at all costs and we won't let your application stop working because of a change we made. We are always adding features and making improvements to our API, but whenever we make a significant change to an endpoint, we will launch a new API version. Also, whenever the API is upgraded, we will add a new log to our changelog

We consider the following changes to be backward-compatible:

Adding new API resources;
Adding new optional request parameters;
Making a mandatory request parameter optional;
Adding new properties to existing API responses;
Changing the order of properties in existing API responses;
Adding new events to webhooks (that means your webhook listener should gracefully handle unfamiliar event types).

**Current API Version**

v2

## Authentication

## Static IP list

To ensure the integrity and safety of our requests to your services, we recommend adding our static IP addresses to your firewall ingress rules. The following IP addresses are currently being used:

**Production**

- 35.199.76.124 
  - 34.85.188.162

**Sandbox**

- 35.247.226.240 
  - 35.245.182.229

## Errors

We like standards. Unfortunately, not all of our possible errors could fit in the HTTP status standard. Since we believe numbers are not descriptive enough, we prefer to use strings as error codes. In order to be compatible with request libraries, though, we use the HTTP status in the summary shown to the right.

**HTTP STATUS CODE SUMMARY**

| Status | Description |
| --- | --- |
| 200 | Everything went right |
| 400 | Your input is incorrect. We will send you a json explaining what went wrong. |
| 500 | Something went wrong on our side. Our engineering team will be notified and act to fix the problem ASAP. |
| 418 | Geek test. Discover the easter egg. |

**ERROR SAMPLE**

{
    "errors": [
        {
            "code": "invalidEmail",
            "message": "Your email address should look like “person@domain.com”."
        },
        {
            "code": "invalidName",
            "message": "Your name must have at least 6 characters."
        }
    ]
}

## Supported Languages

Our API returns messages in two different languages: US English (default language) and Brazilian Portuguese. To select one of them, just add the optional header key Accept-Language to your request with "en-US" or "pt-BR" as value. If you use anything else, messages will be returned in English.

**Accept-Language Header**

| Code | Language |
| --- | --- |
| en-US | US English (default) |
| pt-BR | Brazilian Portuguese |

## Pagination

We use query cursors to do pagination. They allow you to retrieve query results in manageable batches, and are recommended over using integer offsets for pagination.

Therefore, we return a cursor string in the GET results. You must send the cursor back in the following query string in order to get the results from the next page. The cursor will be null if there are no more results to be retrieved.

To the right you will find a pseudo-code showing how to handle cursors in our API.

Note: All paged lists have at most 100 objects. Above that, you should use query cursors to get more elements. Our SDKs will handle this for you, though, so you don't have to worry about cursors and batches when using them.

**Example: Handling cursors**

path = "https://sandbox.api.starkbank.com/v2/transfer"

response = requests.get(path)
transferList = response["transfers"]
cursor = response["cursor"]

print(cursor)  # CkYKFAoHY3JlYXRlZBIJCMWGnoWVoukCEipqE2l-YXBpLW1zLWNoYXJnZS1zYnhyEwsSBkNoYXJnZRiAgICC28rtCAwYACAB

nextResponse = request.get(path + "?cursor=" + cursor)
transferList += nextResponse["transfers"]
nextCursor = nextResponse["cursor"]

...

## Date & Time

All dates returned by our API will be in UTC ISO format. That means no matter where you are, you will always receive UTC times and should handle conversions to local time on your end whenever needed.

**Example**

2018-12-29T18:27:12.343531+00:00

# Business Account

## Workspace

Workspaces are bank accounts. They have independent balances, statements, operations and permissions. The only property that is shared between your workspaces is the link they have to your organization, which carries your basic information, such as tax ID, name, etc...

The main reason for automating the creation of multiple Workspaces is to use our infrastructure to divide your own customers into different buckets, setting them up with isolated balances and statements.

### The Workspace object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the workspace. |
| `allowedTaxIds` | LIST OF STRINGS | Tax IDs allowed to send Deposits to this workspace. If empty, all are allowed. |
| `created` | STRING | Creation datetime of the workspace. Example: "2020-04-23T23:00:00.000000+00:00". |
| `name` | STRING | Display name of the workspace shown in the Web Banking interface. |
| `organizationId` | STRING | ID of the organization that owns this workspace. |
| `pictureUrl` | STRING | URL of the workspace profile picture. |
| `status` | STRING | Current workspace status. Options: "active", "blocked". |
| `username` | STRING | Unique URL-safe identifier for the workspace. This is part of the Workspace Web Banking URL. |

### Create a Workspace

`POST /v2/workspace`

Here you can create a brand new Workspace.

Note: Only Organization credentials are able to create Workspaces.

**Request**

```python
import starkbank

workspace = starkbank.workspace.create(
    username="iron-bank-123",
    name="Iron Bank #123"
)

print(workspace)
```

**Response**

```python
  Workspace(
    id=6225875037061120,
    username=iron-bank-123,
    name=Iron Bank #123,
    allowed_tax_ids=[],
    status=active,
    organization_id=5656565656565656,
    picture_url=https://storage.googleapis.com/api-ms-workspace-sbx.appspot.com/pictures/workspace/6341320293482496.png?20230314201348,
    created=2020-04-23 23:00:00.000000
)
```

### List Workspaces

`GET /v2/workspace`

Get a list of Workspaces your credentials have access to in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

workspaces = starkbank.workspace.query()

for workspace in workspaces:
    print(workspace)
```

**Response**

```python
Workspace(
    id=6225875037061120,
    username=iron-bank-123,
    name=Iron Bank #123,
    allowed_tax_ids=[],
    status=active,
    organization_id=5656565656565656
    picture_url=https://storage.googleapis.com/api-ms-workspace-sbx.appspot.com/pictures/workspace/6341320293482496.png?20230314201348,
    created=2020-04-23 23:00:00.000000,
)
```

### Get a Workspace

`GET /v2/workspace/:id`

Get a single workspace by its id.

**Request**

```python
import starkbank

workspace = starkbank.workspace.get("6225875037061120")

print(workspace)
```

**Response**

```python
Workspace(
    id=6225875037061120,
    username=iron-bank-123,
    name=Iron Bank #123,
    allowed_tax_ids=[],
    status=active,
    organization_id=5656565656565656
    picture_url=https://storage.googleapis.com/api-ms-workspace-sbx.appspot.com/pictures/workspace/6341320293482496.png?20230314201348,
    created=2020-04-23 23:00:00.000000
)
```

### Update a Workspace

`PATCH /v2/workspace/:id`

Update a workspace by passing its id and the fields you want to update.

**Request**

```python
import starkbank

picture = open("path/to/picture.png", "rb").read()

workspace = starkbank.workspace.update(
    "6225875037061120",
    username="new-username",
    name="New Name",
    allowed_tax_ids=["012.345.678-90"],
    picture=picture,
    picture_type="image/png",
    status="blocked",
)

print(workspace)
```

**Response**

```python
Workspace(
    id=6225875037061120,
    username=new-username,
    name=New Name,
    allowed_tax_ids=['012.345.678-90'],
    status=blocked,
    organization_id=5656565656565656,
    picture_url=https://storage.googleapis.com/api-ms-workspace-sbx.appspot.com/pictures/workspace/6341320293482496.png?20230314201348,
    created=2020-04-23 23:00:00.000000
)
```

## Balance

The balance entity holds the total funds available in your workspace and can be calculated as the sum of its transactions (cash-in + cash-out).

Therefore, you can also interpret Transactions as balance change logs.

### The Balance object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the balance. |
| `amount` | INTEGER | Current balance amount in cents of reais. |
| `currency` | STRING | Currency code of the balance. Example: "BRL". |
| `updated` | STRING | Last update datetime of the balance. Example: "2020-04-23T23:00:00.000000+00:00". |

### Get the Balance

`GET /v2/balance`

Get the current balance in your workspace.

**Request**

```python
import starkbank

balance = starkbank.balance.get()

print(balance)
```

**Response**

```python
Balance(
    amount=5419070393,
    currency=BRL,
    id=5083989094170624,
    updated=2020-04-24 17:44:48.912604
)
```

## Transaction

Since Stark Bank is centralized, we have a private ledger to keep track of all transactions. It's important to understand that every financial operation in Stark Bank generates a transaction that is registered in our ledger.

You may directly generate a Transaction when you transfer money between workspaces in Stark Bank. Other times, we generate the Transaction for you, when you make a Transfer, pay a Boleto or receive money from a paid Boleto, for example.

### The Transaction object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the transaction. |
| `amount` | INTEGER | Transaction amount in cents of reais. Negative values represent cash-out. |
| `balance` | INTEGER | Balance in cents of reais after the transaction was processed. |
| `created` | STRING | Creation datetime of the transaction. Example: "2020-04-23T23:00:00.000000+00:00". |
| `description` | STRING | Description of the transaction. |
| `externalId` | STRING | Unique external identifier for the transaction. |
| `fee` | INTEGER | Fee charged by the transaction in cents of reais. |
| `receiverId` | STRING | ID of the workspace that received the amount. |
| `senderId` | STRING | ID of the workspace that sent the amount. |
| `source` | STRING | Reference to the operation that generated this transaction. Example: transfer/1234567890 |
| `tags` | LIST OF STRINGS | Tags associated with the transaction. |

### List Transactions

`GET /v2/transaction`

Your bank statement is the list of all transactions registered in your private ledger.

We return it paged.

**Request**

```python
import starkbank

transactions = starkbank.transaction.query(
    after="2020-04-01",
    before="2020-04-30"
)

for transaction in transactions:
    print(transaction)
```

**Response**

```python
Transaction(
    amount=-10000,
    created=2020-04-24 17:44:49.066074,
    description=A Lannister always pays his debts,
    external_id=my_unique_id,
    fee=0,
    id=5185595898855424,
    receiver_id=5651751147405312,
    sender_id=5083989094170624,
    source=self,
    balance=1567891,
    tags=['lannister', 'debts']
)
```

### Get a Transaction

`GET /v2/transaction/:id`

Get a single transaction by its id.

**Request**

```python
import starkbank

transaction = starkbank.transaction.get("5185595898855424")

print(transaction)
```

**Response**

```python
Transaction(
    amount=-10000,
    created=2020-04-24 17:44:49.066074,
    description=A Lannister always pays his debts,
    external_id=my_unique_id,
    fee=0,
    id=5185595898855424,
    receiver_id=5651751147405312,
    sender_id=5083989094170624,
    source=self,
    balance=1567891,
    tags=['lannister', 'debts']
)
```

# Cash Receivables

## 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, 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, 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.

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

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

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

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

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

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

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

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

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

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

## Dynamic Brcode

Note:This is a basic Pix QR Code solution for one time payment. For a complete Pix QR Code receivable, check the Invoice resource.

When a Dynamic Brcode is paid, a Deposit is created with the tags parameter containing the string "dynamic-brcode/" followed by the Dynamic Brcode's uuid "dynamic-brcode/{uuid}" for conciliation.

### The Dynamic Brcode object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the dynamic brcode. |
| `amount` | INTEGER | Amount in cents to be received. Example: 100 (R$1.00). |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `displayDescription` | STRING | Description shown in the payer bank interface. |
| `expiration` | INTEGER | Time in seconds from creation until expiration. |
| `pictureUrl` | STRING | URL of the dynamic brcode image. |
| `rules` | LIST OF OBJECTS | List of rule objects with key and value. |
| `tags` | LIST OF STRINGS | Tags associated with the dynamic brcode. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `uuid` | STRING | Unique UUID for the dynamic brcode. |

### Create Dynamic Brcodes

`POST /v2/dynamic-brcode`

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

**Request**

```python
import starkbank

brcodes = starkbank.dynamicbrcode.create([
    starkbank.DynamicBrcode(
        amount=4000,
        expiration=123456789,
        tags=["New sword", "DynamicBrcode #1234"],
        display_description="Payment for service #1234",
        rules=[
            {
                "key": "allowedTaxIds",
                "value": [
                    "012.345.678-90",
                    "45.059.493/0001-73"
                ]
            }
        ],
    )
])

for brcode in brcodes:
    print(brcode)
```

**Response**

```python
DynamicBrcode(
    amount=4000,
    created=2023-02-06 21:15:00.118056,
    expiration=123456789,
    id=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/80b0688d05934971a6b8ecd86cde69f25204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***630461C9,
    picture_url=https://sandbox.api.starkbank.com/v2/dynamic-brcode/80b0688d05934971a6b8ecd86cde69f2.png,
    tags=['new sword', 'dynamicbrcode #1234'],
    displayDescription=Payment for service #1234,
    rules=[
        Rule(
            key=allowedTaxIds,
            value=[
                '012.345.678-90',
                '45.059.493/0001-73'
            ]
        )
    ],
    updated=2023-02-06 21:15:00.449696,
    uuid=80b0688d05934971a6b8ecd86cde69f2
)
```

### List Dynamic Brcodes

`GET /v2/dynamic-brcode`

Get a list of brcodes in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

brcodes = starkbank.dynamicbrcode.query(
    after="2023-02-01",
    before="2023-02-28",
)

for brcode in brcodes:
    print(brcode)
```

**Response**

```python
DynamicBrcode(
    amount=4000,
    created=2023-02-06 21:15:00.118056,
    expiration=123456789,
    id=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/80b0688d05934971a6b8ecd86cde69f25204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***630461C9,
    picture_url=https://sandbox.api.starkbank.com/v2/dynamic-brcode/80b0688d05934971a6b8ecd86cde69f2.png,
    tags=['new sword', 'dynamicbrcode #1234'],
    displayDescription=Payment for service #1234,
    rules=[
        Rule(
            key=allowedTaxIds,
            value=[
                '012.345.678-90',
                '45.059.493/0001-73'
            ]
        )
    ],
    updated=2023-02-06 21:15:00.449696,
    uuid=80b0688d05934971a6b8ecd86cde69f2
)
```

### Get a Dynamic Brcode

`GET /v2/dynamic-brcode/:uuid`

Get a single dynamic brcode by its uuid.

**Request**

```python
import starkbank

brcode = starkbank.dynamicbrcode.get("80b0688d05934971a6b8ecd86cde69f2")

print(brcode)
```

**Response**

```python
DynamicBrcode(
    amount=4000,
    created=2023-02-06 21:15:00.118056,
    expiration=123456789,
    id=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/80b0688d05934971a6b8ecd86cde69f25204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***630461C9,
    picture_url=https://sandbox.api.starkbank.com/v2/dynamic-brcode/80b0688d05934971a6b8ecd86cde69f2.png,
    tags=['new sword', 'dynamicbrcode #1234'],
    displayDescription=Payment for service #1234,
    rules=[
        Rule(
            key=allowedTaxIds,
            value=[
                '012.345.678-90',
                '45.059.493/0001-73'
            ]
        )
    ],
    updated=2023-02-06 21:15:00.449696,
    uuid=80b0688d05934971a6b8ecd86cde69f2
)
```

## Deposit

Deposits represent passive cash-ins received by your account from external transfers or payments. In this section, we will teach you how to manage your Deposits.

### The Deposit object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the deposit. |
| `accountNumber` | STRING | Payer bank account number. |
| `accountType` | STRING | Payer bank account type. |
| `amount` | INTEGER | Deposit amount in cents. |
| `bankCode` | STRING | Payer bank code or ISPB. |
| `branchCode` | STRING | Payer bank branch. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `fee` | INTEGER | Fee charged in cents. |
| `name` | STRING | Payer full name. |
| `status` | STRING | Current deposit status. Options: "created", "void". |
| `tags` | LIST OF STRINGS | Tags associated with the deposit. |
| `taxId` | STRING | Payer CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the deposit. |
| `type` | STRING | Type of the deposit. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### List Deposits

`GET /v2/deposit`

Here you can list and filter all deposits you have received. We return it paged.

**Request**

```python
import starkbank

deposits = starkbank.deposit.query(
    after="2020-11-01",
    before="2020-11-30"
)

for deposit in deposits:
    print(deposit)
```

**Response**

```python
Deposit(
    account_number=1010101010101010,
    account_type= "payment",
    amount=100000,
    bank_code=20018183,
    branch_code=0001,
    created=2020-11-11 14:42:45.824846,
    fee=50,
    id=5155165527080960,
    name=Iron Bank S.A,
    status=created,
    tags=['deposit'],
    tax_id=10.203.000/0001-80,
    transaction_ids=['6663513506316288'],
    type=pix,
    updated=2020-11-11 14:42:47.333539
)
```

### Get a Deposit

`GET /v2/deposit/:id`

Get a single Deposit by its id.

**Request**

```python
import starkbank

deposit = starkbank.deposit.get("5155165527080960")

print(deposit)
```

**Response**

```python
Deposit(
    account_number=1010101010101010,
    account_type= "payment",
    amount=100000,
    bank_code=20018183,
    branch_code=0001,
    created=2020-11-11 14:42:45.824846,
    fee=50,
    id=5155165527080960,
    name=Iron Bank S.A,
    status=created,
    tags=['deposit'],
    tax_id=10.203.000/0001-80,
    transaction_ids=['6663513506316288'],
    type=pix,
    updated=2020-11-11 14:42:47.333539
)
```

### Update a Deposit

`PATCH /v2/deposit/:id`

Update the Deposit by passing its id to be partially or fully reversed.

**Request**

```python
import starkbank

deposit = starkbank.deposit.update(
    "5155165527080960",
    amount=0,
)

print(deposit)
```

**Response**

```python
Deposit (
  id="6165578200907776",
  name="Brice Ltda.",
  tax_id="72.831.025/0001-48",
  bank_code="07252614",
  branch_code="2645",
  account_number="4729524077596703",
  account_type="savings",
  amount=0,
  type="pix",
  status="created",
  tags=[
    "e07252614202310251510pkudndwgiev",
    "72055490-9aa6-4df9-ab5c-2009a9621f33",
    "ditto"
  ],
  fee=0,
  transaction_ids=[ "72909267320047755761378230622962" ],
  created="2023-10-25T15:10:51.111167+00:00",
  updated="2024-01-10T14:08:24.577238+00:00"
)
```

### List Deposit Logs

`GET /v2/deposit/log`

Get a paged list of all deposit logs. A log tracks a change in the deposit entity according to its life cycle.

**Request**

```python
import starkbank

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

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

**Response**

```python
Log(
    created=2020-11-11 14:44:44.385820,
    deposit=Deposit(
        account_number=1010101010101010,
        account_type=payment,
        amount=9000,
        bank_code=20018183,
        branch_code=0001,
        created=2020-11-11 14:44:43.144663,
        fee=50,
        id=5738709764800512,
        name=Iron Bank S.A,
        status=created,
        tags=['deposit'],
        tax_id=10.203.000/0001-80,
        transaction_ids=['5862355036536832'],
        type=pix,
        updated=2020-11-11 14:44:53.298960
    ),
    errors=[],
    id=5066704988143616,
    type=credited
)
```

### Get a Deposit Log

`GET /v2/deposit/log/:id`

Get a single deposit log by its id.

**Request**

```python
import starkbank

log = starkbank.deposit.log.get("5066704988143616")

print(log)
```

**Response**

```python
Log(
    created=2020-11-11 14:44:44.385820,
    deposit=Deposit(
        account_number=1010101010101010,
        account_type=payment,
        amount=9000,
        bank_code=20018183,
        branch_code=0001,
        created=2020-11-11 14:44:43.144663,
        fee=50,
        id=5738709764800512,
        name=Iron Bank S.A,
        status=created,
        tags=['deposit'],
        tax_id=10.203.000/0001-80,
        transaction_ids=['5862355036536832'],
        type=pix,
        updated=2020-11-11 14:44:53.298960
    ),
    errors=[],
    id=5066704988143616,
    type=credited
)
```

### Get a reversed Deposit Log PDF

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

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

**Request**

```python
import starkbank

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

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

## Boleto

A boleto is a method you can use to charge your customers or load your Stark Bank account. Here we will teach you how to create and manage boletos.

You can also split a Boleto between different receivers, you need to create a Split Receiver, and add the receiver into the Splits array.

### The Boleto object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the boleto. |
| `amount` | INTEGER | Amount in cents to be charged. Example: 100 (R$1.00). |
| `barCode` | STRING | Boleto bar code. |
| `city` | STRING | Customer city name. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `descriptions` | LIST OF OBJECTS | List of description objects. |
| `discounts` | LIST OF OBJECTS | List of discount objects. |
| `district` | STRING | Customer district name. |
| `due` | STRING | Due date of the boleto. Example: "2020-04-23". |
| `fee` | INTEGER | Fee charged in cents. |
| `fine` | FLOAT | Percentage charged if paid after due date. |
| `interest` | FLOAT | Monthly percentage charged if paid after due date. |
| `line` | STRING | Boleto line number. |
| `name` | STRING | Customer full name. |
| `ourNumber` | STRING | Boleto control number (nosso numero). |
| `overdueLimit` | INTEGER | Number of days after due date until boleto expires. |
| `receiverName` | STRING | Name of the credit receiver (Sacador Avalista). |
| `receiverTaxId` | STRING | Tax ID of the credit receiver. |
| `stateCode` | STRING | Customer state code. |
| `status` | STRING | Current boleto status. Options: "created", "overdue", "paid", "canceled". |
| `streetLine1` | STRING | Customer street address. |
| `streetLine2` | STRING | Customer street address complement. |
| `tags` | LIST OF STRINGS | Tags associated with the boleto. |
| `taxId` | STRING | Customer CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the boleto. |
| `workspaceId` | STRING | ID of the workspace that created the boleto. |
| `zipCode` | STRING | Customer zip code. |

### Create Boletos

`POST /v2/boleto`

This is how you create a new list of boletos. You can create up to 100 boletos per request. In case a boleto is paid after its due date and there is fine or interest, its amount will be updated with the paid amount. The same is valid if the boleto is paid with a discount.

**Request**

```python
import starkbank

boletos = starkbank.boleto.create([
    starkbank.Boleto(
        amount=400000,
        due="2020-05-20",
        name="Iron Bank S.A.",
        tax_id="20.018.183/0001-80",
        fine=2.5,
        interest=1.3,
        overdue_limit=5,
        street_line_1="Av. Faria Lima, 1844",
        street_line_2="CJ 13",
        district="Itaim Bibi",
        city="São Paulo",
        state_code="SP",
        zip_code="01500-000",
        tags=["War supply", "Invoice #1234"],
        discounts=[
            {"percentage": 10, "date": "2020-04-25"}
        ],
        splits=[
            Split(amount=3000, receiverId="5742447426535424"), Split(amount=5000, receiverId="5743243941642240")
        ]
    )
])

for boleto in boletos:
    print(boleto)
```

**Response**

```python
Boleto(
    id=6655767935451136,
    amount=400000,
    bar_code=34191826100004000001091007175647307144464000,
    city=São Paulo,
    created=2020-04-23 23:36:08.129614,
    descriptions=[],
    discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
    district=Itaim Bibi,
    due=2020-05-21,
    fee=0,
    fine=2.5,
    interest=1.3,
    line=34191.09107 07175.647309 71444.640008 1 82610000400000,
    name=Iron Bank S.A.,
    our_number=10445145,
    transaction_ids=[],
    overdue_limit=5,
    receiver_name=Winterfell S. A.,
    receiver_tax_id=71.735.814/0001-12,
    state_code=SP,
    status=created,
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=CJ 13,
    tags=['war supply', 'invoice #1234'],
    tax_id=20.018.183/0001-80,
    zip_code=01500-000,
    workspace_id=5083989094170624,
    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 Boletos

`GET /v2/boleto`

Get a list of non-deleted boletos in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

boletos = starkbank.boleto.query(
    after="2020-04-01",
    before="2020-04-30"
)

for boleto in boletos:
    print(boleto)
```

**Response**

```python
Boleto(
    id=6655767935451136,
    amount=400000,
    bar_code=34191826100004000001091007175647307144464000,
    city=São Paulo,
    created=2020-04-23 23:36:08.129614,
    descriptions=[],
    discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
    district=Itaim Bibi,
    due=2020-05-21,
    fee=0,
    fine=2.5,
    interest=1.3,
    line=34191.09107 07175.647309 71444.640008 1 82610000400000,
    name=Iron Bank S.A.,
    our_number=10445145,
    transaction_ids=[],
    overdue_limit=5,
    receiver_name=Winterfell S. A.,
    receiver_tax_id=71.735.814/0001-12,
    state_code=SP,
    status=created,
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=CJ 13,
    tags=['war supply', 'invoice #1234'],
    tax_id=20.018.183/0001-80,
    zip_code=01500-000
    workspace_id=5083989094170624
)
```

### Get a Boleto

`GET /v2/boleto/:id`

Get a single boleto by its id.

**Request**

```python
import starkbank

boleto = starkbank.boleto.get("6655767935451136")

print(boleto)
```

**Response**

```python
Boleto(
    id=6655767935451136,
    amount=400000,
    bar_code=34191826100004000001091007175647307144464000,
    city=São Paulo,
    created=2020-04-23 23:36:08.129614,
    descriptions=[],
    discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
    district=Itaim Bibi,
    due=2020-05-21,
    fee=0,
    fine=2.5,
    interest=1.3,
    line=34191.09107 07175.647309 71444.640008 1 82610000400000,
    name=Iron Bank S.A.,
    our_number=10445145,
    transaction_ids=[],
    overdue_limit=5,
    receiver_name=Winterfell S. A.,
    receiver_tax_id=71.735.814/0001-12,
    state_code=SP,
    status=created,
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=CJ 13,
    tags=['war supply', 'invoice #1234'],
    tax_id=20.018.183/0001-80,
    zip_code=01500-000,
    workspace_id=5083989094170624
)
```

### Delete a Boleto

`DELETE /v2/boleto/:id`

Delete a single boleto. We will send a request to CIP to cancel the boleto registration. After the boleto registration is canceled, it won't be possible to pay it anymore.

NOTE: This action cannot be undone.

**Request**

```python
import starkbank

boleto = starkbank.boleto.delete("6655767935451136")

print(boleto)
```

**Response**

```python
Boleto(
    id=6655767935451136,
    amount=400000,
    bar_code=34191826100004000001091007175647307144464000,
    city=São Paulo,
    created=2020-04-23 23:36:08.129614,
    descriptions=[],
    discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
    district=Itaim Bibi,
    due=2020-05-21,
    fee=0,
    fine=2.5,
    interest=1.3,
    line=34191.09107 07175.647309 71444.640008 1 82610000400000,
    name=Iron Bank S.A.,
    our_number=10445145,
    transaction_ids=[],
    overdue_limit=5,
    receiver_name=Winterfell S. A.,
    receiver_tax_id=71.735.814/0001-12,
    state_code=SP,
    status=created,
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=CJ 13,
    tags=['war supply', 'invoice #1234'],
    tax_id=20.018.183/0001-80,
    zip_code=01500-000,
    workspace_id=5083989094170624
)
```

### Get a Boleto PDF

`GET /v2/boleto/:id/pdf`

Get a downloadable boleto PDF file. This route is public and does not require the usual authentication headers. However, if you request an invalid boleto ID too many times, your IP will be blocked for this specific route.

**Request**

```python
import starkbank

pdf = starkbank.boleto.pdf("6655767935451136")

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

### List Boleto logs

`GET /v2/boleto/log`

Get a paged list of boleto logs. A log tracks a change in the boleto entity according to its life cycle.

**Request**

```python
import starkbank

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

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

**Response**

```python
Log(
    id=6465045294743552,
    created=2020-04-24 23:46:14.703951,
    errors=[],
    type=paid,
    boleto=Boleto(
        id=6655767935451136,
        amount=400000,
        bar_code=34191826100004000001091007175647307144464000,
        city=São Paulo,
        created=2020-04-23 23:36:08.129614,
        descriptions=[],
        discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
        district=Itaim Bibi,
        due=2020-05-21,
        fee=0,
        fine=2.5,
        interest=1.3,
        line=34191.09107 07175.647309 71444.640008 1 82610000400000,
        name=Iron Bank S.A.,
        our_number=10445145,
        transaction_ids=[],
        overdue_limit=5,
        receiver_name=Winterfell S. A.,
        receiver_tax_id=71.735.814/0001-12,
        state_code=SP,
        status=created,
        street_line_1=Av. Faria Lima, 1844,
        street_line_2=CJ 13,
        tags=['war supply', 'invoice #1234'],
        tax_id=20.018.183/0001-80,
        zip_code=01500-000
        workspace_id=5083989094170624
    )
)
```

### Get a Boleto Log

`GET /v2/boleto/log/:id`

Get a single boleto log by its id.

**Request**

```python
import starkbank

log = starkbank.boleto.log.get("6465045294743552")

print(log)
```

**Response**

```python
Log(
    id=6465045294743552,
    created=2020-04-24 23:46:14.703951,
    errors=[],
    type=paid,
    boleto=Boleto(
        id=6655767935451136,
        amount=400000,
        bar_code=34191826100004000001091007175647307144464000,
        city=São Paulo,
        created=2020-04-23 23:36:08.129614,
        descriptions=[],
        discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
        district=Itaim Bibi,
        due=2020-05-21,
        fee=0,
        fine=2.5,
        interest=1.3,
        line=34191.09107 07175.647309 71444.640008 1 82610000400000,
        name=Iron Bank S.A.,
        our_number=10445145,
        transaction_ids=[],
        overdue_limit=5,
        receiver_name=Winterfell S. A.,
        receiver_tax_id=71.735.814/0001-12,
        state_code=SP,
        status=created,
        street_line_1=Av. Faria Lima, 1844,
        street_line_2=CJ 13,
        tags=['war supply', 'invoice #1234'],
        tax_id=20.018.183/0001-80,
        zip_code=01500-000,
        workspace_id=5083989094170624
    )
)
```

## Boleto Holmes

Honoring the famous Sherlock Holmes, this feature allows your application to investigate updated boleto status according to CIP in less than an hour.

Here we will teach you how to create and manage your Boleto Holmes. Ideally, since results are asynchronous, you should register a Boleto Holmes webhook subscription in order to receive the investigation results instead of polling.

### The Boleto Holmes object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the boleto holmes. |
| `boletoId` | STRING | Investigated boleto entity ID. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `result` | STRING | Result of the investigation. Options: "paid", "canceled", "registered". |
| `status` | STRING | Current holmes status. Options: "created", "solving", "solved". |
| `tags` | LIST OF STRINGS | Tags associated with the boleto holmes. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Boleto Holmes

`POST /v2/boleto-holmes`

Use this route to verify the updated status of boletos generated at Stark Bank according to CIP.

**Request**

```python
import starkbank

holmes = starkbank.boletoholmes.create([
    starkbank.BoletoHolmes(
        boleto_id="5656565656565656",
        tags=["sherlock", "holmes"],
    )
])

for holmes in holmes:
    print(holmes)
```

**Response**

```python
BoletoHolmes(
    boleto_id=5656565656565656,
    created=2020-07-23 00:07:51.069587,
    id=3232323232323232,
    result=,
    status=solving,
    tags=["sherlock", "holmes"],
    updated=2020-07-23 00:07:51.069597
)
```

### List Boleto Holmes

`GET /v2/boleto-holmes`

Get a list of non-deleted boletos in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

holmes = starkbank.boletoholmes.query(
    boleto_id="5656565656565656",
    after="2020-07-01",
    before="2020-07-30"
)

for holmes in holmes:
    print(holmes)
```

**Response**

```python
BoletoHolmes(
    boleto_id=5656565656565656,
    created=2020-07-23 00:07:51.069587,
    id=3232323232323232,
    result=paid,
    status=solved,
    tags=["sherlock", "holmes"],
    updated=2020-07-23 00:07:51.069597
)
```

### Get a Boleto Holmes

`GET /v2/boleto-holmes/:id`

Get a single boleto holmes by its id.

**Request**

```python
import starkbank

holmes = starkbank.boletoholmes.get("3232323232323232")

print(holmes)
```

**Response**

```python
BoletoHolmes(
    boleto_id=5656565656565656,
    created=2020-07-23 00:07:51.069587,
    id=3232323232323232,
    result=,
    status=solving,
    tags=["sherlock", "holmes"],
    updated=2020-07-23 00:07:51.069597
)
```

### List Boleto Holmes Logs

`GET /v2/boleto-holmes/log`

Get a paged list of all boleto holmes logs. A log tracks a change in the holmes entity according to its life cycle.

**Request**

```python
import starkbank

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

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

**Response**

```python
Log(
    id=1010101010101010,
    created=2020-07-24 17:58:32.075347,
    type=solved,
    holmes=BoletoHolmes(
        boleto_id=5656565656565656,
        created=2020-07-23 00:07:51.069587,
        id=3232323232323232,
        result=paid,
        status=solved,
        tags=["sherlock", "holmes"],
        updated=2020-07-23 00:07:51.069597
    ),
    updated=2020-07-24 17:58:32.075347,
)
```

### Get a Boleto Holmes Log

`GET /v2/boleto-holmes/log/:id`

Get a single boleto holmes log by its id.

**Request**

```python
import starkbank

log = starkbank.boletoholmes.log.get("1010101010101010")

print(log)
```

**Response**

```python
Log(
    id=1010101010101010,
    created=2020-07-24 17:58:32.075347,
    updated=2020-07-24 17:58:32.075347,
    type=solved,
    holmes=BoletoHolmes(
        boleto_id=5656565656565656,
        created=2020-07-23 00:07:51.069587,
        id=3232323232323232,
        result=paid,
        status=solved,
        tags=["sherlock", "holmes"],
        updated=2020-07-23 00:07:51.069597
    )
)
```

## Split

The Split resource is used to split an Invoice or Boleto between different receivers.

### The Split object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the split. |
| `amount` | INTEGER | Split amount in cents. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `externalId` | STRING | Unique external ID for the split. |
| `receiverId` | STRING | ID of the split receiver. |
| `scheduled` | STRING | Scheduled transfer datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `source` | STRING | Source of the split. |
| `status` | STRING | Current split status. |
| `tags` | LIST OF STRINGS | Tags associated with the split. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### List Splits

`GET /v2/split`

Get a list of Splits in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

splits = starkbank.split.query(
    after="2024-01-30",
    before="2024-02-01",
    limit=1
)

for split in splits:
    print(split)
```

**Response**

```python
Split(
	amount=10000,
	created=2024-01-30 16:10:59.874663,
	external_id=invoice/5163468596445184/receiver/5143677177430016,
	id=5745664021495808,
	receiver_id=5143677177430016,
	scheduled=2024-01-30 16:10:59.840821,
	source=invoice/5163468596445184,
	status=created,
	tags=['invoice/5163468596445184'],
	updated=2024-01-30 16:21:03.973723
)
```

### Get a Split

`GET /v2/split/:id`

Get a single Split by its id.

**Request**

```python
import starkbank

split = starkbank.split.get("5155165527080960")

print(split)
```

**Response**

```python
Split(
	amount=10000,
	created=2024-01-30 16:10:59.874824,
	external_id=invoice/5163468596445184/receiver/5706627130851328,
	id=5155165527080960,
	receiver_id=5706627130851328,
	scheduled=2024-01-30 16:10:59.840821,
	source=invoice/5163468596445184,
	status=created,
	tags=['invoice/5163468596445184'],
	updated=2024-01-30 16:10:59.874829
)
```

### List Split Logs

`GET /v2/split/log`

Get a paged list of Split logs. A log tracks a change in the Split entity according to its life cycle.

**Request**

```python
import starkbank

logs = starkbank.split.log.query(
    after="2020-10-01",
    before="2020-10-30"
)
for log in logs:
  print(log)
```

**Response**

```python
Log(
	created=2024-01-30 16:21:03.459601,
	errors=None,
	id=5659211052613632,
	split=Split(
		amount=10000,
		created=2024-01-30 16:10:59.874663,
		external_id=invoice/5163468596445184/receiver/5143677177430016,
		id=5745664021495808,
		receiver_id=5143677177430016,
		scheduled=2024-01-30 16:10:59.840821,
		source=invoice/5163468596445184,
		status=created,
		tags=['invoice/5163468596445184'],
		updated=2024-01-30 16:21:04.002158
	),
	type=created
)
```

### Get a Split Log

`GET /v2/split/log/:id`

Get a single Split Log by its id.

**Request**

```python
import starkbank

log = starkbank.split.log.get("5729450050191360")

print(log)
```

**Response**

```python
Log(
	created=2024-01-30 16:21:03.459601,
	errors=None,
	id=5729450050191360,
	split=Split(
		amount=10000,
		created=2024-01-30 16:10:59.874663,
		external_id=invoice/5163468596445184/receiver/5143677177430016,
		id=5745664021495808,
		receiver_id=5143677177430016,
		scheduled=2024-01-30 16:10:59.840821,
		source=invoice/5163468596445184,
		status=success,
		tags=['invoice/5163468596445184'],
		updated=2024-01-30 16:21:04.002158
	),
	type=success
)
```

## Split Receiver

You can create a Receiver to an Invoice or Boleto split by using the Split Receiver resource.

### The Split Receiver object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the split receiver. |
| `accountNumber` | STRING | Receiver bank account number. |
| `accountType` | STRING | Receiver bank account type. Options: "checking", "savings", "salary", "payment". |
| `bankCode` | STRING | Receiver bank code or ISPB. |
| `branchCode` | STRING | Receiver bank account branch. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `name` | STRING | Receiver full name. |
| `status` | STRING | Current split receiver status. |
| `tags` | LIST OF STRINGS | Tags associated with the split receiver. |
| `taxId` | STRING | Receiver CPF or CNPJ. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Split Receiver

`POST /v2/split-receiver`

Send a list of Split Receiver objects for creation in the Stark Bank API

**Request**

```python
import starkbank

receiver = starkbank.splitreceiver.create(
      receiver=starkbank.SplitReceiver(
        name="Daenerys Targaryen Stormborn",
        tax_id="594.739.480-42",
        bank_code="665",
        branch_code="2201",
        account_number="76543-8",
        account_type="salary"
    )
)

print(receiver)
```

**Response**

```python
SplitReceiver(
	account_number=76543-8,
	account_type=salary,
	bank_code=665,
	branch_code=2201,
	created=2024-01-30 20:17:12.586145,
	id=5710191014182912,
	name=Daenerys Targaryen Stormborn,
	status=created,
	tags=[],
	tax_id=594.739.480-42,
	updated=2024-01-30 20:17:12.586152
)
```

### List Split Receivers

`GET /v2/split-receiver`

Get a list of Split Receivers in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

receivers = starkbank.splitreceiver.query(limit=1)

for receiver in receivers:
    print(receiver)
```

**Response**

```python
SplitReceiver(
	account_number=73068305-0,
	account_type=salary,
	bank_code=18236120,
	branch_code=250,
	created=2024-01-30 20:17:12.586344,
	id=5147241060761600,
	name=Lucille Jette,
	status=created,
	tags=[],
	tax_id=949.887.518-99,
	updated=2024-01-30 20:17:13.685002
)
```

### Get a Split Receiver

`GET /v2/split-receiver/:id`

Retrieve a single Split Receiver object previously created in the Stark Bank API by its id.

**Request**

```python
import starkbank

receiver = starkbank.splitreceiver.get("5155165527080960")

print(receiver)
```

**Response**

```python
SplitReceiver(
	account_number=73068305-0,
	account_type=salary,
	bank_code=18236120,
	branch_code=250,
	created=2024-01-30 20:17:12.586344,
	id=5155165527080960,
	name=Lucille Jette,
	status=created,
	tags=[],
	tax_id=949.887.518-99,
	updated=2024-01-30 20:17:13.685002
)
```

### List Split Receiver Logs

`GET /v2/split-receiver/log`

Get a paged list of Split Receiver logs. A log tracks a change in the Split Receiver entity according to its life cycle.

**Request**

```python
import starkbank

log = starkbank.splitreceiver.log.get(
    after="2024-10-30",
    before="2024-10-01"
)

print(log)
```

**Response**

```python
Log(
	created=2024-01-30 20:17:12.611535,
	errors=None,
	id=4865766084050944,
	receiver=SplitReceiver(
		account_number=73068305-0,
		account_type=salary,
		bank_code=18236120,
		branch_code=250,
		created=2024-01-30 20:17:12.586344,
		id=5147241060761600,
		name=Lucille Jette,
		status=created,
		tags=[],
		tax_id=949.887.518-99,
		updated=2024-01-30 20:17:13.712424
	),
	type=created
)
```

### Get a Split Receiver Log

`GET /v2/split-receiver/log/:id`

Get a single Split Receiver Log by its id.

**Request**

```python
import starkbank

log = starkbank.splitreceiver.log.get("5155165527080960")

print(log)
```

**Response**

```python
Log(
	created=2024-01-30 20:17:12.611535,
	errors=None,
	id=5155165527080960,
	receiver=SplitReceiver(
		account_number=73068305-0,
		account_type=salary,
		bank_code=18236120,
		branch_code=250,
		created=2024-01-30 20:17:12.586344,
		id=5147241060761600,
		name=Lucille Jette,
		status=created,
		tags=[],
		tax_id=949.887.518-99,
		updated=2024-01-30 20:17:13.712424
	),
	type=created
)
```

## Split Profile

The Split Profile resource is used to configure the behavior of split operations.

### The Split Profile object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the split profile. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `delay` | INTEGER | Time in milliseconds the amount stays at the workspace. |
| `interval` | STRING | Frequency of transfer. Options: "day", "week", "month". |
| `status` | STRING | Current split profile status. |
| `tags` | LIST OF STRINGS | Tags associated with the split profile. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Put a Split Profile

`PUT /v2/split-profile`

Send a list containing a single Split Profile object. If the object has already been created, its rules will be updated.

**Request**

```python
import starkbank

payload ={
    "interval": "day",
    "delay": 0
}
splitprofile = starkbank.splitprofile.update([payload])

for profile in splitprofile:
  print(profile)
```

**Response**

```python
SplitProfile(
  created=2023-10-24 00:23:08.831127,
  delay=0,
  id=6206954716266496,
  interval=day,
  status=created,
  tags=[],
  updated=2024-02-26 17:56:13.304200
)
```

### List Split Profiles

`GET /v2/split-profile`

Get a list of Split Profiles in chunks of up to 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

splitprofiles = starkbank.splitprofile.query(limit=2)

for profile in splitprofiles:
    print(profile)
```

**Response**

```python
SplitProfile(
    created=2023-10-24 00:23:08.831127,
    delay=0,
    id=6206954716266496,
    interval=day,
    status=created,
    tags=[],
    updated=2024-02-26 17:56:13.539948
)
```

### Get a Split Profile

`GET /v2/split-profile/:id`

Retrieve a single Split Profile object by its ID, which was previously created.

**Request**

```python
import starkbank

splitprofile = starkbank.splitprofile.get(5634161670881280)

print(splitprofile)
```

**Response**

```python
SplitProfile(
  created=2023-10-24 00:23:08.831127,
  delay=0,
  id=6206954716266496,
  interval=day,
  status=created,
  tags=[],
  updated=2024-02-26 17:56:13.539948
)
```

### List Split Profile Logs

`GET /v2/split-profile/log`

Get a paged list of Split Profile logs. A log tracks a change in the Split Profile entity according to its life cycle.

**Request**

```python
import starkbank

logs = starkbank.splitprofile.log.query(limit=10)

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

**Response**

```python
Log(
  created=2024-02-26 17:56:13.326078,
  errors=None,
  id=5746640992337920,
  profile=SplitProfile(
    created=2023-10-24 00:23:08.831127,
    delay=0,
    id=6206954716266496,
    interval=day,
    status=created,
    tags=[],
    updated=2024-02-26 17:56:13.581938
  ),
  type=updated
)
```

### Get a Split Profile Log

`GET /v2/split-profile/log/:id`

Get a single Split Profile Log by its id.

**Request**

```python
import starkbank

log = starkbank.splitprofile.log.get("5634161670881280")

print(log)
```

**Response**

```python
Log(
  created=2024-02-26 17:56:13.326078,
  errors=None,
  id=5746640992337920,
  profile=SplitProfile(
    created=2023-10-24 00:23:08.831127,
    delay=0,
    id=6206954716266496,
    interval=day,
    status=created,
    tags=[],
    updated=2024-02-26 17:56:13.581938
  ),
  type=updated
)
```

# Cash Subscription

## Invoice Pull Subscription

An Invoice Pull Subscription is a recurring payment agreement between a payer and a receiver, authorized through the Pix Automatic infrastructure. Once active, it allows the receiver to periodically trigger automatic debits by issuing invoices that match the agreed conditions such as amount, frequency, and billing cycle without requiring new consent for each transaction.

You can use asynchronous webhooks to monitor status changes.

### The Invoice Pull Subscription object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the subscription. |
| `amount` | INTEGER | Fixed amount to be charged every cycle in cents. |
| `amountMinLimit` | INTEGER | Minimum amount limit in cents. |
| `bacenId` | STRING | Central Bank identifier. |
| `brcode` | STRING | BR Code for the subscription. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `displayDescription` | STRING | Description presented to the payer. |
| `due` | STRING | Due date for payer approval or denial. |
| `end` | STRING | Final date of the subscription. |
| `externalId` | STRING | Unique external ID to prevent duplicate subscriptions. |
| `interval` | STRING | Cycle definition. Options: "week", "month", "quarter", "semester", "year". |
| `name` | STRING | Debtor full name. |
| `pullMode` | STRING | Defines if pull requests are automatic or manual. |
| `pullRetryLimit` | INTEGER | Number of retries allowed. Options: 0, 3. |
| `referenceCode` | STRING | Unique reference code for the contract. |
| `start` | STRING | Expected date to settle first pull request. |
| `status` | STRING | Current subscription status. |
| `tags` | LIST OF STRINGS | Tags associated with the subscription. |
| `taxId` | STRING | Debtor CPF or CNPJ. |
| `type` | STRING | Subscription journey type. Options: "push", "qrcode", "qrcodeAndPayment", "paymentAndOrQrCode". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Invoice Pull Subscriptions

`POST /v2/invoice-pull-subscription`

Use this route to create new invoice pull subscriptions.

**Request**

```python
import starkbank

subscriptions = starkbank.invoicepullsubscription.create([
    starkbank.InvoicePullSubscription(
        amount=0,
        amount_min_limit=5000,
        data={
            "account_number": "9123900000",
            "bank_code": "05097757",
            "branch_code": "1126",
            "tax_id": "20.018.183/0001-80"
        },
        display_description="Dragon Travel Fare",
        external_id="b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
        interval="month",
        name="John Snow",
        pull_mode="manual",
        pull_retry_limit=3,
        start="2025-09-14T00:00:00Z",
        end="2025-10-14T00:00:00Z",
        reference_code="contract-12345",
        tags=[],
        tax_id="012.345.678-90",
        type="push"
    ),
])

for subscription in subscriptions:
    print(subscription)
```

**Response**

```python
InvoicePullSubscription(
    amount=0,
    amount_min_limit=5000,
    bacen_id=RR2001818320250904xDUK7RgCRT4,
    created=2025-09-04 20:57:33.833777,
    data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
    display_description=Dragon Travel Fare,
    due=2025-09-14 00:00:00,
    end=2025-10-14 00:00:00,
    external_id=b7e6a2c2-8e2b-4c1a-9e2a-123456789abc,
    id=5656565656565656,
    interval=month,
    name=John Snow,
    pull_mode=manual,
    pull_retry_limit=3,
    reference_code=contract-12345,
    start=2025-09-14 00:00:00,
    status=active,
    tags=[],
    tax_id=012.345.678-90,
    type=push,
    updated=2025-09-14 00:00:00
)
```

### List Invoice Pull Subscriptions

`GET /v2/invoice-pull-subscription`

Here you can list and filter all invoice pull subscriptions you have made. We return it paged.

**Request**

```python
import starkbank

subscriptions = starkbank.invoicepullsubscription.query(
    after="2025-09-01",
    before="2025-09-30",
)

for subscription in subscriptions:
    print(subscription)
```

**Response**

```python
InvoicePullSubscription(
    amount=0,
    amount_min_limit=5000,
    bacen_id=RR2001818320250909WDW2JAoiyB2,
    created=2025-09-09 21:42:36.419070,
    data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
    display_description=Dragon Travel Fare,
    due=2025-09-11 21:42:35.878330,
    end=2025-10-14 03:00:00,
    external_id=e0ef6c02-f58e-44cd-b04d-e914d4df9405,
    id=4656724615102464,
    interval=month,
    name=John Snow,
    pull_mode=manual,
    pull_retry_limit=3,
    reference_code=contract-12345,
    start=2025-09-14 03:00:00,
    status=active,
    tags=[],
    tax_id=012.345.678-90,
    type=push,
    updated=2025-09-09 21:42:43.694648
)
```

### Get an Invoice Pull Subscription

`GET /v2/invoice-pull-subscription/:id`

Get a single invoice pull subscription by its id.

**Request**

```python
import starkbank

subscriptions = starkbank.invoicepullsubscription.get("4656724615102464")

for subscription in subscriptions:
    print(subscription)
```

**Response**

```python
InvoicePullSubscription(
    amount=0,
    amount_min_limit=5000,
    bacen_id=RR2001818320250909WDW2JAoiyB2,
    created=2025-09-09 21:42:36.419070,
    data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
    display_description=Dragon Travel Fare,
    due=2025-09-11 21:42:35.878330,
    end=2025-10-14 03:00:00,
    external_id=e0ef6c02-f58e-44cd-b04d-e914d4df9405,
    id=4656724615102464,
    interval=month,
    name=John Snow,
    pull_mode=manual,
    pull_retry_limit=3,
    reference_code=contract-12345,
    start=2025-09-14 03:00:00,
    status=active,
    tags=[],
    tax_id=012.345.678-90,
    type=push,
    updated=2025-09-09 21:42:43.694648
)
```

### Cancel an Invoice Pull Subscription

`DELETE /v2/invoice-pull-subscription/:id`

Cancel an existing invoice pull subscription. The subscription must be with "active" status to be canceled.

**Request**

```python
import starkbank

subscriptions = starkbank.invoicepullsubscription.cancel("4656724615102464")

print(subscription)
```

**Response**

```python
InvoicePullSubscription(
        amount=0,
        amount_min_limit=5000,
        bacen_id=RR2001818320250909WDW2JAoiyB2,
        created=2025-09-09 21:42:36.419070,
        data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
        display_description=Dragon Travel Fare,
        due=2025-09-11 21:42:35.878330,
        end=2025-10-14 03:00:00,
        external_id=e0ef6c02-f58e-44cd-b04d-e914d4df9405,
        id=4656724615102464,
        interval=month,
        name=John Snow,
        pull_mode=manual,
        pull_retry_limit=3,
        reference_code=contract-12345,
        start=2025-09-14 03:00:00,
        status=active,
        tags=[],
        tax_id=012.345.678-90,
        type=push,
        updated=2025-09-09 21:42:43.694648
)
```

### List Invoice Pull Subscription Logs

`GET /v2/invoice-pull-subscription/log`

Get a paged list of invoice pull subscription logs. A log tracks a change in the entity according to its life cycle.

**Request**

```python
import starkbank

logs = starkbank.invoicepullsubscription.log.query(
    after="2025-09-01",
    before="2025-09-30",
)

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

**Response**

```python
Log(
    created=2025-09-09 21:58:09.963082,
    errors=[],
    id=5631191491280896,
    subscription=InvoicePullSubscription(
            amount=1000000,
            amount_min_limit=5000,
            bacen_id=RR2001818320250909fxSoQw3VO04,
            created=2025-09-09 21:58:03.557191,
            data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
            display_description=Dragon Travel Fare,
            due=2025-09-11 21:58:02.951121,
            end=2025-10-14 03:00:00,
            external_id=f4a4c70b-bf5a-400d-8eae-685128691645z,
            id=4582433332658176,
            interval=month,
            name=John Snow,
            pull_mode=manual,
            pull_retry_limit=3,
            reference_code=contract-12345,
            start=2025-09-14 03:00:00,
            status=active,
            tags=[],
            tax_id=012.345.678-90,
            type=push,
            updated=2025-09-09 21:58:11.552600
    ),
    type=confirmed
)
```

### Get an Invoice Pull Subscription Log

`GET /v2/invoice-pull-subscription/log/:id`

Get a single invoice pull subscription log by its id.

**Request**

```python
import starkbank

logs = starkbank.invoicepullsubscription.log.get("5631191491280896")

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

**Response**

```python
Log(
    created=2025-09-09 21:58:09.963082,
    errors=[],
    id=5631191491280896,
    subscription=InvoicePullSubscription(
            amount=1000000,
            amount_min_limit=5000,
            bacen_id=RR2001818320250909fxSoQw3VO04,
            created=2025-09-09 21:58:03.557191,
            data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
            display_description=Dragon Travel Fare,
            due=2025-09-11 21:58:02.951121,
            end=2025-10-14 03:00:00,
            external_id=f4a4c70b-bf5a-400d-8eae-685128691645z,
            id=4582433332658176,
            interval=month,
            name=John Snow,
            pull_mode=manual,
            pull_retry_limit=3,
            reference_code=contract-12345,
            start=2025-09-14 03:00:00,
            status=active,
            tags=[],
            tax_id=012.345.678-90,
            type=push,
            updated=2025-09-09 21:58:11.552600
    ),
    type=confirmed
)
```

## Invoice Pull Request

An Invoice Pull Request is a command sent to the payer's bank to trigger the automatic debit of a previously issued invoice linked to an active Invoice Pull Subscription. It confirms the receiver's intent to collect the agreed amount within the current billing cycle and initiates the settlement process through the Pix infrastructure.

You can use asynchronous webhooks to monitor status changes.

### The Invoice Pull Request object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the pull request. |
| `attemptType` | STRING | Type of attempt. Options: "default", "retry". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `displayDescription` | STRING | Description presented to the payer. |
| `due` | STRING | Expected date of settlement. |
| `externalId` | STRING | Unique external ID for the pull request. |
| `installmentId` | STRING | ID of the installment linked to the pull request. |
| `invoiceId` | STRING | ID of the invoice to be pulled. |
| `status` | STRING | Current pull request status. |
| `subscriptionId` | STRING | ID of the invoice pull subscription. |
| `tags` | LIST OF STRINGS | Tags associated with the pull request. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Invoice Pull Requests

`POST /v2/invoice-pull-request`

Use this route to create new invoice pull requests.

**Request**

```python
import starkbank

requests = starkbank.invoicepullrequest.create([
    starkbank.InvoicePullRequest(
        attempt_type="retry",
        due="2025-09-14",
        invoice_id="6649956664344576",
        subscription_id="4776669403414528",
        tags=[]
    )
])

for request in requests:
    print(request)
```

**Response**

```python
InvoicePullRequest(
    attempt_type=retry,
    created=2025-09-10 18:21:46.579211,
    display_description=,
    due=2025-09-14 03:00:00,
    external_id=c3cb7f72c8d94069adbc52a3b65515a4,
    id=5649587104645120,
    installment_id=5187902950604800,
    invoice_id=6649956664344576,
    status=created,
    subscription_id=4776669403414528,
    tags=[],
    updated=2025-09-10 18:21:46.579216
)
```

### List Invoice Pull Requests

`GET /v2/invoice-pull-request`

Here you can list and filter all invoice pull requests you have made. We return it paged.

**Request**

```python
import starkbank

requests = starkbank.invoicepullrequest.query(
    after="2025-08-01",
    before="2025-08-30",
)

for request in requests:
    print(request)
```

**Response**

```python
InvoicePullRequest(
        attempt_type=default,
        created=2025-08-14 18:23:40.089592,
        display_description=,
        due=2025-08-16 23:59:59,
        external_id=c0a7f183f32e42b9a4cfc5ee997a3455,
        id=4875989783937024,
        installment_id=6381497086902272,
        invoice_id=5192316503457792,
        status=failed,
        subscription_id=4871746087813120,
        tags=[],
        updated=2025-08-17 00:00:07.816140
)
```

### Get an Invoice Pull Request

`GET /v2/invoice-pull-request/:id`

Get a single Invoice Pull Request by its id.

**Request**

```python
import starkbank

requests = starkbank.invoicepullrequest.get("4875989783937024")

for request in requests:
    print(request)
```

**Response**

```python
InvoicePullRequest(
        attempt_type=default,
        created=2025-08-14 18:23:40.089592,
        display_description=,
        due=2025-08-16 23:59:59,
        external_id=c0a7f183f32e42b9a4cfc5ee997a3455,
        id=4875989783937024,
        installment_id=6381497086902272,
        invoice_id=5192316503457792,
        status=failed,
        subscription_id=4871746087813120,
        tags=[],
        updated=2025-08-17 00:00:07.816140
)
```

### Cancel an Invoice Pull Request

`DELETE /v2/invoice-pull-request/:id`

Cancel a single Invoice Pull Request.

**Request**

```python
import starkbank

request = starkbank.invoicepullrequest.cancel("6281065945628672")

print(request)
```

**Response**

```python
InvoicePullRequest(
        attempt_type=default,
        created=2025-09-07 03:00:15.420295,
        display_description=Iron Bank S.A.,
        due=2025-09-09 03:00:00,
        external_id=35ce0f6775fc42f8942b6142aa9fd9b6,
        id=6281065945628672,
        installment_id=6401171258343424,
        invoice_id=4616495631958016,
        status=scheduled,
        subscription_id=5692449980678144,
        tags=[],
        updated=2025-09-07 03:00:57.777005
)
```

### List Invoice Pull Request Logs

`GET /v2/invoice-pull-request/log`

Get a paged list of invoice pull request logs. A log tracks a change in the entity according to its life cycle.

**Request**

```python
import starkbank

logs = starkbank.invoicepullrequest.log.get(
    after="2025-08-01",
    before="2025-08-30"
)

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

**Response**

```python
Log(
        created=2025-08-17 00:00:05.640702,
        errors=[],
        id=5439643239579648,
        request=InvoicePullRequest(
                attempt_type=default,
                created=2025-08-14 18:23:40.089592,
                display_description=,
                due=2025-08-16 23:59:59,
                external_id=c0a7f183f32e42b9a4cfc5ee997a3455,
                id=4875989783937024,
                installment_id=6381497086902272,
                invoice_id=5192316503457792,
                status=failed,
                subscription_id=4871746087813120,
                tags=[],
                updated=2025-08-17 00:00:07.852905
        ),
        type=failed
)
```

### Get an Invoice Pull Request Log

`GET /v2/invoice-pull-request/log/:id`

Get a single invoice pull request log by its id.

**Request**

```python
import starkbank

logs = starkbank.invoicepullrequest.log.get("5439643239579648")

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

**Response**

```python
Log(
        created=2025-08-17 00:00:05.640702,
        errors=[],
        id=5439643239579648,
        request=InvoicePullRequest(
                attempt_type=default,
                created=2025-08-14 18:23:40.089592,
                display_description=,
                due=2025-08-16 23:59:59,
                external_id=c0a7f183f32e42b9a4cfc5ee997a3455,
                id=4875989783937024,
                installment_id=6381497086902272,
                invoice_id=5192316503457792,
                status=failed,
                subscription_id=4871746087813120,
                tags=[],
                updated=2025-08-17 00:00:07.852905
        ),
        type=failed
)
```

# Card Receivables

## Merchant Session

The Merchant Session resource can be created by a merchant and used by the card holder in order to collect their card data without having to handle it on the merchant's side.

The card data can be sent directly from a browser or app to Stark Bank's API using the Merchant Session Purchase route.

### The Merchant Session object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the merchant session. |
| `allowedFundingTypes` | LIST OF STRINGS | Funding types allowed for the purchase. Options: "credit", "debit". |
| `allowedInstallments` | LIST OF OBJECTS | Installment configurations allowed for the purchase. |
| `allowedIps` | LIST OF STRINGS | IP addresses allowed to create a purchase. |
| `challengeMode` | STRING | Holder verification mode. Options: "enabled", "disabled". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `expiration` | INTEGER | Time in seconds until the session expires. |
| `status` | STRING | Current session status. Options: "active", "expired", "success". |
| `tags` | LIST OF STRINGS | Tags associated with the session. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `uuid` | STRING | Unique UUID for the session. |

### Create Merchant Sessions

`POST /v2/merchant-session`

This route allows the merchant to create a session that can be used by the card holder's application to create a new purchase.

The UUID parameter returned by the session should be used to create a Merchant Session Purchase.

**Request**

```python
import starkbank
from starkbank.merchantsession import AllowedInstallment

allowed_installments = [
    AllowedInstallment(total_amount=5000, count=1),
    AllowedInstallment(total_amount=5500, count=2)
]

merchant_session = starkbank.MerchantSession(
    allowed_funding_types=["debit", "credit"],
    allowed_installments=allowed_installments,
    expiration=3600,
    challenge_mode="disabled",
    tags=["session_123"]
)

print(starkbank.merchantsession.create(merchant_session))
```

**Response**

```python
MerchantSession(
    allowed_funding_types=['debit', 'credit'],
    allowed_installments=[
        AllowedInstallment(
            count=1,
            total_amount=5000
        ),
        AllowedInstallment(
            count=2,
            total_amount=5500
        )
    ],
    allowed_ips=[],
    challenge_mode=disabled,
    created=2025-02-20 19:34:45.818681,
    expiration=3600,
    id=4932221869752320,
    status=created,
    tags=['session_123'],
    updated=2025-02-20 19:34:45.827862,
    uuid=cc80706d85c5438b9fbe02085daf5315
)
```

### Create Merchant Session Purchase

`POST /v2/merchant-session/:uuid/purchase`

This route can be used to create a Merchant Purchase directly from the payer's client application.

The UUID of a Merchant Session that was previously created by the merchant is necessary to access this route.

**Request**

```python
import starkbank

merchant_purchase = starkbank.merchantsession.purchase(
    uuid= "cc80706d85c5438b9fbe02085daf5315",
    purchase= starkbank.merchantsession.Purchase(
        amount=5500,
        installment_count=2,
        holder_name="Rhaenyra Targaryen",
        holder_email="rhaenyra.targaryen@gmail.com",
        holder_phone="11985923451",
        funding_type="credit",
        billing_country_code="BRA",
        billing_city="Sao Paulo",
        billing_state_code="SP",
        billing_street_line_1="Rua Casterly Rock, 2000",
        billing_street_line_2="1 andar",
        billing_zip_code="01450-000",
        metadata={
            "userAgent": "Mozilla",
            "userIp": "255.255.255.255",
            "language": "pt-BR",
            "timezoneOffset": 3,
            "extraData": "extraData"
        },
        card_expiration="2035-01",
        card_number="5277696455399733",
        card_security_code="123",

    )
)
```

**Response**

```python
Purchase(
    amount=5500,
    billing_city=Sao Paulo,
    billing_country_code=BRA,
    billing_state_code=SP,
    billing_street_line_1=Rua Casterly Rock, 2000,
    billing_street_line_2=1 andar,
    billing_zip_code=01450-000,
    card_ending=9733,
    card_id=,
    challenge_mode=disabled,
    challenge_url=,
    created=2025-02-20 20:17:48.562909,
    currency_code=BRL,
    end_to_end_id=6a361ae0-f977-43b7-9970-4f59d58cd126,
    fee=0,
    funding_type=credit,
    holder_email=rhaenyra.targaryen@gmail.com,
    holder_name=Rhaenyra Targaryen,
    holder_phone=11985923451,
    id=5167847869251584,
    installment_count=2,
    metadata={
        'extraData': 'extraData',
        'language': 'pt-BR',
        'timezoneOffset': 3,
        'userAgent': 'Mozilla',
        'userIp': '255.255.255.255'},
    network=mastercard,
    source=merchant-session/4913745390206976,
    status=denied,
    tags=['session_123'],
    updated=2025-02-20 20:17:49.620024
)
```

### List Merchant Sessions

`GET /v2/merchant-session`

Get a list of merchant sessions in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

merchant_sessions = starkbank.merchantsession.query(after= "2025-01-01", before= "2025-03-01")

for merchant_session in merchant_sessions:
    print(merchant_session)
```

**Response**

```python
MerchantSession(
    allowed_funding_types=['credit', 'debit'],
    allowed_installments=[
        AllowedInstallment(
            count=1,
            total_amount=5000
        ),
        AllowedInstallment(
            count=2,
            total_amount=5500
        )
    ],
    allowed_ips=[],
    challenge_mode=enabled,
    created=2025-01-03 15:47:08.879093,
    expiration=3600,
    id=5739291523153920,
    status=success,
    tags=[],
    updated=2025-01-03 15:47:41.826546,
    uuid=281319fce4f149acb71044e2f305953d
)
```

### Get a Merchant Session

`GET /v2/merchant-session/:id`

Retrieve detailed information about a specific session by its id.

**Request**

```python
import starkbank

merchant_session = starkbank.merchantsession.get('5739291523153920')
print(merchant_session)
```

**Response**

```python
MerchantSession(
    allowed_funding_types=['credit', 'debit'],
    allowedInstallments=[
        AllowedInstallment(
            count=1,
            total_amount=5000
        ),
        AllowedInstallment(
            count=2,
            total_amount=5500
        )
    ],
    allowed_ips=[],
    challenge_mode=enabled,
    created=2025-01-03 15:47:08.879093,
    expiration=3600,
    id=5739291523153920,
    status=success,
    tags=[],
    updated=2025-01-03 15:47:41.826546,
    uuid=281319fce4f149acb71044e2f305953d
)
```

### List Merchant Session Logs

`GET /v2/merchant-session/log`

Get a paged list of merchant session logs.

A log tracks a change in the session entity according to its life cycle.

**Request**

```python
import starkbank

merchant_session_logs = starkbank.merchantsession.log.query(limit=1)
for log in merchant_session_logs:
    print(log)
```

**Response**

```python
Log(
	created=2025-02-21 22:30:11.107220,
	errors=[],
	id=6206771064471552,
	session=MerchantSession(
        allowed_funding_types=['debit', 'credit'],
        allowed_installments=[
            AllowedInstallment(
                count=1,
                total_amount=5000
            ),
            AllowedInstallment(
                count=2,
                total_amount=5500
            )
        ],
		allowed_ips=[],
		challenge_mode=enabled,
		created=2025-02-21 22:30:11.080441,
		expiration=3600,
		id=5080871157628928,
		status=created,
		tags=['stark', 'suit'],
		updated=2025-02-21 22:30:11.233107,
		uuid=ffc2e83962f14424833b96776dcaed83
	),
	type=created
)
```

### Get a Merchant Session Log

`GET /v2/merchant-session/log/:id`

Get a single merchant session log by its id.

**Request**

```python
import starkbank

log = starkbank.merchantsession.log.get('5950134772826112')
print(log)
```

**Response**

```python
Log(
	created=2025-02-21 22:30:11.107220,
	errors=[],
	id=6206771064471552,
	session=MerchantSession(
        allowed_funding_types=['debit', 'credit'],
        allowed_installments=[
            AllowedInstallment(
                count=1,
                total_amount=5000
            ),
            AllowedInstallment(
                count=2,
                total_amount=5500
            )
        ],
        allowed_ips=[],
        challenge_mode=disabled,
        created=2025-02-21 22:30:11.080441,
        expiration=3600,
        id=5080871157628928,
        status=created,
        tags=['stark', 'suit'],
        updated=2025-02-21 22:30:11.233107,
        uuid=ffc2e83962f14424833b96776dcaed83
	),
	type=created
)
```

## Merchant Purchase

The Merchant Purchase resource can be used to charge customers with credit or debit cards.

If a card hasn't been used before, a Merchant Session Purchase must be created and approved with that specific card before it can be used directly in a Merchant Purchase.

### The Merchant Purchase object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the merchant purchase. |
| `amount` | INTEGER | Amount in cents to be received. Example: 100 (R$1.00). |
| `cardEnding` | STRING | Last 4 digits of the card. |
| `cardId` | STRING | ID of the Merchant Card used for the purchase. |
| `challengeMode` | STRING | Holder verification mode. Options: "enabled", "disabled". |
| `challengeUrl` | STRING | URL for holder verification challenge. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `currencyCode` | STRING | Currency code of the purchase. |
| `endToEndId` | STRING | End-to-end ID of the purchase. |
| `fee` | INTEGER | Fee charged in cents. |
| `fundingType` | STRING | Funding type. Options: "credit", "debit". |
| `installmentCount` | INTEGER | Number of purchase installments. |
| `network` | STRING | Card network. |
| `source` | STRING | Source of the purchase. |
| `status` | STRING | Current purchase status. Options: "created", "approved", "denied", "confirmed", "paid", "pending", "canceled", "voided", "failed". |
| `tags` | LIST OF STRINGS | Tags associated with the purchase. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Merchant Purchase

`POST /v2/merchant-purchase`

This route is used to charge a card that has been previously saved.

Cards can only be used in this route once a previous purchase was approved through a Merchant Session Purchase.

**Request**

```python
import starkbank

merchant_purchase = starkbank.merchantpurchase.create(
    starkbank.MerchantPurchase(
        amount=10000,
        installment_count=5,
        holder_email="tywin.lannister@gmail.com",
        holder_phone="11985923451",
        funding_type="credit",
        billing_country_code="BRA",
        billing_city="Sao Paulo",
        billing_state_code="SP",
        billing_street_line_1="Rua Casterly Rock, 2000",
        billing_street_line_2="1 andar",
        billing_zip_code="01450-000",
        metadata={
            "userAgent": "userAgent",
            "userIp": "184.82.170.183",
            "language": "pt-BR",
            "timezoneOffset": 3,
            "extraData": "extraData"
        },
        card_id="6295415968235520"
    )
)

print(merchant_purchase)
```

**Response**

```python
MerchantPurchase(
    amount=10000,
    billing_city=Sao Paulo,
    billing_country_code=BRA,
    billing_state_code=SP,
    billing_street_line_1=Rua Casterly Rock, 2000,
    billing_street_line_2=1 andar,
    billing_zip_code=01450-000,
    card_ending=0007,
    card_id=6295415968235520,
    challenge_mode=enabled,
    challenge_url=https://sandbox.api.starkinfra.com/v2/acquiring-purchase/5700835795271680/challenge,
    created=2025-02-20 20:47:43.237974,
    currency_code=BRL,
    end_to_end_id=1087c2ba-6a07-4108-82f7-14156032af48,
    fee=0,
    funding_type=credit,
    holder_email=tywin.lannister@gmail.com,
    holder_name=Tywin Lannister,
    holder_phone=11985923451,
    id=5136275203948544,
    installment_count=5,
    metadata={
        'extraData': 'extraData',
        'language': 'pt-BR',
        'screenHeight': 500
        'screenWidth': 500,
        'timezoneOffset': 3,
        'userAgent': 'userAgent',
        'userIp': '184.82.170.183'
    },
    network=mastercard,
    source=merchant-card/6295415968235520,
    status=pending,
    tags=[],
    updated=2025-02-20 20:47:45.176881
)
```

### Update a Merchant Purchase

`PATCH /v2/merchant-purchase/:id`

Update a single purchase. If the purchase is currently approved, you can only update the status to canceled and set the amount to 0. This action cancels the authorization. If the purchase is currently confirmed, you can update the status to reversed and adjust the amount to a lower value. This action debits the difference and reverses the purchase, partially or totally. If the purchase is partially reversed, its status will remain confirmed. However, if the purchase is fully reversed, its status will be updated to voided.

**Request**

```python
import starkbank

merchant_purchase = starkbank.merchantpurchase.update(id="5752391039188992", status="canceled", amount=0)

print(merchant_purchase)
```

**Response**

```python
MerchantPurchase(
    amount=0,
    billing_city=,
    billing_country_code=,
    billing_state_code=,
    billing_street_line_1=,
    billing_street_line_2=,
    billing_zip_code=,
    cardId="6675871284854784",
    card_ending="0005",
    challenge_mode="disabled",
    challenge_url="",
    created="2025-01-30T18:52:55.315590+00:00",
    currency_code="BRL",
    end_to_end_id="33c022ec-2c54-46e5-b20b-eb10edfaf021",
    fee=160,
    funding_type="credit",
    holder_email=,
    holder_name=Margaery Tyrell,
    holder_phone=,
    id="5752391039188992",
    installment_count=3,
    metadata={},
    network="visa",
    source="merchant-card/6675871284854784",
    status="confirmed",
    tags=["purchase_1234"],
    updated="2025-01-30T20:44:06.470183+00:00"
)
```

### List Merchant Purchases

`GET /v2/merchant-purchase`

Get a list of merchant purchases in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

merchantpurchases = starkbank.merchantpurchase.query(limit=1, tags=["order/123"], status="approved")

for merchantpurchase in merchantpurchases:
    print(merchantpurchase)
```

**Response**

```python
MerchantPurchase(
    amount=10000,
    billing_city=Sao Paulo,
    billing_country_code=BRA,
    billing_state_code=SP,
    billing_street_line_1=Rua Casterly Rock, 2000,
    billing_street_line_2=1 andar,
    billing_zip_code=01450-000,
    card_ending=0007,
    id=6295415968235520,
    challenge_mode=enabled,
    challenge_url=,
    created=2025-02-20 20:47:43.237974,
    currency_code=BRL,
    end_to_end_id=1087c2ba-6a07-4108-82f7-14156032af48,
    fee=0,
    funding_type=credit,
    holder_email=tywin.lannister@gmail.com,
    holder_name=Margaery Tyrell,
    holder_phone=11985923451,
    id=5136275203948544,
    installment_count=5,
    metadata={
        'extraData': 'extraData',
        'language': 'pt-BR',
        'screenHeight': 500,
        'screenWidth': 500,
        'timezoneOffset': 3,
        'userAgent': 'userAgent',
        'userIp': '184.82.170.183'
    },
    network=mastercard,
    source=merchant-card/6295415968235520,
    status=pending,
    tags=[],
    updated=2025-02-20 20:47:46.491252
)
```

### Get a Merchant Purchase

`GET /v2/merchant-purchase/:id`

Retrieve detailed information about a specific purchase by its id.

**Request**

```python
import starkbank

merchant_purchase = starkbank.merchantpurchase.get('5136275203948544')

print(merchant_purchase)
```

**Response**

```python
MerchantPurchase(
    amount=10000,
    billing_city=Sao Paulo,
    billing_country_code=BRA,
    billing_state_code=SP,
    billing_street_line_1=Rua Casterly Rock, 2000,
    billing_street_line_2=1 andar,
    billing_zip_code=01450-000,
    card_ending=0007,
    card_id=6295415968235520,
    challenge_mode=enabled,
    challenge_url=,
    created=2025-02-20 20:47:43.237974,
    currency_code=BRL,
    end_to_end_id=1087c2ba-6a07-4108-82f7-14156032af48,
    fee=0,
    funding_type=credit,
    holder_email=tywin.lannister@gmail.com,
    holder_name=Margaery Tyrell,
    holder_phone=11985923451,
    id=5136275203948544,
    installment_count=5,
    metadata={
        'extraData': 'extraData',
        'language': 'pt-BR',
        'screenHeight': 500,
        'screenWidth': 500,
        'timezoneOffset': 3,
        'userAgent': 'userAgent',
        'userIp': '184.82.170.183'
    },
    network=mastercard,
    source=merchant-card/6295415968235520,
    status=pending,
    tags=[],
    updated=2025-02-20 20:47:46.491252
)
```

### List Merchant Purchase Logs

`GET /v2/merchant-purchase/log`

Get a paged list of merchant purchase logs.

A log tracks a change in the purchase entity according to its life cycle.

**Request**

```python
import starkbank

merchant_purchase_logs = starkbank.merchantpurchase.log.query(limit=1)

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

**Response**

```python
Log(    
    created=2025-02-20 20:51:47.554421,
    errors=[],
    id=4529865642475520,
    purchase=MerchantPurchase(
        amount=180,
        billing_city=São Paulo,
        billing_country_code=BRA,
        billing_state_code=SP,
        billing_street_line_1=Rua do Holder Name, 123,
        billing_street_line_2=,
        billing_zip_code=11111-111,
        card_ending=9733,
        card_expiration=None,
        card_id=,
        card_number=None,
        card_security_code=None,
        challenge_mode=disabled,
        challenge_url=,
        created=2024-07-16 19:42:25.059361,
        currency_code=BRL,
        end_to_end_id=ee77111c-644c-4a67-a4cf-6cbc9da15ceb,
        fee=0,
        funding_type=credit,
        holder_email=holdeName@email.com,
        holder_name=Holder Name,
        holder_phone=11111111111,
        id=4512566093021184,
        installment_count=12,
        metadata={},
        network=mastercard,
        source=merchant-session/5375106121465856,
        status=created,
        tags=['yourtags'],
        updated=2024-07-16 19:42:26.878894
    ),
    type=canceling
)
```

### Get a Merchant Purchase Log

`GET /v2/merchant-purchase/log/:id`

Get a single merchant purchase log by its id.

**Request**

```python
import starkbank

log = starkbank.merchantpurchase.log.get('4529865642475520')

print(log)
```

**Response**

```python
Log(
    created=2025-02-20 20:51:47.554421,
    errors=[],
    id=4529865642475520,
    purchase=MerchantPurchase(
        amount=180,
        billing_city=São Paulo,
        billing_country_code=BRA,
        billing_state_code=SP,
        billing_street_line_1=Rua do Holder Name, 123,
        billing_street_line_2=,
        billing_zip_code=11111-111,
        card_ending=9733,
        card_id=,
        challenge_mode=disabled,
        challenge_url=,
        created=2024-07-16 19:42:25.059361,
        currency_code=BRL,
        end_to_end_id=ee77111c-644c-4a67-a4cf-6cbc9da15ceb,
        fee=0,
        funding_type=credit,
        holder_email=holdeName@email.com,
        holder_name=Holder Name,
        holder_phone=11111111111,
        id=4512566093021184,
        installment_count=12,
        metadata={},
        network=mastercard,
        source=merchant-session/5375106121465856,
        status=created,
        tags=['yourtags'],
        updated=2024-07-16 19:42:26.878894
    ),
    type=canceling
)
```

## Merchant Card

The Merchant Card resource stores information about cards used in approved purchases.

These cards can be used in new purchases without the need to create a new session.

### The Merchant Card object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the merchant card. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `ending` | STRING | Last 4 digits of the card number. |
| `expiration` | STRING | Card expiration date. Example: "2025-06". |
| `fundingType` | STRING | Funding type. Options: "credit", "debit". |
| `holderName` | STRING | Name of the card holder. |
| `network` | STRING | Card network. |
| `status` | STRING | Current card status. Options: "active", "expired", "canceled", "blocked". |
| `tags` | LIST OF STRINGS | Tags associated with the card. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### List Merchant Cards

`GET /v2/merchant-card`

Get a list of merchant cards in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

merchant_cards = starkbank.merchantcard.query(limit=1)

for merchant_card in merchant_cards:
    print(merchant_card)
```

**Response**

```python
MerchantCard(
    created=2025-02-18 18:39:28.597425,
    ending=0007,
    expiration=2045-02-01 02:59:59.999999,
    funding_type=credit,
    holder_name=Margaery Tyrell,
    id=6295415968235520,
    network=mastercard,
    status=active,
    tags=[],
    updated=2025-02-19 20:08:50.497358
)
```

### Get a Merchant Card

`GET /v2/merchant-card/:id`

Retrieve detailed information about a specific card by its id.

**Request**

```python
import starkbank

merchant_card = starkbank.merchantcard.get('6295415968235520')

print(merchant_card)
```

**Response**

```python
MerchantCard(
    created=2025-02-18 18:39:28.597425,
    ending=0007,
    expiration=2045-02-01 02:59:59.999999,
    funding_type=credit,
    holder_name=Margaery Tyrell,
    id=6295415968235520,
    network=mastercard,
    status=active,
    tags=[],
    updated=2025-02-19 20:08:50.497358
)
```

### List Merchant Card Logs

`GET /v2/merchant-card/log`

Get a paged list of merchant card logs.

A log tracks a change in the card entity according to its lifecycle.

**Request**

```python
import starkbank

logs = starkbank.merchantcard.log.query(limit=1)

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

**Response**

```python
Log(
    created=2025-02-18 18:39:28.612480,
    errors=[],
    id=4888041084682240,
    card=MerchantCard(
        created=2025-02-18 18:39:28.597425,
        ending=0007,
        expiration=2045-02-01 02:59:59.999999,
        funding_type=credit,
        holder_name=Margaery Tyrell,
        id=6295415968235520,
        network=mastercard,
        status=active,
        tags=[],
        updated=2025-02-19 20:08:50.497358
    ),
    type=active,
)
```

### Get a Merchant Card Log

`GET /v2/merchant-card/log/:id`

Get a single merchant card log by its id.

**Request**

```python
import starkbank

merchant_card_log = starkbank.merchantcard.log.get('4888041084682240')

print(merchant_card_log)
```

**Response**

```python
Log(
    created=2025-02-18 18:39:28.612480,
    errors=[],
    id=4888041084682240,
    card=MerchantCard(
        created=2025-02-18 18:39:28.597425,
        ending=0007,
        expiration=2045-02-01 02:59:59.999999,
        funding_type=credit,
        holder_name=Margaery Tyrell,
        id=6295415968235520,
        network=mastercard,
        status=active,
        tags=[],
        updated=2025-02-19 20:08:50.497358
    ),
    type=active,
    updated=None
)
```

## Merchant Installment

Merchant Installments are created for every installment in a purchase.

These resources will track its own due payment date and settlement lifecycle.

### The Merchant Installment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the merchant installment. |
| `amount` | INTEGER | Installment amount in cents. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `due` | STRING | Expected settlement date. Example: "2020-04-23T23:00:00.000000+00:00". |
| `fee` | INTEGER | Fee charged in cents. |
| `fundingType` | STRING | Funding type. Options: "credit", "debit". |
| `network` | STRING | Card network. |
| `purchaseId` | STRING | ID of the Merchant Purchase linked to the installment. |
| `status` | STRING | Current installment status. Options: "created", "paid", "canceled", "voided". |
| `tags` | LIST OF STRINGS | Tags associated with the installment. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the installment. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### List Merchant Installments

`GET /v2/merchant-installment`

Get a list of merchant installments in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

merchant_installments = starkbank.merchantinstallment.query(limit=1)

for merchant_installment in merchant_installments:
    print(merchant_installment)
```

**Response**

```python
MerchantInstallment(
    amount=1000,
    created=2025-02-20 20:01:58.529828,
    due=2025-05-21 03:00:00.529828,
    fee=16,
    funding_type=credit,
    id=4848075206033408,
    network=mastercard,
    purchase_id=5559970598748160,
    status=paid,
    tags=[],
    transaction_ids=["38502321313064121177062848528552"],
    updated=2025-02-20 20:02:02.185613
)
```

### Get a Merchant Installment

`GET /v2/merchant-installment/:id`

Retrieve detailed information about a specific installment by its id.

**Request**

```python
import starkbank

merchant_installment = starkbank.merchantinstallment.get('4848075206033408')

print(merchant_installment)
```

**Response**

```python
MerchantInstallment(
        amount=1000,
        created=2025-02-20 20:01:58.529828,
        due=2025-05-21 03:00:00.529828,
        fee=16,
        funding_type=credit,
        id=4848075206033408,
        network=mastercard,
        purchase_id=5559970598748160,
        status=paid,
        tags=[],
        transaction_ids=["38502321313064121177062848528552"],
        updated=2025-02-20 20:02:02.185613
)
```

### List Merchant Installment Logs

`GET /v2/merchant-installment/log`

Get a paged list of merchant installment logs.

A log tracks a change in the installment entity according to its life cycle.

**Request**

```python
import starkbank

merchant_installment_logs = starkbank.merchantinstallment.log.query(limit=1)

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

**Response**

```python
Log(
    created=2025-02-20 21:05:03.520701,
    errors=[],
    id=6218715502739456,
    installment=MerchantInstallment(
        amount=5000,
        created=2025-02-20 21:05:03.515855,
        due=2025-03-21 03:00:00,
        fee=60,
        funding_type=credit,
        id=5092815595896832,
        network=mastercard,
        purchase_id=6332003586670592,
        status=created,
        tags=[],
        transaction_ids=[],
        updated=2025-02-20 21:05:04.705022
    ),
    type=created,
    updated=2025-02-20 21:05:04.720418
)
```

### Get a Merchant Installment Log

`GET /v2/merchant-installment/log/:id`

Get a single merchant installment log by its id.

**Request**

```python
import starkbank

log = starkbank.merchantinstallment.log.get('6218715502739456')

print(log)
```

**Response**

```python
Log(
    created=2025-02-20 21:05:03.520701,
    errors=[],
    id=6218715502739456,
    installment=MerchantInstallment(
        amount=5000,
        created=2025-02-20 21:05:03.515855,
        due=2025-03-21 03:00:00,
        fee=60,
        funding_type=credit,
        id=5092815595896832,
        network=mastercard,
        purchase_id=6332003586670592,
        status=created,
        tags=[],
        transaction_ids=[],
        updated=2025-02-20 21:05:04.705022
    ),
    type=created,
    updated=2025-02-20 21:05:04.720418
)
```

# Bill Payments

## Transfer

Transfers are used to send money to any bank account in Brazil using the Ted or Pix systems.

Here we will show you how to create and manage them.

### The Transfer object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the transfer. |
| `accountNumber` | STRING | Receiver bank account number. |
| `accountType` | STRING | Receiver bank account type. Options: "checking", "savings", "salary", "payment". |
| `amount` | INTEGER | Amount in cents to be transferred. Example: 100 (R$1.00). |
| `bankCode` | STRING | Receiver bank code or ISPB. |
| `branchCode` | STRING | Receiver bank account branch. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `description` | STRING | Text displayed in the bank statement. |
| `displayDescription` | STRING | Description shown in the receiver bank interface. |
| `externalId` | STRING | Unique external ID to prevent duplicates. |
| `fee` | INTEGER | Fee charged in cents. |
| `name` | STRING | Receiver full name. |
| `rules` | LIST OF OBJECTS | List of rule objects with key and value. |
| `scheduled` | STRING | Scheduled payment datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `status` | STRING | Current transfer status. Options: "created", "processing", "confirmed", "success", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the transfer. |
| `taxId` | STRING | Receiver CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the transfer. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Transfers

`POST /v2/transfer`

This route is used to send your transfers to their receivers.

You can create up to 100 transfers in a single request.

**Request**

```python
import starkbank

transfers = starkbank.transfer.create([
    starkbank.Transfer(
        amount=1000000,
        tax_id="123.456.789-10",
        name="Daenerys Targaryen Stormborn",
        bank_code="20018183",
        branch_code="2201",
        account_number="76543-8",
        external_id="my-external-id",
        scheduled="2020-08-14",
        tags=["daenerys", "invoice/1234"],
        rules=[
            starkbank.transfer.Rule(
                key="resendingLimit",
                value=5
            )
        ]
    )
])

for transfer in transfers:
    print(transfer)
```

**Response**

```python
Transfer(
    account_number=76543-8,
    account_type=checking,
    amount=1000000,
    bank_code=20018183,
    branch_code=2201,
    created=2020-02-06 16:22:24.664134,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    external_id=my-external-id,
    fee=0,
    id=5412038532661248,
    name=Daenerys Targaryen Stormborn,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    scheduled=2020-08-14 10:00:00,
    status=created,
    tags=['daenerys', 'invoice/1234'],
    tax_id=123.456.789-10,
    transaction_ids=[],
    updated=2020-02-06 16:22:24.664148
)
```

### List Transfers

`GET /v2/transfer`

Here you can list and filter all transfers you have made. We return it paged.

**Request**

```python
import starkbank

transfers = starkbank.transfer.query(
    after="2020-04-01",
    before="2020-04-30",
)

for transfer in transfers:
    print(transfer)
```

**Response**

```python
Transfer(
    account_number=76543-8,
    account_type=checking,
    amount=1000000,
    bank_code=665,
    branch_code=2201,
    created=2020-04-24 17:49:10.225810,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    external_id=my-external-id,
    fee=200,
    id=5950134772826112,
    name=Daenerys Targaryen Stormborn,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    status=processing,
    scheduled=2020-08-14 11:00:00,
    tags=['daenerys', 'invoice/1234'],
    tax_id=594.739.480-42,
    transaction_ids=['5991715760504832'],
    updated=2020-04-24 17:49:10.225810
)
```

### Get a Transfer

`GET /v2/transfer/:id`

Get a single transfer by its id.

**Request**

```python
import starkbank

transfer = starkbank.transfer.get("5950134772826112")

print(transfer)
```

**Response**

```python
Transfer(
    account_number=76543-8,
    account_type=checking,
    amount=1000000,
    bank_code=665,
    branch_code=2201,
    created=2020-04-24 17:49:10.225810,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    external_id=my-external-id,
    fee=200,
    id=5950134772826112,
    name=Daenerys Targaryen Stormborn,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    status=processing,
    scheduled=2020-08-14 11:00:00,
    tags=['daenerys', 'invoice/1234'],
    tax_id=594.739.480-42,
    transaction_ids=['5991715760504832'],
    updated=2020-04-24 17:49:10.225810
)
```

### Cancel a scheduled Transfer

`DELETE /v2/transfer/:id`

Cancel a scheduled transfer. You can only cancel transfers before they start being processed.

NOTE:Canceled transfers will still appear in your queries.

**Request**

```python
import starkbank

transfer = starkbank.transfer.delete("6693962735681536")

print(transfer)
```

**Response**

```python
Transfer(
    account_number=76543-8,
    account_type=checking,
    amount=100000000,
    bank_code=665,
    branch_code=2201,
    created=2020-04-24 17:49:10.225810,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    external_id=my-external-id,
    fee=200,
    id=6693962735681536,
    name=Daenerys Targaryen Stormborn,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    status=canceled,
    scheduled=2020-08-14 11:00:00,
    tags=['daenerys', 'invoice/1234'],
    tax_id=594.739.480-42,
    transaction_ids=['5991715760504832'],
    updated=2020-04-24 17:49:10.225810
)
```

### Get a Transfer PDF

`GET /v2/transfer/:id/pdf`

Get a PDF from a single transfer by its id.

**Request**

```python
import starkbank

pdf = starkbank.transfer.pdf("5646210941583360")

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

### List Transfer Logs

`GET /v2/transfer/log`

Get a paged list of all transfer logs. A log tracks a change in the transfer entity according to its life cycle.

**Request**

```python
import starkbank

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

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

**Response**

```python
Log(
    id=5662318377566208,
    created=2020-04-24 17:49:09.348444,
    errors=[],
    type=sending,
    transfer=Transfer(
        id=5950134772826112,
        account_number=76543-8,
        account_type=checking,
        amount=100000000,
        bank_code=665,
        branch_code=2201,
        created=2020-04-24 17:49:08.748893,
        description=Daenerys Targaryen Stormborn (594.739.480-42),
        external_id=my-external-id,
        fee=200,
        name=Daenerys Targaryen Stormborn,
        rules=[
            Rule(
                key=resendingLimit,
                value=5
            )
        ],
        status=processing,
        scheduled=2020-08-14 11:00:00,
        tags=['daenerys', 'invoice/1234'],
        tax_id=594.739.480-42,
        transaction_ids=['5991715760504832'],
        updated=2020-04-24 17:49:10.259578
    )
)
```

### Get a Transfer Log

`GET /v2/transfer/log/:id`

Get a single transfer log by its id.

**Request**

```python
import starkbank

log = starkbank.transfer.log.get("5662318377566208")

print(log)
```

**Response**

```python
Log(
    id=5662318377566208,
    created=2020-04-24 17:49:09.348444,
    errors=[],
    type=sending,
    transfer=Transfer(
        id=5950134772826112,
        account_number=76543-8,
        account_type=checking,
        amount=100000000,
        bank_code=665,
        branch_code=2201,
        created=2020-04-24 17:49:08.748893,
        description=Daenerys Targaryen Stormborn (594.739.480-42),
        external_id=my-external-id,
        fee=200,
        name=Daenerys Targaryen Stormborn,
        rules=[
            Rule(
                key=resendingLimit,
                value=5
            )
        ],
        status=processing,
        scheduled=2020-08-14 11:00:00,
        tags=['daenerys', 'invoice/1234'],
        tax_id=594.739.480-42,
        transaction_ids=['5991715760504832'],
        updated=2020-04-24 17:49:10.259578
    )
)
```

## Brcode Payment

Here we will teach you how to create and manage brcode payments.

### The Brcode Payment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the brcode payment. |
| `amount` | INTEGER | Payment amount in cents. |
| `brcode` | STRING | Brcode 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. |
| `name` | STRING | Receiver full name. |
| `rules` | LIST OF OBJECTS | List of rule objects with key and value. |
| `scheduled` | STRING | Scheduled payment datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `status` | STRING | Current payment status. Options: "created", "processing", "confirmed", "success", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the brcode payment. |
| `taxId` | STRING | Receiver CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the payment. |
| `type` | STRING | Type of the brcode payment. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Brcode Payments

`POST /v2/brcode-payment`

Use this route to pay registered brcodes generated at Stark Bank or at other financial institutions using the available balance in your Stark Bank account.

NOTE:Initially, the brcode entity amount will be zero because the brcode is processed asynchronously.

**Request**

```python
import starkbank

payments = starkbank.brcodepayment.create([
    starkbank.BrcodePayment(
        brcode="00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF",
        tax_id="012.345.678-90",
        scheduled="2021-01-13",
        description="this will be fast",
        tags=["pix", "qrcode"],
        rules=[
            starkbank.brcodepayment.Rule(key="resendingLimit", value=5)
        ]
    )
])

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

**Response**

```python
BrcodePayment(
    amount=0,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2021-01-03 18:36:18.574799,
    description=this will be fast,
    fee=0,
    id=5717797661310976,
    name=None,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    scheduled=2021-01-13 10:00:00,
    status=creating,
    tags=['pix', 'qrcode'],
    tax_id=***.345.678-**,
    transaction_ids=[],
    type=dynamic,
    updated=2021-01-03 18:36:18.574815
)
```

### List Brcode Payments

`GET /v2/brcode-payment`

Get a list of non-deleted brcodes in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

payments = starkbank.brcodepayment.query(
    after="2021-01-01",
    before="2021-01-30"
)

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

**Response**

```python
BrcodePayment(
    amount=0,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2021-01-03 18:36:18.574799,
    description=this will be fast,
    fee=0,
    id=5717797661310976,
    name=None,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    scheduled=2021-01-13 10:00:00,
    status=creating,
    tags=['pix', 'qrcode'],
    tax_id=***.345.678-**,
    transaction_ids=[],
    type=dynamic,
    updated=2021-01-03 18:36:18.574815
)
```

### Get a Brcode Payment

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

Get a single brcode by its id.

**Request**

```python
import starkbank

payment = starkbank.brcodepayment.get("5717797661310976")

print(payment)
```

**Response**

```python
BrcodePayment(
    amount=0,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2021-01-03 18:36:18.574799,
    description=this will be fast,
    fee=0,
    id=5717797661310976,
    name=None,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    scheduled=2021-01-13 10:00:00,
    status=creating,
    tags=['pix', 'qrcode'],
    tax_id=***.345.678-**,
    transaction_ids=[],
    type=dynamic,
    updated=2021-01-03 18:36:18.574815
)
```

### Update a Brcode Payment

`PATCH /v2/brcode-payment/:id`

Update a single brcode payment, if it hasn't been paid yet.

**Request**

```python
import starkbank

payment = starkbank.brcodepayment.update("5717797661310976", status="canceled")

print(payment)
```

**Response**

```python
BrcodePayment(
    amount=0,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2021-01-03 18:36:18.574799,
    description=this will be fast,
    fee=0,
    id=5717797661310976,
    name=None,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    scheduled=2021-01-13 10:00:00,
    status=canceled,
    tags=['pix', 'qrcode'],
    tax_id=***.345.678-**,
    transaction_ids=[],
    type=dynamic,
    updated=2021-01-03 18:36:18.574815
)
```

### Get a Brcode Payment PDF

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

Get a brcode payment PDF receipt. You can only get a receipt for payments whose status are either success, processing or created.

**Request**

```python
import starkbank

pdf = starkbank.brcodepayment.pdf("5717797661310976")

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

### List Brcode Payment Logs

`GET /v2/brcode-payment/log`

Get a paged list of all brcode payment logs. A log tracks a change in the payment entity according to its life cycle.

**Request**

```python
import starkbank

logs = starkbank.brcodepayment.log.query(
    after="2021-01-01",
    before="2021-01-30",
    payment_ids=["5717797661310976"]
)

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

**Response**

```python
Log(
    created=2021-01-03 18:36:18.966033,
    errors=[],
    id=5172860540682240,
    payment=BrcodePayment(
        amount=0,
        brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
        created=2021-01-03 18:36:18.574799,
        description=this will be fast,
        fee=0,
        id=5717797661310976,
        name=None,
        rules=[
            Rule(
                key=resendingLimit,
                value=5
            )
        ],
        scheduled=2021-01-13 10:00:00,
        status=canceled,
        tags=['pix', 'qrcode'],
        tax_id=***.345.678-**,
        transaction_ids=[],
        type=dynamic,
        updated=2021-01-03 18:36:18.574815
    ),
    type=failed
)
```

### Get a Brcode Payment Log

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

Get a single brcode payment log by its id.

**Request**

```python
import starkbank

log = starkbank.brcodepayment.log.get("5172860540682240")

print(log)
```

**Response**

```python
Log(
    created=2021-01-03 18:36:18.966033,
    errors=[],
    id=5172860540682240,
    payment=BrcodePayment(
        amount=0,
        brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
        created=2021-01-03 18:36:18.574799,
        description=this will be fast,
        fee=0,
        id=5717797661310976,
        name=None,
        rules=[
            Rule(
                key=resendingLimit,
                value=5
            )
        ],
        scheduled=2021-01-13 10:00:00,
        status=canceled,
        tags=['pix', 'qrcode'],
        tax_id=***.345.678-**,
        transaction_ids=[],
        type=dynamic,
        updated=2021-01-03 18:36:18.574815
    ),
    type=failed
)
```

## Boleto Payment

Here we will teach you how to create and manage boleto payments.

### The Boleto Payment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the boleto 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 boleto payment. |
| `taxId` | STRING | Receiver CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the payment. |

### Create Boleto Payments

`POST /v2/boleto-payment`

Use this route to pay registered boletos generated at Stark Bank or at other financial institutions using the available balance in your Stark Bank account.

**Request**

```python
import starkbank

payments = starkbank.boletopayment.create([
    starkbank.BoletoPayment(
        line="34191.09107 05447.947309 71544.640008 8 84660000011631",
        tax_id="38.435.677/0001-25",
        tags=["little girl", "no one"],
        description="Payment for killing white walkers",
        scheduled="2020-04-25"
    )
])

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

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116311091005447947307154464000,
    created=2020-04-24 17:58:32.007153,
    description=Payment for killing white walkers,
    fee=0,
    id=6693962735681536,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-04-25 15:00:00,
    status=created,
    tags=['little girl', 'no one'],
    transaction_ids=[],
    tax_id=38.435.677/0001-25
)
```

### List Boleto Payments

`GET /v2/boleto-payment`

Get a list of non-deleted boleto payments in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

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

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

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116311091005447947307154464000,
    created=2020-04-24 17:58:32.007153,
    description=Payment for killing white walkers,
    fee=0,
    id=6693962735681536,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-04-25 15:00:00,
    status=created,
    tags=['little girl', 'no one'],
    transaction_ids=[],
    tax_id=38.435.677/0001-25
)
```

### Get a Boleto Payment

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

Get a single boleto payment by its id.

**Request**

```python
import starkbank

payment = starkbank.boletopayment.get("6693962735681536")

print(payment)
```

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116311091005447947307154464000,
    created=2020-04-24 17:58:32.007153,
    description=Payment for killing white walkers,
    fee=0,
    id=6693962735681536,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-04-25 15:00:00,
    status=created,
    tags=['little girl', 'no one'],
    transaction_ids=[],
    tax_id=38.435.677/0001-25
)
```

### Delete a Boleto Payment

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

Cancel a scheduled boleto payment. You can only cancel boleto payments before they start being processed.

NOTE:Payments that have already been processed can be deleted, but not cancelled.

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
BoletoPayment(
    amount=11631,
    bar_code=34198846600000116311091005447947307154464000,
    created=2020-04-24 17:58:32.007153,
    description=Payment for killing white walkers,
    fee=0,
    id=6693962735681536,
    line=34191.09107 05447.947309 71544.640008 8 84660000011631,
    scheduled=2020-04-25 15:00:00,
    status=canceled,
    tags=['little girl', 'no one'],
    transaction_ids=[],
    tax_id=38.435.677/0001-25
)
```

### Get a Boleto Payment PDF

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

Get a boleto payment PDF receipt. You can only get a receipt for payments whose status are either success, processing or created.

**Request**

```python
import starkbank

pdf = starkbank.boletopayment.pdf("6693962735681536")

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

### List Boleto Payment Logs

`GET /v2/boleto-payment/log`

Get a paged list of all boleto payment logs. A log tracks a change in the payment entity according to its life cycle.

**Request**

```python
import starkbank

logs = starkbank.boletopayment.log.query(
    payment_ids=["6693962735681536"]
)

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

**Response**

```python
Log(
    id=5260913007394816,
    created=2020-04-24 17:58:32.075347,
    errors=[],
    type=created,
    payment=BoletoPayment(
        amount=11631,
        bar_code=34198846600000116311091005447947307154464000,
        created=2020-04-24 17:58:32.007153,
        description=Payment for killing white walkers,
        fee=0,
        id=6693962735681536,
        line=34191.09107 05447.947309 71544.640008 8 84660000011631,
        scheduled=2020-04-25 15:00:00,
        status=created,
        tags=['little girl', 'no one'],
        transaction_ids=[],
        tax_id=38.435.677/0001-25
    )
)
```

### Get a Boleto Payment Log

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

Get a single boleto payment log by its id.

**Request**

```python
import starkbank

log = starkbank.boletopayment.log.get("5260913007394816")

print(log)
```

**Response**

```python
Log(
    id=5260913007394816,
    created=2020-04-24 17:58:32.075347,
    errors=[],
    type=created,
    payment=BoletoPayment(
        amount=11631,
        bar_code=34198846600000116311091005447947307154464000,
        created=2020-04-24 17:58:32.007153,
        description=Payment for killing white walkers,
        fee=0,
        id=6693962735681536,
        line=34191.09107 05447.947309 71544.640008 8 84660000011631,
        scheduled=2020-04-25 15:00:00,
        status=created,
        tags=['little girl', 'no one'],
        transaction_ids=[],
        tax_id=38.435.677/0001-25
    )
)
```

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

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

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

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

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

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

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

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

## Tax Payment

Here we will explain how to create and manage tax payments, such as ISS and DAS.

### The Tax Payment object

**Attributes**

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

### Create Tax Payments

`POST /v2/tax-payment`

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

**Request**

```python
import starkbank

payments = starkbank.taxpayment.create([
    starkbank.TaxPayment(
        bar_code="81660000005003657010074119002551100010601813",
        scheduled="2023-08-02",
        description="fix the road",
        tags=["take", "my", "money"],
    )
])

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

**Response**

```python
TaxPayment(
    amount=50036,
    bar_code=81660000005003657010074119002551100010601813,
    created=2023-01-24 18:03:18.662638,
    description=fix the road,
    fee=0,
    id=5186070702456832,
    line=81660000005 2 00365701007 4 41190025511 7 00010601813 8,
    scheduled=2023-08-02 11:00:00.000000,
    status=created,
    tags=["take", "my", "money"],
    transaction_ids=[],
    type=iss,
    updated=2023-01-24 18:03:18.000000
)
```

### List Tax Payments

`GET /v2/tax-payment`

Get a list of non-deleted tax payments in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

payments = starkbank.taxpayment.query(
    after="2023-01-01",
    before="2023-01-30"
)

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

**Response**

```python
TaxPayment(
    amount=50036,
    bar_code=81660000005003657010074119002551100010601813,
    created=2023-01-24 18:03:18.662638,
    description=fix the road,
    fee=0,
    id=5186070702456832,
    line=81660000005 2 00365701007 4 41190025511 7 00010601813 8,
    scheduled=2023-08-02 11:00:00.000000,
    status=created,
    tags=["take", "my", "money"],
    transaction_ids=[],
    type=iss,
    updated=2023-01-24 18:03:18.000000
)
```

### Get a Tax Payment

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

Get a single tax payment by its id.

**Request**

```python
import starkbank

payment = starkbank.taxpayment.get("5186070702456832")

print(payment)
```

**Response**

```python
TaxPayment(
    amount=50036,
    bar_code=81660000005003657010074119002551100010601813,
    created=2023-01-24 18:03:18.662638,
    description=fix the road,
    fee=0,
    id=5186070702456832,
    line=81660000005 2 00365701007 4 41190025511 7 00010601813 8,
    scheduled=2023-08-02 11:00:00,
    status=created,
    tags=["take", "my", "money"],
    transaction_ids=[],
    type=iss,
    updated=2023-01-24 18:03:18.662638
)
```

### Delete a Tax Payment

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

Cancel a scheduled tax payment. You can only cancel tax payments before they start being processed.

NOTE:Payments that have already been processed can be deleted, but not cancelled.

**Request**

```python
import starkbank

payment = starkbank.taxpayment.delete("5186070702456832")

print(payment)
```

**Response**

```python
TaxPayment(
    amount=50036,
    bar_code=81660000005003657010074119002551100010601813,
    created=2023-01-24 18:03:18.662638,
    description=fix the road,
    fee=0,
    id=5186070702456832,
    line=81660000005 2 00365701007 4 41190025511 7 00010601813 8,
    scheduled=2023-08-02 11:00:00.000000,
    status=canceled,
    tags=["take", "my", "money"],
    transaction_ids=[],
    type=iss,
    updated=2023-01-26 14:44:22.522334
)
```

### Get a Tax Payment PDF

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

Get a tax payment PDF receipt. You can only get a receipt for payments whose status are either success, processing or created.

**Request**

```python
import starkbank

pdf = starkbank.taxpayment.pdf("5186070702456832")

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

### List Tax Payment Logs

`GET /v2/tax-payment/log`

Get a paged list of all tax payment logs. A log tracks a change in the payment entity according to its life cycle.

**Request**

```python
import starkbank

logs = starkbank.taxpayment.log.query(
    payment_ids=["5133524998815744"]
)

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

**Response**

```python
Log(
    created=2023-01-18 16:49:06.080497,
    errors=[],
    id=5068165377687552,
    payment=TaxPayment(
        amount=8271,
        bar_code=85660000000827100640074119002551100010601813,
        created=2023-01-18 16:49:05.981612,
        description=paying taxes,
        fee=0,
        id=5133524998815744,
        line=85660000000 9 82710064007 3 41190025511 7 00010601813 8,
        scheduled=2023-01-20 11:00:00.000000,
        status=created,
        tags=['expensive'],
        transaction_ids=[],
        type=iss,
        updated=2023-01-20 15:00:01.494340
    ),
    type=created
)
```

### Get a Tax Payment Log

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

Get a single tax payment log by its id.

**Request**

```python
import starkbank

log = starkbank.taxpayment.log.get("5068165377687552")

print(log)
```

**Response**

```python
Log(
    created=2023-01-18 16:49:06.080497,
    errors=[],
    id=5068165377687552,
    payment=TaxPayment(
        amount=8271,
        bar_code=85660000000827100640074119002551100010601813,
        created=2023-01-18 16:49:05.981612,
        description=paying taxes,
        fee=0,
        id=5133524998815744,
        line=85660000000 9 82710064007 3 41190025511 7 00010601813 8,
        scheduled=2023-01-20 11:00:00,
        status=created,
        tags=['expensive'],
        transaction_ids=[],
        type=iss,
        updated=2023-01-20 15:00:01.494340
    ),
    type=created
)
```

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

**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=datetime(2021, 5, 12, 15, 23, 26, 689377),
        scheduled=datetime(2021, 3, 12, 15, 23, 26, 689377)
        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.

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

**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 Darf payments before they start being processed.

NOTE:Payments that have already been processed can be deleted, but not cancelled.

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

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

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

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

## Payment Preview

A Payment Preview is used to get information from multiple types of payment to confirm any information before actually paying. If the 'scheduled' parameter is not informed, today will be assumed as the intended payment date. Right now, the 'scheduled' parameter only has effect on BrcodePreviews.

This resource is able to preview the following types of payment: "brcode-payment", "boleto-payment", "utility-payment" and "tax-payment"

### The Payment Preview object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Main identification of the payment (BR Code, line, or bar code). |
| `scheduled` | STRING | Intended payment date. Example: "2020-03-10". |
| `type` | STRING | Payment type. Options: "brcode-payment", "boleto-payment", "utility-payment", "tax-payment". |

### Create a Payment Preview

`POST /v2/payment-preview`

Create a payment preview to get information from a payment.

**Request**

```python
import starkbank

previews = starkbank.paymentpreview.create([
    starkbank.PaymentPreview(
        id="00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540510.005802BR5908T'Challa6009Sao Paulo62090505123456304B14A",
        scheduled="2023-01-29"
    )
])

for preview in previews:
    print(preview)
```

**Response**

```python
PaymentPreview(
    id=00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540510.005802BR5908T'Challa6009Sao Paulo62090505123456304B14A,
    payment=BrcodePreview(
        account_type=savings,
        allow_change=False,
        amount=1000,
        bank_code=01705236,
        cash_amount=0,
        cashier_bank_code=,
        cashier_type=,
        description=Descrição para o pagador,
        discount_amount=0,
        fine_amount=0,
        interest_amount=0,
        key_id=35719950-ac93-4bab-8ad6-56d7fb63afd2,
        name=Humberto EI,
        nominal_amount=1000,
        reconciliation_id=12345,
        reduction_amount=0,
        status=created,
        tax_id=27.564.801/0001-36
    ),
    scheduled=2023-01-29,
    type=brcode-payment
)
```

## Payment Request

Here we will teach you how to create and manage your payment requests. The payment request is the main element of our approval flow, which can be checked out by logging into our Web Banking.

The requests are bound to their respective cost centers and represent requests to execute specific payments, which can be transfers, boleto payments, etc. Expect more payment options to be introduced!

### The Payment Request object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the payment request. |
| `amount` | INTEGER | Amount in cents to be paid. |
| `centerId` | STRING | ID of the targeted cost center. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `description` | STRING | Description of the payment request. |
| `due` | STRING | Suggested payment date. Example: "2020-04-23". |
| `status` | STRING | Current payment request status. |
| `tags` | LIST OF STRINGS | Tags associated with the payment request. |
| `type` | STRING | Payment type. Options: "transfer", "brcode-payment", "boleto-payment", "utility-payment". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Payment Requests

`POST /v2/payment-request`

Use this route to create new payment requests in our Web Banking approval flow.

**Request**

```python
import starkbank

requests = starkbank.paymentrequest.create([
    starkbank.PaymentRequest(
        center_id="4762954029334528",
        payment=starkbank.Transfer(
            amount=100000000,
            bank_code="665",
            branch_code="2201",
            account_number="76543-8",
            tax_id="594.739.480-42",
            name="Daenerys Targaryen Stormborn",
        ),
        tags=["daenerys", "request/1234"]
    ),
])

for request in requests:
    print(request)
```

**Response**

```python
PaymentRequest(
    actions=[
        {
            'pictureUrl': '',
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296',
            'email': ''
        },
        {
            'pictureUrl': '',
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096',
            'email': 'rhaegar.targaryen@starkbank.com'
        }
    ],
    amount=100000000,
    center_id=4762954029334528,
    created=2020-10-23T19:36:59.345753,
    due=2020-10-24T03:00:00+00:00,
    id=5756591424929792,
    payment=Transfer(
        account_number=76543-8,
        amount=100000000,
        bank_code=665,
        branch_code=2201,
        name=Daenerys Targaryen Stormborn,
        tax_id=594.739.480-42
    ),
    status=pending,
    tags=['daenerys', 'request/1234'],
    type=transfer,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    updated=2020-10-23T19:36:59.345760+00:00
)
```

### List Payment Requests

`GET /v2/payment-request`

Here you can list and filter payment requests created by the requesting user. We return it paged.

**Request**

```python
import starkbank

requests = starkbank.paymentrequest.query(center_id="4762954029334528", limit=1)

for request in requests:
    print(request)
```

**Response**

```python
PaymentRequest(
    actions=[
        {
            'pictureUrl': '',
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296',
            'email': ''
        },
        {
            'pictureUrl': '',
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096',
            'email': 'rhaegar.targaryen@starkbank.com'
        }
    ],
    amount=100000000,
    center_id=4762954029334528,
    created=2020-10-23T19:36:59.345753,
    due=2020-10-24T03:00:00+00:00,
    id=5756591424929792,
    payment=Transfer(
        account_number=76543-8,
        amount=100000000,
        bank_code=665,
        branch_code=2201,
        name=Daenerys Targaryen Stormborn,
        tax_id=594.739.480-42
    ),
    status=pending,
    tags=['daenerys', 'request/1234'],
    type=transfer,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    updated=2020-10-23T19:36:59.345760+00:00
)
```

# Others

## Webhook

You can create webhook subscriptions to receive events whenever a new log is created. We send the event by making a POST request to your endpoint URL. The event will be delivered with a digital signature (headers["Digital-Signature"]), which can be verified using the Stark Bank public key. This key is recoverable by a GET request to /v2/public-key.

If your endpoint URL does not return a 200 status, the webhook service will try again at most three times. The interval between each attempt is 5 min, 30 min and finally 120 min. In case the event cannot be delivered after those three attempts, we will stop trying to deliver the message.

The event sent to the endpoint URL has the structure shown to the right, where the content of the log sent will depend on the event subscription.

NOTE 1: Registered webhooks will only work for services used in that same version. For example, if you create a transfer in v2, its logs will only trigger v2 webhooks and v1 webhooks would ignore its events.

NOTE 2: Even if you use Webhook, we strongly recommend that you create a daily task to get all undelivered events and set them as delivered. It's important to add redundancy and resilience to your system, preventing you from having outdated information just in case your system is temporarily unable to receive our Webhook events.

### The Webhook object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the webhook subscription. |
| `subscriptions` | LIST OF STRINGS | List of subscribed event types. |
| `url` | STRING | Endpoint URL that receives webhook events. |

### Create a Webhook

`POST /v2/webhook`

Here you can register a new webhook URL. The subscriptions refer to which kinds of logs will be sent to the webhook URL being registered. The subscriptions must be in transfer, boleto, boleto-payment, utility-payment, brcode-payment, boleto-holmes, deposit, darf-payment, payment-request or invoice.

**Request**

```python
import starkbank

webhook = starkbank.webhook.create(
    url="https://winterfell.westeros.gov/events-from-stark-bank",
    subscriptions=[
        "boleto",
        "boleto-payment",
        "transfer",
        "utility-payment"
    ]
)

print(webhook)
```

**Response**

```python
Webhook(
    id=6225875037061120,
    subscriptions=['boleto', 'boleto-payment', 'transfer', 'utility-payment'],
    url=https://winterfell.westeros.gov/events-from-stark-bank
)
```

### List Webhooks

`GET /v2/webhook`

Get a list of non-deleted webhooks in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

webhooks = starkbank.webhook.query()

for webhook in webhooks:
    print(webhook)
```

**Response**

```python
Webhook(
    id=6225875037061120,
    subscriptions=['boleto', 'boleto-payment', 'transfer', 'utility-payment'],
    url=https://winterfell.westeros.gov/events-from-stark-bank
)
```

### Get a Webhook

`GET /v2/webhook/:id`

Get a single Webhook by its id.

**Request**

```python
import starkbank

webhook = starkbank.webhook.get("6225875037061120")

print(webhook)
```

**Response**

```python
Webhook(
    id=6225875037061120,
    subscriptions=['boleto', 'boleto-payment', 'transfer', 'utility-payment'],
    url=https://winterfell.westeros.gov/events-from-stark-bank
)
```

### Delete a Webhook

`DELETE /v2/webhook/:id`

Delete a single Webhook subscription.

NOTE: This action cannot be undone.

**Request**

```python
import starkbank

webhook = starkbank.webhook.delete("6225875037061120")

print(webhook)
```

**Response**

```python
Webhook(
    id=6225875037061120,
    subscriptions=['boleto', 'boleto-payment', 'transfer', 'utility-payment'],
    url=https://winterfell.westeros.gov/events-from-stark-bank
)
```

## Event

Every time a log is created, a corresponding event will be generated and sent to you by webhook, if the appropriate subscription was set. Therefore, the event represents an occurrence in your workspace.

NOTE: All the events have a log property containing an entity log. The nature of the log, however, may change according to the subscription that triggered the event. For example, if the subscription is transfer, the log in the event will be a TransferLog. If the subscription is boleto, the log in the event will be a BoletoLog, and so on.

### The Event object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the event. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `isDelivered` | STRING | Whether the event has been successfully delivered. Options: "true", "false". |
| `subscription` | STRING | Subscription that triggered the event. |
| `workspaceId` | STRING | ID of the workspace the event belongs to. |

### List Events

`GET /v2/event`

Get a list of non-deleted events in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

events = starkbank.event.query(
    is_delivered=False,
    after="2020-04-01",
    before="2020-04-30"
)

for event in events:
    print(event)
```

**Response**

```python
Event(
    id=4537025176797184,
    is_delivered=False,
    subscription=transfer,
    created=2020-04-24 17:49:10.181589,
    log=Log(
        id=5662318377566208,
        created=2020-04-24 17:49:09.348444,
        errors=[],
        type=sending,
        transfer=Transfer(
            id=5950134772826112,
            account_number=76543-8,
            amount=100000000,
            bank_code=665,
            branch_code=2201,
            created=2020-04-24 17:49:08.748893,
            fee=200,
            name=Daenerys Targaryen Stormborn,
            status=processing,
            tags=['daenerys', 'invoice/1234'],
            tax_id=594.739.480-42,
            transaction_ids=['5991715760504832'],
            updated=2020-04-24 17:49:09.632271
        )
    ),
    workspace_id=1231231231231231
)
```

### Get an Event

`GET /v2/event/:id`

Get a single Event by its id.

**Request**

```python
import starkbank

event = starkbank.event.get("4537025176797184")

print(event)
```

**Response**

```python
Event(
    id=4537025176797184,
    is_delivered=False,
    subscription=transfer,
    created=2020-04-24 17:49:10.181589,
    log=Log(
        id=5662318377566208,
        created=2020-04-24 17:49:09.348444,
        errors=[],
        type=sending,
        transfer=Transfer(
            id=5950134772826112,
            account_number=76543-8,
            amount=100000000,
            bank_code=665,
            branch_code=2201,
            created=2020-04-24 17:49:08.748893,
            fee=200,
            name=Daenerys Targaryen Stormborn,
            status=processing,
            tags=['daenerys', 'invoice/1234'],
            tax_id=594.739.480-42,
            transaction_ids=['5991715760504832'],
            updated=2020-04-24 17:49:09.632271
        )
    ),
    workspace_id=1231231231231231
)
```

### Delete an Event

`DELETE /v2/event/:id`

Delete a single Event from the event list.

Note: This action cannot be undone.

**Request**

```python
import starkbank

event = starkbank.event.delete("4537025176797184")

print(event)
```

**Response**

```python
Event(
    id=4537025176797184,
    is_delivered=False,
    subscription=transfer,
    created=2020-04-24 17:49:10.181589,
    log=Log(
        id=5662318377566208,
        created=2020-04-24 17:49:09.348444,
        errors=[],
        type=sending,
        transfer=Transfer(
            id=5950134772826112,
            account_number=76543-8,
            amount=100000000,
            bank_code=665,
            branch_code=2201,
            created=2020-04-24 17:49:08.748893,
            fee=200,
            name=Daenerys Targaryen Stormborn,
            status=processing,
            tags=['daenerys', 'invoice/1234'],
            tax_id=594.739.480-42,
            transaction_ids=['5991715760504832'],
            updated=2020-04-24 17:49:09.632271
        )
    ),
    workspace_id=1231231231231231
)
```

### Update an event

`PATCH /v2/event/:id`

The only information you can update in an Event is the isDelivered property. This can be useful when, after experiencing server downtime on your side, you list all events with isDelivered=false, process them, and then set them as delivered to stabilize your operations.

**Request**

```python
import starkbank

event = starkbank.event.update("4537025176797184", is_delivered=True)

print(event)
```

**Response**

```python
Event(
    id=4537025176797184,
    is_delivered=True,
    subscription=transfer,
    created=2020-04-24 17:49:10.181589,
    log=Log(
        id=5662318377566208,
        created=2020-04-24 17:49:09.348444,
        errors=[],
        type=sending,
        transfer=Transfer(
            id=5950134772826112,
            account_number=76543-8,
            amount=100000000,
            bank_code=665,
            branch_code=2201,
            created=2020-04-24 17:49:08.748893,
            fee=200,
            name=Daenerys Targaryen Stormborn,
            status=processing,
            tags=['daenerys', 'invoice/1234'],
            tax_id=594.739.480-42,
            transaction_ids=['5991715760504832'],
            updated=2020-04-24 17:49:09.632271
        )
    ),
    workspace_id=1231231231231231
)
```

## Event Attempt

When an Event delivery fails, an event attempt will be registered. It carries information meant to help you debug event reception issues.

### The Event Attempt object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the event attempt. |
| `code` | STRING | Delivery error code. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `eventId` | STRING | ID of the associated Event. |
| `message` | STRING | Delivery error description. |
| `webhookId` | STRING | ID of the associated Webhook. |

### List failed Webhook Event delivery attempts

`GET /v2/event/attempt`

Get information on failed webhook event delivery attempts.

**Request**

```python
import starkbank

attempts = starkbank.event.attempt.query(after="2020-01-30")

for attempt in attempts:
    print(attempt)
```

**Response**

```python
Attempt(
    id=4737439230853120,
    code=invalidHttpStatus,
    message=HTTP POST request returned status 404,
    webhook_id=5187231165710336
    event_id=6488144706797568,
    created=2020-01-30 12:35:59.322499,
)
```

### Get an Event Attempt

`GET /v2/event/attempt/:id`

Get a single event attempt by its id.

**Request**

```python
import starkbank

attempt = starkbank.event.attempt.get("4737439230853120")

print(attempt)
```

**Response**

```python
Attempt(
    id=4737439230853120,
    code=invalidHttpStatus,
    message=HTTP POST request returned status 404,
    webhook_id=5187231165710336
    event_id=6488144706797568,
    created=2020-01-30 12:35:59.322499,
)
```

## Pix Key

The Pix keys are saved in the DICT (Diretório de Identificadores de Contas Transacionais), the centralized Pix service managed by Bacen (Brazilian Central Bank) that allows you to search for transactional accounts with convenient addressing keys.

The types of keys currently available are CPF, CNPJ, phone number, e-mail and EVP (random UUID). In this section, we will teach you how to manage DICT keys.

Note: Whenever a Workspace is created, an EVP (random) DICT key is created and associated with it. This is done in order to ensure the safety of the Invoice service, since it requires an active DICT Key to work.

### The Pix Key object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix key (CPF, CNPJ, phone, email or EVP). |
| `accountNumber` | STRING | Account number. |
| `accountType` | STRING | Account type. Options: "checking", "savings", "salary", "payment". |
| `bankName` | STRING | Bank name. |
| `branchCode` | STRING | Account branch code. |
| `ispb` | STRING | Bank ISPB code. |
| `name` | STRING | Account owner full name. |
| `ownerType` | STRING | Account owner type. Options: "business", "personal". |
| `status` | STRING | Current key status. |
| `taxId` | STRING | Account owner CPF or CNPJ. |
| `type` | STRING | Key type. Options: "cpf", "cnpj", "phone", "email", "evp". |

### List your DICT Keys

`GET /v2/dict-key`

Get a list of the DICT Keys you own (or have owned) in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Request**

```python
import starkbank

dict_keys = starkbank.dictkey.query(
    status="registered",
    limit= 1,
    type= "evp"
)

for dict_key in dict_keys:
    print(dict_key)
```

**Response**

```python
DictKey(
    account_number=*ZW5jcnlwdGVkLWFjY291bnQtbnVtYmVy,
    account_type=checking,
    branch_code=*ZW5jcnlwdGVkLWJyYW5jaC1jb2Rl,
    id=1aa1aaaa-a11a-1111-a111-1a1aa111aaaa,
    ispb=67372284,
    name=Jon Snow,
    owner_type=naturalPerson,
    status=registered,
    tax_id=***.456.789-**,
    type=evp
)
```

### Get a DICT Key

`GET /v2/dict-key/:id`

Get a single DICT key by its id. This method includes keys you do not own. You can use it to retrieve a key's information before creating Transfers.

Note: Try to avoid looking up DICT keys without sending transfers afterwards, since Bacen's system will block users making too many standalone requests in a short timespan. Invalid key searches also count towards this block.

Note: The encrypted parameters can be used to create a transfer without the need to decrypt.

**Request**

```python
import starkbank

dictkey = starkbank.dictkey.get("jon.snow@starkbank.com")

print(dictkey)
```

**Response**

```python
DictKey(
    account_number=*ZW5jcnlwdGVkLWFjY291bnQtbnVtYmVy,
    account_type=checking,
    branch_code=*ZW5jcnlwdGVkLWJyYW5jaC1jb2Rl,
    id=jon.snow@starkbank.com,
    ispb=67372284,
    name=Jon Snow,
    owner_type=naturalPerson,
    status=registered,
    tax_id=***.456.789-**,
    type=email
)
```

## Institutions

An Institution is used to query institutions registered by the Brazilian Central Bank for Pix and Ted transactions.

### The Institution object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `displayName` | STRING | Short version of the institution name for display. |
| `name` | STRING | Full version of the institution name. |
| `spiCode` | STRING | SPI code used to identify the institution on Pix transactions. |
| `strCode` | STRING | STR code used to identify the institution on Ted transactions. |

### List Institutions

`GET /v2/institution`

Get a list of institutions.

**Request**

```python
import starkbank

institutions = starkbank.institution.query(search="stark")

for institution in institutions:
    print(institution)
```

**Response**

```python
Institution(
    display_name=Stark Bank,
    name=Stark Bank S.A.,
    spi_code=20018183,
    str_code=
)
```

## Public Key

Some of our responses will be signed using our own private key, such as the messages we send by webhook. In order to verify that it was really us that generated the message, you can get our public key and verify the provided signature and content.

### The Public Key object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `content` | STRING | PEM-encoded public key content. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### List Public Keys

`GET /v2/public-key`

Get a list of the Stark Bank public keys ordered by creation date from newest to oldest. The most recent public key is the one currently in use by the API. The older keys can be used to verify older messages.

**Request**

```python
import starkbank

public_keys = starkbank.key.get()

for public_key in public_keys:
    print(public_key)
```

**Response**

```python
PublicKey(
    content=-----BEGIN PUBLIC KEY-----\nMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEQA+bOEY57yQGYdcF0q7Ia/JPc0Hr8Il0\n/pbETwvDSM+7yCkqTPDRsdptMMaoK9UEXILOaXq9Ot5azrgQEcTetg==\n-----END PUBLIC KEY-----,
    created=2020-03-27 03:31:00.000000
)
```

---

## Other Languages

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