# 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](https://en.wikipedia.org/wiki/Representational_State_Transfer). This means we use predictable, resource-oriented URLs to do banking operations. The API itself speaks exclusively in [JSON](http://www.json.org), including errors, but our [SDK libraries](https://github.com/starkbank?q=sdk) convert responses to appropriate language-specific objects.

Want to check our [OpenAPI 3.1](https://www.openapis.org/) specification? You can download our yaml file [right here](https://docs.starkbank.com/static/starkbank-openapi.yml).

You can also try our [Postman](https://www.postman.com) collection. Download it [here](https://docs.starkbank.com/static/starkbank-postman.json).

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

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

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

## Contents

- [Tech Support](#tech-support)
- [Testing in Sandbox](#testing-in-sandbox)
- [Moving to Production](#moving-to-production)
- [Versioning](#versioning)
- [Authentication](#authentication)
- [Static IP list](#static-ip-list)
- [Errors](#errors)
- [Supported Languages](#supported-languages)
- [Pagination](#pagination)
- [Date & Time](#date--time)
- **Business Account**
  - [Workspace](#workspace): [Create a Workspace](#create-a-workspace), [List Workspaces](#list-workspaces), [Get a Workspace](#get-a-workspace), [Update a Workspace](#update-a-workspace)
  - [Balance](#balance): [Get the Balance](#get-the-balance)
  - [Transaction](#transaction): [List Transactions](#list-transactions), [Get a Transaction](#get-a-transaction)
- **Cash Receivables**
  - [Invoice](#invoice): [Create Invoices](#create-invoices), [List Invoices](#list-invoices), [Get an Invoice](#get-an-invoice), [Update an Invoice](#update-an-invoice), [Get an Invoice QR Code](#get-an-invoice-qr-code), [Get an Invoice PDF](#get-an-invoice-pdf), [List Invoice Logs](#list-invoice-logs), [Get an Invoice Log](#get-an-invoice-log), [Get a reversed Invoice Log PDF](#get-a-reversed-invoice-log-pdf), [Get an Invoice Payment information](#get-an-invoice-payment-information)
  - [Dynamic Brcode](#dynamic-brcode): [Create Dynamic Brcodes](#create-dynamic-brcodes), [List Dynamic Brcodes](#list-dynamic-brcodes), [Get a Dynamic Brcode](#get-a-dynamic-brcode)
  - [Deposit](#deposit): [List Deposits](#list-deposits), [Get a Deposit](#get-a-deposit), [Update a Deposit](#update-a-deposit), [List Deposit Logs](#list-deposit-logs), [Get a Deposit Log](#get-a-deposit-log), [Get a reversed Deposit Log PDF](#get-a-reversed-deposit-log-pdf)
  - [Boleto](#boleto): [Create Boletos](#create-boletos), [List Boletos](#list-boletos), [Get a Boleto](#get-a-boleto), [Delete a Boleto](#delete-a-boleto), [Get a Boleto PDF](#get-a-boleto-pdf), [List Boleto logs](#list-boleto-logs), [Get a Boleto Log](#get-a-boleto-log)
  - [Boleto Holmes](#boleto-holmes): [Create Boleto Holmes](#create-boleto-holmes), [List Boleto Holmes](#list-boleto-holmes), [Get a Boleto Holmes](#get-a-boleto-holmes), [List Boleto Holmes Logs](#list-boleto-holmes-logs), [Get a Boleto Holmes Log](#get-a-boleto-holmes-log)
  - [Split](#split): [List Splits](#list-splits), [Get a Split](#get-a-split), [List Split Logs](#list-split-logs), [Get a Split Log](#get-a-split-log)
  - [Split Receiver](#split-receiver): [Create Split Receiver](#create-split-receiver), [List Split Receivers](#list-split-receivers), [Get a Split Receiver](#get-a-split-receiver), [List Split Receiver Logs](#list-split-receiver-logs), [Get a Split Receiver Log](#get-a-split-receiver-log)
  - [Split Profile](#split-profile): [Put a Split Profile](#put-a-split-profile), [List Split Profiles](#list-split-profiles), [Get a Split Profile](#get-a-split-profile), [List Split Profile Logs](#list-split-profile-logs), [Get a Split Profile Log](#get-a-split-profile-log)
- **Cash Subscription**
  - [Invoice Pull Subscription](#invoice-pull-subscription): [Create Invoice Pull Subscriptions](#create-invoice-pull-subscriptions), [List Invoice Pull Subscriptions](#list-invoice-pull-subscriptions), [Get an Invoice Pull Subscription](#get-an-invoice-pull-subscription), [Cancel an Invoice Pull Subscription](#cancel-an-invoice-pull-subscription), [List Invoice Pull Subscription Logs](#list-invoice-pull-subscription-logs), [Get an Invoice Pull Subscription Log](#get-an-invoice-pull-subscription-log)
  - [Invoice Pull Request](#invoice-pull-request): [Create Invoice Pull Requests](#create-invoice-pull-requests), [List Invoice Pull Requests](#list-invoice-pull-requests), [Get an Invoice Pull Request](#get-an-invoice-pull-request), [Cancel an Invoice Pull Request](#cancel-an-invoice-pull-request), [List Invoice Pull Request Logs](#list-invoice-pull-request-logs), [Get an Invoice Pull Request Log](#get-an-invoice-pull-request-log)
- **Card Receivables**
  - [Merchant Session](#merchant-session): [Create Merchant Sessions](#create-merchant-sessions), [Create Merchant Session Purchase](#create-merchant-session-purchase), [List Merchant Sessions](#list-merchant-sessions), [Get a Merchant Session](#get-a-merchant-session), [List Merchant Session Logs](#list-merchant-session-logs), [Get a Merchant Session Log](#get-a-merchant-session-log)
  - [Merchant Purchase](#merchant-purchase): [Create Merchant Purchase](#create-merchant-purchase), [Update a Merchant Purchase](#update-a-merchant-purchase), [List Merchant Purchases](#list-merchant-purchases), [Get a Merchant Purchase](#get-a-merchant-purchase), [List Merchant Purchase Logs](#list-merchant-purchase-logs), [Get a Merchant Purchase Log](#get-a-merchant-purchase-log)
  - [Merchant Card](#merchant-card): [List Merchant Cards](#list-merchant-cards), [Get a Merchant Card](#get-a-merchant-card), [List Merchant Card Logs](#list-merchant-card-logs), [Get a Merchant Card Log](#get-a-merchant-card-log)
  - [Merchant Installment](#merchant-installment): [List Merchant Installments](#list-merchant-installments), [Get a Merchant Installment](#get-a-merchant-installment), [List Merchant Installment Logs](#list-merchant-installment-logs), [Get a Merchant Installment Log](#get-a-merchant-installment-log)
- **Corporate**
  - [Corporate Holder](#corporate-holder): [Create Corporate Holders](#create-corporate-holders), [List Corporate Holders](#list-corporate-holders), [Get a Corporate Holder](#get-a-corporate-holder), [Update a Corporate Holder](#update-a-corporate-holder), [Cancel a Corporate Holder](#cancel-a-corporate-holder), [List Corporate Holder Logs](#list-corporate-holder-logs), [Get a Corporate Holder Log](#get-a-corporate-holder-log)
  - [Corporate Rule](#corporate-rule)
  - [Corporate Purchase](#corporate-purchase): [List Corporate Purchases](#list-corporate-purchases), [Get a Corporate Purchase](#get-a-corporate-purchase), [Update a Corporate Purchase](#update-a-corporate-purchase), [List Corporate Purchase Logs](#list-corporate-purchase-logs), [Get a Corporate Purchase Log](#get-a-corporate-purchase-log)
  - [Corporate Invoice](#corporate-invoice): [Create a Corporate Invoice](#create-a-corporate-invoice), [List Corporate Invoices](#list-corporate-invoices)
  - [Corporate Withdrawal](#corporate-withdrawal): [Create a Corporate Withdrawal](#create-a-corporate-withdrawal), [List Corporate Withdrawals](#list-corporate-withdrawals), [Get a Corporate Withdrawal](#get-a-corporate-withdrawal)
  - [Corporate Balance](#corporate-balance): [Get the Corporate Balance](#get-the-corporate-balance)
  - [Corporate Transaction](#corporate-transaction): [List Corporate Transactions](#list-corporate-transactions), [Get a Corporate Transaction](#get-a-corporate-transaction)
  - [Card Method](#card-method): [List Card Methods](#list-card-methods)
  - [Merchant Category](#merchant-category): [List Merchant Categories](#list-merchant-categories)
  - [Merchant Country](#merchant-country): [List Merchant Countries](#list-merchant-countries)
- **Bill Payments**
  - [Transfer](#transfer): [Create Transfers](#create-transfers), [List Transfers](#list-transfers), [Get a Transfer](#get-a-transfer), [Cancel a scheduled Transfer](#cancel-a-scheduled-transfer), [Get a Transfer PDF](#get-a-transfer-pdf), [List Transfer Logs](#list-transfer-logs), [Get a Transfer Log](#get-a-transfer-log)
  - [Verified Account](#verified-account): [Create Verified Accounts](#create-verified-accounts), [List Verified Accounts](#list-verified-accounts), [Get a Verified Account](#get-a-verified-account), [Cancel a Verified Account](#cancel-a-verified-account), [List Verified Account Logs](#list-verified-account-logs), [Get a Verified Account Log](#get-a-verified-account-log)
  - [Verified Transfer](#verified-transfer): [Create Verified Transfers](#create-verified-transfers)
  - [Brcode Payment](#brcode-payment): [Create Brcode Payments](#create-brcode-payments), [List Brcode Payments](#list-brcode-payments), [Get a Brcode Payment](#get-a-brcode-payment), [Update a Brcode Payment](#update-a-brcode-payment), [Get a Brcode Payment PDF](#get-a-brcode-payment-pdf), [List Brcode Payment Logs](#list-brcode-payment-logs), [Get a Brcode Payment Log](#get-a-brcode-payment-log)
  - [Boleto Payment](#boleto-payment): [Create Boleto Payments](#create-boleto-payments), [List Boleto Payments](#list-boleto-payments), [Get a Boleto Payment](#get-a-boleto-payment), [Delete a Boleto Payment](#delete-a-boleto-payment), [Get a Boleto Payment PDF](#get-a-boleto-payment-pdf), [List Boleto Payment Logs](#list-boleto-payment-logs), [Get a Boleto Payment Log](#get-a-boleto-payment-log)
  - [Utility Payment](#utility-payment): [Create Utility Payments](#create-utility-payments), [List Utility Payments](#list-utility-payments), [Get a Utility Payment](#get-a-utility-payment), [Delete a Utility Payment](#delete-a-utility-payment), [Get a Utility Payment PDF](#get-a-utility-payment-pdf), [List Utility Payment Logs](#list-utility-payment-logs), [Get a Utility Payment Log](#get-a-utility-payment-log)
  - [Tax Payment](#tax-payment): [Create Tax Payments](#create-tax-payments), [List Tax Payments](#list-tax-payments), [Get a Tax Payment](#get-a-tax-payment), [Delete a Tax Payment](#delete-a-tax-payment), [Get a Tax Payment PDF](#get-a-tax-payment-pdf), [List Tax Payment Logs](#list-tax-payment-logs), [Get a Tax Payment Log](#get-a-tax-payment-log)
  - [Darf Payment](#darf-payment): [Create Darf payments](#create-darf-payments), [List Darf Payments](#list-darf-payments), [Get a Darf Payment](#get-a-darf-payment), [Delete a Darf Payment](#delete-a-darf-payment), [Get a Darf Payment PDF](#get-a-darf-payment-pdf), [List Darf Payment Logs](#list-darf-payment-logs), [Get a Darf Payment Log](#get-a-darf-payment-log)
  - [Payment Preview](#payment-preview): [Create a Payment Preview](#create-a-payment-preview)
  - [Payment Request](#payment-request): [Create Payment Requests](#create-payment-requests), [List Payment Requests](#list-payment-requests)
- **Others**
  - [Webhook](#webhook): [Create a Webhook](#create-a-webhook), [List Webhooks](#list-webhooks), [Get a Webhook](#get-a-webhook), [Delete a Webhook](#delete-a-webhook)
  - [Event](#event): [List Events](#list-events), [Get an Event](#get-an-event), [Delete an Event](#delete-an-event), [Update an event](#update-an-event)
  - [Event Attempt](#event-attempt): [List failed Webhook Event delivery attempts](#list-failed-webhook-event-delivery-attempts), [Get an Event Attempt](#get-an-event-attempt)
  - [Pix Key](#pix-key): [List your DICT Keys](#list-your-dict-keys), [Get a DICT Key](#get-a-dict-key)
  - [Institutions](#institutions): [List Institutions](#list-institutions)
  - [Public Key](#public-key): [List Public Keys](#list-public-keys)

## Tech Support

If you have any questions about our API or [SDKs](https://github.com/starkbank?q=sdk), 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](https://web.starkbank.com/sandbox/create)

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](https://github.com/starkbank?q=sdk) 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](https://web.starkbank.com/signup/email)

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

At Stark Bank, we do not use static API keys or access tokens.

Instead, all API requests are authenticated using [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) digital signatures with the [secp256k1](https://en.bitcoin.it/wiki/Secp256k1) curve and [SHA-256](https://en.bitcoin.it/wiki/SHA-256) digest.

Each request is signed locally on your server using your private key, which is never transmitted. The signature is sent with the request, and we verify it using your registered public key.

Our [SDKs](https://github.com/starkbank?q=sdk) automatically handle request signing.

**Credential Types:**

**Projects:** Bound to a specific Workspace, recommended for most integrations, and only a workspace admin can register.

**Organizations:** Bound to your company’s Tax ID, can manage multiple Workspaces, and only a legal representative can register.

**Setup:**

1. Generate a private and public keys, [learn how](https://docs.starkbank.com/how-to-create-ecdsa-keys.md).

2. Upload your public key in our Web Banking (Sandbox or Production).

3. Configure your SDK with your Project ID or Organization ID and your private key.

**Security:**

1. Keep your private key secure at all times. Never share it with anyone — including Stark Bank — and never hard-code it in your source code. Store it in a [Hardware Security Module (HSM)](https://en.wikipedia.org/wiki/Hardware_security_module) whenever possible. Otherwise, keep it encrypted, such as in an environment variable or secure database.

2. Restrict API access by configuring an [IP allowlist](https://docs.starkbank.com/ip-allowlisting.md) for your credential.

**Example**

```python
import starkbank

# Example key only — replace with your own.
# Never hardcode private keys in source. Store them in an HSM,
# or at minimum in an encrypted KMS.
private_key_content = """
-----BEGIN EC PARAMETERS-----
BgUrgQQACg==
-----END EC PARAMETERS-----
-----BEGIN EC PRIVATE KEY-----
MHQCAQEEIMCwW74H6egQkTiz87WDvLNm7fK/cA+ctA2vg/bbHx3woAcGBSuBBAAK
oUQDQgAE0iaeEHEgr3oTbCfh8U2L+r7zoaeOX964xaAnND5jATGpD/tHec6Oe9U1
IF16ZoTVt1FzZ8WkYQ3XomRD4HS13A==
-----END EC PRIVATE KEY-----
"""

# for project users:
user = starkbank.Project(
    environment="sandbox",
    id="5656565656565656",
    private_key=private_key_content
)

# or, for organization users:
user = starkbank.Organization(
    environment="sandbox",
    id="4545454545454545",
    private_key=private_key_content
)

starkbank.user = user
```

### Do it yourself

Just in case you are unable to use our [SDKs](https://github.com/starkbank?q=sdk), in every request we pass three custom headers: Access-Id, Access-Time, and Access-Signature.

Here is a pseudo-code explaining how to make authenticated requests:

```
# Set your user Id
accessId = "project/12345"
accessId = "organization/12345"
accessId = "organization/12345/workspace/67890"

# Get current Unix Time
accessTime = 1584041509

# Get you json content in string format for POST/PUT/PATCH requests
# or empty string for GET/DELETE requests.
bodyString = ""

# Build the message in this format:
message = accessId + ":" + accessTime + ":" + bodyString

# Load your private key from its pem string
privateKey = PrivateKey.fromPem(...)

# Use ECDSA to sign the message
signature = ECDSA.sign(message, privateKey)

# Convert the signature to base 64
accessSignature = signature.toBase64()

# You are now ready to send the request
request = Request.get(
    url="https://sandbox.api.starkbank.com/v2/transfer",
    body=bodyString,
    headers={
        "Access-Id" : accessId,
        "Access-Time" : accessTime,
        "Access-Signature": accessSignature
    }
)
```

Feeling adventurous? Check out our [Digital Signature libraries](https://github.com/starkbank?q=ecdsa).

**CUSTOM HEADERS**

| Header | Description |
| --- | --- |
| Access-Id | Static string that identifies the user: project/{projectId} for projects; organization/{organizationId} for organizations; organization/{organizationId}/workspace/{workspaceId} for organizations operating inside a Workspace. |
| Access-Time | Current Unix-Time: the number of seconds since 1 January 1970. |
| Access-Signature | Base64-encoded ECDSA signature of Access-Id + ":" + Access-Time + ":" + body, where body is the JSON string for POST/PUT/PATCH requests and an empty string for GET/DELETE requests. |

**Access-Id Example**

project/12345

**Access-Time Example**

1584041509

**Access-Signature Example**

MEYCIQC5wiR/fEmwJHscoQ1a4gn9w/qiYQlr8qsdo95MsfgFNwIhAIi4jJ3bzhg+6QEu8g5qK0SNSzIi9JwRuDuP2NZYpLP3

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

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

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

List endpoints return at most **100** objects per call, together with a `cursor` string. To fetch the next batch, repeat the same request with the cursor in the query string (`?cursor=...`), keeping every other filter unchanged. The cursor comes back as **null** when there are no more results.

Cursors are opaque: do not parse, build or compare them, and do not rely on integer offsets. Use `limit` to ask for smaller batches (up to 100).

Our [SDKs](https://github.com/starkbank?q=sdk) expose two ways to list: `query`, a generator that walks through every page for you, and `page`, which returns one batch plus the next cursor so you can stop and resume whenever it is convenient. The example uses `page`; the last call shows how to send the cursor over plain HTTP.

**Example**

```python
import starkbank

cursor = None
while True:
    transfers, cursor = starkbank.transfer.page(limit=50, cursor=cursor)
    for transfer in transfers:
        print(transfer)
    if cursor is None:
        break
```

## 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", "frozen" or "closed". |
| `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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `name` | REQUIRED | This string will show up to identify your Workspace when you log into it at our Web Banking. Example: 'My Workspace' |
| `username` | REQUIRED | This string uniquely identifies the Workspace in our entire database. It is also part of the Workspace Web Banking URL and must, therefore, be URL-safe. For example, if a Workspace in Sandbox has the 'my-workspace' username, its URL would be "https://my-workspace.sandbox.starkbank.com" |
| `allowedTaxIds` | OPTIONAL | List of tax IDs that will be allowed to send Deposits to this Workspace. If empty, all are allowed. Example: ``` ["012.345.678-90", "20.018.183/0001-80"] ``` |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of IDs of the Workspaces to be retrieved. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `username` | OPTIONAL | Workspace username to be searched. |

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the workspace. |
| `allowedTaxIds` | OPTIONAL | List of tax IDs that will be allowed to send Deposits to this Workspace. If empty, all are allowed. Example: ``` ["012.345.678-90", "20.018.183/0001-80"] ``` |
| `name` | OPTIONAL | Full name that identifies the Workspace. This name will appear when people access the Workspace on our platform, for example. Example: 'Stark Bank Workspace' |
| `picture` | OPTIONAL | Binary buffer of the picture. Example: open("path/to/picture.png", "rb").read() |
| `pictureType` | CONDITIONALLY REQUIRED | Picture mime type. This parameter will be required if the picture parameter is informed. Example: 'image/png' or 'image/jpeg' |
| `status` | OPTIONAL | You can block or activate a specific Workspace. Example: 'active' or 'blocked' |
| `username` | OPTIONAL | Simplified name to define the workspace URL. This name must be unique across all Stark Bank Workspaces. Example: 'starkbank-workspace' |

**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](#transaction) 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.

We create one automatically whenever a financial operation takes place in your workspace, such as when you make a [Transfer](#transfer), pay a [Boleto](#boleto) or receive money from a paid Boleto.

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `externalIds` | OPTIONAL | Filter transactions that carry the specified external IDs. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

**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](#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](#split-receiver), and add the receiver into the [Splits](#split) array.

### The Invoice object

**Attributes**

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

### Create Invoices

`POST /v2/invoice`

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

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

**Parameters**

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

**Request**

```python
import starkbank
from datetime import datetime

invoices = starkbank.invoice.create([
    starkbank.Invoice(
        amount=400000,
        descriptions=[{'key': 'Arya', 'value': 'Not today'}],
        discounts=[{'percentage': 10, 'due': datetime(2021, 3, 12, 15, 23, 26, 689377)}],
        due=datetime(2021, 5, 12, 15, 23, 26, 689377),
        expiration=123456789,
        fine=2.5,
        interest=1.3,
        name="Arya Stark",
        tags=['War supply', 'Invoice #1234'],
        tax_id="012.345.678-90",
        rules=[
            {
                'key': 'allowedTaxIds',
                'value': [
                    '012.345.678-90',
                    '45.059.493/0001-73'
                ]
            }
        ],
        splits=[
            Split(amount=3000, receiverId="5742447426535424"), Split(amount=5000, receiverId="5743243941642240")
        ]
    )
])

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

**Response**

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

### List Invoices

`GET /v2/invoice`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter invoices by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `transactionIds` | OPTIONAL | List of transaction IDs linked to the desired invoices. |

**Request**

```python
import starkbank

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

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

**Response**

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

### Get an Invoice

`GET /v2/invoice/:id`

Get a single invoice by its id.

**Parameters**

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

**Request**

```python
import starkbank

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

print(invoice)
```

**Response**

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

### Update an Invoice

`PATCH /v2/invoice/:id`

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

**Parameters**

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

**Request**

```python
import starkbank

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

print(updated_invoice)
```

**Response**

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

### Get an Invoice QR Code

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

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

**Parameters**

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

**Request**

```python
import starkbank

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

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

### Get an Invoice PDF

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

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

**Parameters**

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

**Request**

```python
import starkbank

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

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

### List Invoice Logs

`GET /v2/invoice/log`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `invoiceIds` | OPTIONAL | Array of invoice ids that are linked to the logs you desire. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

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

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

**Response**

```python
Log(
    created=2020-10-27 00:30:12.141283,
    errors=[],
    id=6742710681600000,
    type=credited,
    invoice=Invoice(
        amount=120000,
        brcode=00020101021226860014br.gov.bcb.pix2564invoice-h.sandbox.starkbank.com/7e0b4b71ec924f48865a4a3d979565f65204000053039865802BR5915Stark Bank S.A.6009Sao Paulo62070503***6304365D,
        created=2020-10-27 00:24:56.372300,
        descriptions=[{'value': 'Not today', 'key': 'Arya'}],
        discount_amount=0,
        discounts=[{'percentage': 10.0, 'due': '2021-03-12T18:23:26+00:00'}],
        due=2021-05-12 15:23:26,
        expiration=123456789,
        fee=0,
        pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
        link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
        fine=2.5,
        fine_amount=0,
        id=5616810774757376,
        interest=1.3,
        interest_amount=0,
        name=Arya Stark,
        nominal_amount=120000,
        status=paid,
        tags=['new sword', 'invoice #1234'],
        transaction-ids=[],
        tax_id=012.345.678-90,
        updated=2020-10-27 00:30:12.362815
    )
)
```

### Get an Invoice Log

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

Get a single invoice Log by its id.

**Parameters**

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

**Request**

```python
import starkbank

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

print(log)
```

**Response**

```python
Log(
    created=2020-10-27 00:30:12.141283,
    errors=[],
    id=6742710681600000,
    type=credited,
    invoice=Invoice(
        amount=120000,
        brcode=00020101021226860014br.gov.bcb.pix2564invoice-h.sandbox.starkbank.com/7e0b4b71ec924f48865a4a3d979565f65204000053039865802BR5915Stark Bank S.A.6009Sao Paulo62070503***6304365D,
        created=2020-10-27 00:24:56.372300,
        descriptions=[{'value': 'Not today', 'key': 'Arya'}],
        discount_amount=0,
        discounts=[{'percentage': 10.0, 'due': '2021-03-12T18:23:26+00:00'}],
        due=2021-05-12 15:23:26,
        expiration=123456789,
        fee=0,
        pdf=https://invoice-h.sandbox.starkbank.com/pdf/851ff545535c40ba88e24a05accb9978,
        link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
        fine=2.5,
        fine_amount=0,
        id=5616810774757376,
        interest=1.3,
        interest_amount=0,
        name=Arya Stark,
        nominal_amount=120000,
        status=paid,
        tags=['new sword', 'invoice #1234'],
        transaction-ids=[],
        tax_id=012.345.678-90,
        updated=2020-10-27 00:30:12.362815
    )
)
```

### Get a reversed Invoice Log PDF

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

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

**Parameters**

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

**Request**

```python
import starkbank

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

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

### Get an Invoice Payment information

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

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

**Parameters**

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

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

## 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](#invoice) resource.

When a Dynamic Brcode is paid, a [Deposit](#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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | A non-negative integer that represents the amount in cents to be received. Example: 100 (R$1.00). |
| `displayDescription` | OPTIONAL | Description to be shown in the payer bank interface. ex: "Payment for service #1234" |
| `expiration` | OPTIONAL | Time in seconds counted from the creation datetime until the brcode expires. After expiration, the brcode cannot be paid anymore. Default value: 3600 (1 hour). |
| `rules` | OPTIONAL | List of rules for modifying dynamic brcode behavior. Example: ``` [{"key": "allowedTaxIds", "value": ["012.345.678-90", "45.059.493/0001-73"]}] ``` |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `uuids` | OPTIONAL | list of uuids to filter retrieved objects. |

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `sort` | OPTIONAL | Sort order considered in the response. Options are: "created", "-created". |
| `status` | OPTIONAL | Filter deposits by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the deposit. Example: '5656565656565656'. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the deposit. Example: '5155165527080960'. |
| `amount` | REQUIRED | The new amount of the Deposit. If the amount = 0 the Deposit will be 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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `depositIds` | OPTIONAL | Array of deposit ids that are linked to the logs you desire. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. |

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

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.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.

**Parameters**

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

**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](#split-receiver), and add the receiver into the [Splits](#split) 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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | A positive integer that represents the amount in cents to be charged, with a minimum of 200 (R$2.00). Example: 1234 (R$12.34). |
| `city` | REQUIRED | Customer city name. Example: "São Paulo". |
| `district` | REQUIRED | Customer district name. Example: "Itaim Bibi". |
| `name` | REQUIRED | Customer full name. Example: "Anthony Edward Stark". |
| `stateCode` | REQUIRED | Customer state code. Example: "SP". |
| `streetLine1` | REQUIRED | Customer street address. Example: "Av. Faria Lima, 1844". |
| `streetLine2` | REQUIRED | Customer street address complement. Example: "CJ 13". |
| `taxId` | REQUIRED | Customer CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90. |
| `zipCode` | REQUIRED | Customer zip code. Example: 01500-000. |
| `descriptions` | OPTIONAL | List of up to 15 descriptions containing information to help the customer understand why he is being charged. You can add text and amount to create a table or you can just add text. When generating PDFs, if the 'booklet' layout is selected, only the text field of the first description will be considered and it will be used to fill the installment cell in the PDF. Example: ``` [{"text": "Explaining first part of the value", "amount": 20000}, {"text": "More text to explaining something to the customer"}] ``` |
| `discounts` | OPTIONAL | List of up to 2 discounts specifying the discount percentage and the limit date up to when the discount is valid. Example: ``` [{"percentage": 5, "date": "2020-04-01"}, {"percentage": 3.5, "date": "2020-04-02"}] ``` |
| `due` | OPTIONAL | Due date of the boleto. Example: 2020-06-27. The default value is set to two days after creation date. |
| `fine` | OPTIONAL | Percentage of the boleto amount charged if customer pays after the due date. Default value = 2.00 (2%). |
| `interest` | OPTIONAL | Monthly interest, in percentage, charged if customer pays after the due date. Default value = 1.00 (1%). |
| `overdueLimit` | OPTIONAL | Number of days after due date after which the boleto will no longer be payable. 0<=overdueLimit<=59. Default value=59. |
| `receiverName` | OPTIONAL | Name of the credit receiver (Sacador Avalista). If none is informed, workspace owner name will be used. If informed, receiverTaxId must also be informed. |
| `receiverTaxId` | OPTIONAL | Tax ID (CPF/CNPJ) of the credit receiver (Sacador Avalista). If none is informed, workspace owner tax ID will be used. If informed, receiverName must also be informed. |
| `splits` | OPTIONAL | Array of Split objects to indicate payment receivers. Example: ``` [{"receiverId": "5742447426535424", "amount": 100}, {"receiverId": "5743243941642240", "amount": 200}] ``` |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter boletos by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the boleto entity |
| `hiddenFields` | OPTIONAL | List of fields to be hidden in Boleto pdf. Example: ["customerAddress"]. |
| `layout` | OPTIONAL | PDF layout. Available options are "default" (full page) and "booklet" ("carnê"). |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `boletoIds` | OPTIONAL | Array of boleto ids that are linked to the logs you desire. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. |

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

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `boletoId` | REQUIRED | Investigated boleto entity ID. ex: '5656565656565656' |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `boletoId` | OPTIONAL | String to get boletos holmes that refer to a specific boleto ID. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545'] |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter holmes by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `holmesIds` | OPTIONAL | Filter logs by Holmes IDs |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. |

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

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.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](#invoice) or [Boleto](#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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `receiverIds` | OPTIONAL | list of receiver ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545']. |
| `status` | OPTIONAL | Filter splits by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `splitIds` | OPTIONAL | Array of Split ids that are linked to the logs you desire. |
| `types` | OPTIONAL | Filters logs by log types. |

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

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.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](#invoice) or [Boleto](#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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `accountNumber` | REQUIRED | receiver bank account number. Use '-' before the verifier digit. ex: '876543-2' |
| `accountType` | REQUIRED | Receiver bank account type. This parameter only has effect on Pix SplitReceivers. ex: 'checking', 'savings', 'salary' or 'payment' |
| `bankCode` | REQUIRED | Code of the receiver bank institution in Brazil. If an ISPB (8 digits) is informed, a PIX splitReceiver will be created, else a Ted will be issued. ex: '20018183' or '341' |
| `branchCode` | REQUIRED | Receiver bank account branch. Use '-' in case there is a verifier digit. ex: '1357-9' |
| `name` | REQUIRED | Receiver full name. ex: 'Anthony Edward Stark' |
| `taxId` | REQUIRED | Receiver account tax ID (CPF or CNPJ) with or without formatting. ex: '01234567890' or '20.018.183/0001-80' |
| `tags` | OPTIONAL | list of strings for reference when searching for receivers. ex: ['seller/123456'] |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `receiverIds` | OPTIONAL | List of receiver ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545']. |
| `status` | OPTIONAL | Filter split receivers by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `taxIds` | OPTIONAL | List of up to 100 tax IDs (CPF or CNPJ) to filter retrieved splitReceivers. Example: ["012.345.678-90", "45.059.493/0001-73"]. |

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `receiverIds` | OPTIONAL | List of Split Receiver ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545']. |
| `types` | OPTIONAL | filter retrieved objects by event types. ex: 'processing' or 'success' |

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

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.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: "instant", "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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `interval` | REQUIRED | Frequency of the profile's transfer. No default; must be provided. Options: "instant", "day", "week", "month" |
| `delay` | OPTIONAL | How long the amount will stay at the workspace before being transferred, in milliseconds. Must be between 0 and 1000000000. Default is 0 |
| `tags` | OPTIONAL | List of strings for reference when searching for profiles. ex: ["test profile"] |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter split profiles by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `profileIds` | OPTIONAL | List of Split Profile ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545']. |
| `types` | OPTIONAL | filter retrieved objects by event types. ex: 'processing' or 'success' |

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

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.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". |
| `data` | OBJECT | Additional information associated with the subscription. On creation, its content depends on the subscription type: the payer's bank account details for "push", no data for "qrcode", and immediate payment parameters for "qrcodeAndPayment" and "paymentAndOrQrcode". When an active subscription is retrieved or listed, data can contain the payer's accountNumber, bankCode, branchCode and taxId regardless of the authorization journey. |
| `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.

**Data by authorization journey**

The type of the subscription defines the authorization journey and, with it, the content of the data object. You always inform it in the data property of the subscription, following the naming conventions of each SDK.

| Journey | type | data |
| --- | --- | --- |
| 1st: push notification | push | Required. Bank account details of the payer. |
| 2nd: QR Code with direct authorization | qrcode | Not required. It can be omitted. |
| 3rd: QR Code with authorization upon payment | qrcodeAndPayment | Required. Parameters of the immediate payment. |
| 4th: billing QR Code with authorization offer | paymentAndOrQrcode | Required. Parameters of the immediate payment. |

For **push**, data carries the bank account of the payer. Every field is a string and all of them are required:

| Field | Type | Tag | Description |
| --- | --- | --- | --- |
| accountNumber | STRING | REQUIRED | Account number of the payer. Example: "5647143184367616". |
| branchCode | STRING | REQUIRED | Branch code of the payer. Example: "0001". |
| bankCode | STRING | REQUIRED | ISPB of the institution of the payer. Example: "20018183". |
| taxId | STRING | REQUIRED | CPF or CNPJ of the payer. Example: "012.345.678-90". |

```
{
    "subscriptions": [
        {
            "type": "push",
            "amount": 1000000,
            "interval": "month",
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "start": "2025-09-14",
            "data": {
                "accountNumber": "5647143184367616",
                "branchCode": "0001",
                "bankCode": "20018183",
                "taxId": "012.345.678-90"
            }
        }
    ]
}
```

For **qrcodeAndPayment** and **paymentAndOrQrcode**, data carries the parameters of the immediate payment. The fields below follow the same rules as the ones of an [Invoice](#invoice):

| Field | Type | Tag | Description |
| --- | --- | --- | --- |
| amount | INTEGER | REQUIRED | Amount of the immediate payment in cents. Example: 20000 (R$200.00). |
| due | STRING | OPTIONAL | Due datetime of the immediate payment in ISO 8601. Example: "2027-05-31T02:59:59.999999+00:00". Default value: 2 days after creation. |
| expiration | INTEGER | OPTIONAL | Time in seconds counted from the due datetime until the invoice expires. Default value: 5097600 (59 days). Inform 0 so that the invoice expires automatically after its due date. |
| fine | FLOAT | OPTIONAL | Fixed percentage over the amount of the invoice, charged when the payment occurs after the due datetime. Example: 2.5 means 2.5%. Default value: 2.00 (2%). |
| interest | FLOAT | OPTIONAL | Monthly interest percentage charged when it is paid after the due datetime. Example: 5 means 5% per month. Default value: 1.00 (1%). |

```
{
    "subscriptions": [
        {
            "type": "qrcodeAndPayment",
            "amount": 1000000,
            "interval": "month",
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "start": "2025-09-14",
            "data": {
                "amount": 20000,
                "due": "2027-05-31T02:59:59.999999+00:00",
                "expiration": 0,
                "fine": 2.5,
                "interest": 5
            }
        }
    ]
}
```

```
{
    "subscriptions": [
        {
            "type": "paymentAndOrQrcode",
            "amount": 1000000,
            "interval": "month",
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "start": "2025-09-14",
            "data": {
                "amount": 20000,
                "due": "2027-05-31T02:59:59.999999+00:00",
                "expiration": 0,
                "fine": 2.5,
                "interest": 5
            }
        }
    ]
}
```

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `displayDescription` | OPTIONAL | Description to be presented to the payer. |
| `externalId` | OPTIONAL | Safe string that must be unique among all your Invoice PullSubscriptions to prevent duplicates. |
| `interval` | REQUIRED | Cycle definition of the Invoice Pull Requests. Options are "week", "month", "quarter", "semester" and "year". |
| `name` | OPTIONAL | Name of the debtor. |
| `pullMode` | REQUIRED | Defines if the invoice pull requests will be made automatically by Stark Bank or manually by the company. |
| `pullRetryLimit` | REQUIRED | Defines how many times the receiver is able to create Invoice Pull Requests for retries. Options are "0" and "3". |
| `referenceCode` | OPTIONAL | Safe string that must be unique among all your Pix Subscriptions and represent a contract. |
| `start` | REQUIRED | Expected date to settle the first Invoice Pull Request. |
| `taxId` | OPTIONAL | Tax id of the debtor. |
| `type` | REQUIRED | Subscription journey type. Options: "push", "qrcode", "qrcodeAndPayment" or "paymentAndOrQrcode". |
| `amount` | CONDITIONALLY REQUIRED | Fixed amount to be charged every cycle. Required if the subscription has a fixed amount, and never sent together with amountMinLimit. Minimum is 1 (R$0.01). |
| `amountMinLimit` | CONDITIONALLY REQUIRED | Minimum amount limit that the payer can set to be charged every cycle. Required if the subscription has a variable amount, and never sent together with amount. Minimum is 1 (R$0.01). |
| `data` | CONDITIONALLY REQUIRED | Additional data required by some types of invoice pull subscription. On creation, it is required for the **push**, **qrcodeAndPayment** and **paymentAndOrQrcode** types, and not required for the **qrcode** type. For the **push** type, it sets the bank account details of the payer, with accountNumber, branchCode, bankCode and taxId as required strings. For the **qrcodeAndPayment** or **paymentAndOrQrcode** types, it sets the immediate payment parameters: amount in cents is required, while due in ISO 8601 (default: 2 days after creation), expiration in seconds (default 5097600, 59 days), fine as a fixed percentage (default 2.00) and interest as a monthly percentage (default 1.00) are optional. This parameter only defines what you send on creation. When an active subscription is later retrieved or listed, the data returned in the response can contain the payer's accountNumber, bankCode, branchCode and taxId regardless of the authorization journey. |
| `due` | OPTIONAL | Due date for answering with an approval or denial. If not provided, defaults to 2 days after creation. |
| `end` | OPTIONAL | Determines the final date of the subscription. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `expand` | OPTIONAL | List of strings to expand the invoice pull subscription information. Options: "data". |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter invoice pull subscriptions by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | String used to get the specific 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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | String used to get the specific invoice pull subscription by its ID. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `subscriptionIds` | OPTIONAL | List of strings to get specific entities by ids. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `types` | OPTIONAL | Filter logs by log types. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | String used to get the specific 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](#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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `attemptType` | OPTIONAL | Define the type of attempt, if it is the first one of a billing cycle or if it is a retry. Options: "default", "retry". Default is "default". |
| `due` | REQUIRED | Expected date of settlement. |
| `invoiceId` | REQUIRED | Unique ID of the invoice to be pulled. |
| `subscriptionId` | REQUIRED | Unique ID of the invoice pull subscription. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `externalIds` | OPTIONAL | List of external IDs linked to the desired pull requests. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `invoiceIds` | OPTIONAL | List of invoice IDs linked to the desired pull requests. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter invoice pull request by the specified status. |
| `subscriptionIds` | OPTIONAL | List of subscription IDs linked to the desired pull requests. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | String used to get the specific 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.

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `requestIds` | OPTIONAL | List of strings to get specific entities by ids. |
| `types` | OPTIONAL | Filter payment requests by the specified types. Example: confirmed |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | String used to get the specific 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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `allowedFundingTypes` | REQUIRED | The types of funding that are allowed to be used for the purchase. Options are "credit" and "debit". |
| `allowedInstallments` | REQUIRED | The amount and number of installments allowed for the purchase. A non-negative integer that represents the amount in cents to be received and the number of installments. E.g: 100 (R$1.00). |
| `expiration` | REQUIRED | Time in seconds counted from the creation datetime until the session expires. After expiration, a purchase cannot be created using the session anymore. E.g.: 3600 (1 hour). |
| `allowedIps` | OPTIONAL | The IP addresses that are allowed to create a purchase using the session. |
| `challengeMode` | OPTIONAL | Defines whether or not a holder verification (3DS) will be used when authorizing the purchase. 3DS is a protocol designed to enhance security for e-commerce purchases. When enabled, the issuer provides a link for the card holder to complete a verification challenge. Options are "enabled" and "disabled". Default: "enabled" |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**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](#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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | A non-negative integer that represents the amount in cents to be received. E.g: 100 (R$1.00) |
| `cardExpiration` | REQUIRED | A string in the format YYYY-MM representing the expiration of the card to be used for the purchase. |
| `cardNumber` | REQUIRED | A string representing the number of the card to be used for the purchase. |
| `cardSecurityCode` | REQUIRED | A string representing the security code of the card to be used for the purchase. |
| `fundingType` | REQUIRED | The type of funding to be used for the purchase. Options are "credit" and "debit". |
| `holderName` | REQUIRED | The name of the card holder as it appears on the card. |
| `uuid` | REQUIRED | The UUID of the Merchant Session created by the merchant to process the purchase. |
| `billingCity` | CONDITIONALLY REQUIRED | The billing city associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `billingCountryCode` | CONDITIONALLY REQUIRED | The billing country code associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `billingStateCode` | CONDITIONALLY REQUIRED | The billing state code associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `billingStreetLine1` | CONDITIONALLY REQUIRED | The billing street address associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `billingStreetLine2` | CONDITIONALLY REQUIRED | The billing street address complement associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `billingZipCode` | CONDITIONALLY REQUIRED | The billing zip code associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `holderEmail` | CONDITIONALLY REQUIRED | The email associated with the holder of the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `holderPhone` | CONDITIONALLY REQUIRED | The phone number associated with the holder of the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `installmentCount` | OPTIONAL | A non-negative integer that represents the number of purchase installments. Default: 1 |
| `metadata` | CONDITIONALLY REQUIRED | An object containing additional data related to the purchase. If 3DS is enabled, the following fields related to the payer's device are required: userAgent, timezoneOffset, userIp, language. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter sessions by the specified status, such as: active, expired, success. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant session that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `sessionIds` | OPTIONAL | Filter the merchant session ids to only include its corresponding logs |
| `types` | OPTIONAL | Filters logs by log types. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant session that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**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](#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](#merchant-session) Purchase.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | A non-negative integer that represents the amount in cents to be received. E.g: 100 (R$1.00) |
| `cardId` | REQUIRED | The ID of the Merchant Card to be used for the purchase. |
| `fundingType` | REQUIRED | The type of funding to be used for the purchase. Options are "credit" and "debit". |
| `billingCity` | CONDITIONALLY REQUIRED | The billing city associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `billingCountryCode` | CONDITIONALLY REQUIRED | The billing country code associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `billingStateCode` | CONDITIONALLY REQUIRED | The billing state code associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `billingStreetLine1` | CONDITIONALLY REQUIRED | The billing street address associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `billingStreetLine2` | CONDITIONALLY REQUIRED | The billing street address complement associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `billingZipCode` | CONDITIONALLY REQUIRED | The billing zip code associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `challengeMode` | OPTIONAL | Defines whether or not a holder verification (3DS) will be used when authorizing the purchase. Options are "enabled" and "disabled". Default: "enabled" |
| `holderEmail` | CONDITIONALLY REQUIRED | The email associated with the holder of the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `holderPhone` | CONDITIONALLY REQUIRED | The phone number associated with the holder of the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise. |
| `installmentCount` | OPTIONAL | A non-negative integer that represents the number of purchase installments. Default: 1 |
| `metadata` | CONDITIONALLY REQUIRED | An object containing additional data related to the purchase. If 3DS is enabled, the following fields related to the buyer's device are required: userAgent, timezoneOffset, userIp, language. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the purchase entity. |
| `amount` | OPTIONAL | New amount of the purchase. If the purchase is confirmed, this will debit and reverse the difference. If the purchase is authorized, only 0 is allowed and this will cancel the authorization. Example: 200 (R$2.00). |
| `status` | OPTIONAL | This can be used to cancel or reverse the purchase by passing 'canceled' or 'reversed' as the status patch. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter purchases by the specified status, such as: created, approved, denied, confirmed, paid, pending, canceled, voided, failed. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant purchase that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `purchaseIds` | OPTIONAL | Filter the merchant purchase ids to only include its corresponding logs |
| `types` | OPTIONAL | Filters logs by log types. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant purchase that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter cards by the specified status, such as: active, expired, canceled or blocked. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant card that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cardIds` | OPTIONAL | Array of card ids that are linked to the logs you desire. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant card that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter installments by the specified status, such as: created, paid, canceled, voided. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant installment that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `installmentIds` | OPTIONAL | Filter the merchant installment ids to only include their corresponding logs |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant installment that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

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

# Corporate

## Corporate Holder

The Corporate Holder resource describes a card holder that may group several corporate cards.

Holders support spending rules that apply to every card bound to them, so you can cap how much a person or a team spends in a given interval without touching each card.

You can also grant access to a holder to specific members or projects of your [Workspace](#workspace) through the permissions array, and bind the holder to a cost center to organize your corporate expenses.

After a holder is created, issue its cards with the Corporate Card resource.

### The Corporate Holder object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the corporate holder. Example: "5155165527080960". |
| `name` | STRING | Card holder name. Example: "Iron Bank S.A.". |
| `status` | STRING | Current corporate holder status. Options: "active", "blocked", "canceled". |
| `centerId` | STRING | Id of the cost center the holder is bound to. Returned as an empty string when the holder has no cost center. Example: "5656565656565656". |
| `tags` | LIST OF STRINGS | Tags associated with the corporate holder. Example: ["traveler employee"]. |
| `updated` | STRING | Latest update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `permissions` | LIST OF OBJECTS | List of permission objects representing the access granted to members and projects of your Workspace for this particular card holder. |
| `rules` | LIST OF OBJECTS | List of holder spending rule objects. Pass "rules" in the expand parameter to also receive the counters and the currency and merchant details of each rule. |
| `centerName` | STRING | Name of the cost center the holder is bound to. Only returned when "centerName" is passed in the expand parameter. |

### Create Corporate Holders

`POST /v2/corporate-holder`

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

**NOTE:**Holder names must be unique among the active holders of your [Workspace](#workspace). Creating a holder with the name of another active holder will be rejected.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `name` | REQUIRED | Card holder name. Example: "Iron Bank S.A.". |
| `centerId` | OPTIONAL | Id of the target cost center. Example: "5656565656565656". |
| `permissions` | OPTIONAL | Array of permission objects granting access to this holder. Each object requires an ownerType and an ownerId. Example: ``` [{"ownerType": "project", "ownerId": "6253551860842496"}, {"ownerType": "member", "ownerId": "6227829385592832"}] ``` |
| `rules` | OPTIONAL | Array of rule objects with the spending rules that will apply to every card bound to this holder. Example: ``` [{"name": "General USD", "interval": "day", "amount": 100000, "currencyCode": "USD"}] ``` |
| `tags` | OPTIONAL | Array of up to 100 strings to tag the entity for future queries. All tags will be converted to lowercase. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "centerName". |

**Request**

```python
import starkbank

holders = starkbank.corporateholder.create([
    starkbank.CorporateHolder(
        name="Iron Bank S.A.",
        tags=["Traveler Employee"],
        permissions=[
            starkbank.corporateholder.Permission(
                owner_id="6253551860842496",
                owner_type="project"
            )
        ],
        rules=[
            starkbank.CorporateRule(
                name="General USD",
                interval="day",
                amount=100000,
                currency_code="USD",
                categories=[starkbank.MerchantCategory(code="fastFoodRestaurants")],
                countries=[starkbank.MerchantCountry(code="USA")],
                methods=[starkbank.CardMethod(code="token")]
            )
        ]
    )
])

for holder in holders:
    print(holder)
```

**Response**

```python
CorporateHolder(
    id=5155165527080960,
    name=Iron Bank S.A.,
    center_id=,
    status=active,
    tags=['traveler employee'],
    permissions=[
        Permission(
            owner_email=,
            owner_id=6253551860842496,
            owner_name=Iron Bank Sandbox,
            owner_picture_url=,
            owner_status=active,
            owner_type=project,
            created=2022-01-01 00:00:00
        )
    ],
    rules=[
        CorporateRule(
            id=6067428166893568,
            name=General USD,
            amount=100000,
            interval=day,
            schedule=,
            purposes=[],
            currency_code=USD,
            categories=[MerchantCategory(code=fastFoodRestaurants, type=)],
            countries=[MerchantCountry(code=USA)],
            methods=[CardMethod(code=token)]
        )
    ],
    updated=2022-01-01 00:00:00,
    created=2022-01-01 00:00:00
)
```

### List Corporate Holders

`GET /v2/corporate-holder`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "centerName". |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of up to 100 strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `names` | OPTIONAL | List of up to 100 exact holder names to filter retrieved entities. Not available in the SDKs. |
| `search` | OPTIONAL | String used to search holders by name. When it is informed, no cursor is returned. Not available in the SDKs. |
| `status` | OPTIONAL | Filter holders by the specified status. Options: "active", "blocked", "canceled". |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

holders = starkbank.corporateholder.query(
    limit=10,
    status=["active"]
)

for holder in holders:
    print(holder)
```

**Response**

```python
CorporateHolder(
    id=5155165527080960,
    name=Iron Bank S.A.,
    center_id=,
    status=active,
    tags=['traveler employee'],
    permissions=[
        Permission(
            owner_email=,
            owner_id=6253551860842496,
            owner_name=Iron Bank Sandbox,
            owner_picture_url=,
            owner_status=active,
            owner_type=project,
            created=2022-01-01 00:00:00
        )
    ],
    rules=[
        CorporateRule(
            id=6067428166893568,
            name=General USD,
            amount=100000,
            interval=day,
            schedule=,
            purposes=[],
            currency_code=USD,
            categories=[MerchantCategory(code=fastFoodRestaurants, type=)],
            countries=[MerchantCountry(code=USA)],
            methods=[CardMethod(code=token)]
        )
    ],
    updated=2022-01-01 00:00:00,
    created=2022-01-01 00:00:00
)
```

### Get a Corporate Holder

`GET /v2/corporate-holder/:id`

Get a single corporate holder by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the corporate holder entity. |
| `expand` | OPTIONAL | Fields to return expanded in the response. Options: "rules", "centerName". |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

holder = starkbank.corporateholder.get(
    "5155165527080960",
    expand=["rules"]
)

print(holder)
```

**Response**

```python
CorporateHolder(
    id=5155165527080960,
    name=Iron Bank S.A.,
    center_id=,
    status=active,
    tags=['traveler employee'],
    permissions=[
        Permission(
            owner_email=,
            owner_id=6253551860842496,
            owner_name=Iron Bank Sandbox,
            owner_picture_url=,
            owner_status=active,
            owner_type=project,
            created=2022-01-01 00:00:00
        )
    ],
    rules=[
        CorporateRule(
            id=6067428166893568,
            name=General USD,
            amount=100000,
            interval=day,
            schedule=,
            purposes=[],
            currency_code=USD,
            currency_symbol=US$,
            currency_name=American Dollar,
            counter_amount=0,
            categories=[MerchantCategory(code=fastFoodRestaurants, type=food)],
            countries=[MerchantCountry(code=USA)],
            methods=[CardMethod(code=token)]
        )
    ],
    updated=2022-01-01 00:00:00,
    created=2022-01-01 00:00:00
)
```

### Update a Corporate Holder

`PATCH /v2/corporate-holder/:id`

Update a single corporate holder. At least one updatable parameter must be informed.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the corporate holder entity. |
| `centerId` | OPTIONAL | Id of the new target cost center. Example: "5656565656565656". |
| `name` | OPTIONAL | New card holder name. It must be unique among the active holders of your Workspace. Example: "Iron Bank S.A.". |
| `permissions` | OPTIONAL | New array of permission objects. It replaces the current permissions of the holder. Example: ``` [{"ownerType": "project", "ownerId": "6253551860842496"}] ``` |
| `rules` | OPTIONAL | New array of rule objects with the spending rules of the holder. Example: ``` [{"name": "General USD", "interval": "day", "amount": 100000, "currencyCode": "USD"}] ``` |
| `status` | OPTIONAL | You may block the holder by passing "blocked" in the status, and unblock it by passing "active". |
| `tags` | OPTIONAL | New array of up to 100 strings to tag the holder. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

holder = starkbank.corporateholder.update(
    "5155165527080960",
    status="blocked"
)

print(holder)
```

**Response**

```python
CorporateHolder(
    id=5155165527080960,
    name=Iron Bank S.A.,
    center_id=,
    status=blocked,
    tags=['traveler employee'],
    permissions=[
        Permission(
            owner_email=,
            owner_id=6253551860842496,
            owner_name=Iron Bank Sandbox,
            owner_picture_url=,
            owner_status=active,
            owner_type=project,
            created=2022-01-01 00:00:00
        )
    ],
    rules=[
        CorporateRule(
            id=6067428166893568,
            name=General USD,
            amount=100000,
            interval=day,
            schedule=,
            purposes=[],
            currency_code=USD,
            categories=[MerchantCategory(code=fastFoodRestaurants, type=)],
            countries=[MerchantCountry(code=USA)],
            methods=[CardMethod(code=token)]
        )
    ],
    updated=2022-01-02 00:00:00,
    created=2022-01-01 00:00:00
)
```

### Cancel a Corporate Holder

`DELETE /v2/corporate-holder/:id`

Cancel a single corporate holder by its id. Canceling a holder also removes every permission granted on it. This action is irreversible.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the corporate holder entity to cancel. |

**Request**

```python
import starkbank

holder = starkbank.corporateholder.cancel("5155165527080960")

print(holder)
```

**Response**

```python
CorporateHolder(
    id=5155165527080960,
    name=Iron Bank S.A.,
    center_id=,
    status=canceled,
    tags=['traveler employee'],
    permissions=[],
    rules=[
        CorporateRule(
            id=6067428166893568,
            name=General USD,
            amount=100000,
            interval=day,
            schedule=,
            purposes=[],
            currency_code=USD,
            categories=[MerchantCategory(code=fastFoodRestaurants, type=)],
            countries=[MerchantCountry(code=USA)],
            methods=[CardMethod(code=token)]
        )
    ],
    updated=2022-01-03 00:00:00,
    created=2022-01-01 00:00:00
)
```

### List Corporate Holder Logs

`GET /v2/corporate-holder/log`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `holderIds` | OPTIONAL | Array of up to 30 corporate holder ids that are linked to the logs you desire. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. Options: "created", "blocked", "unblocked", "updated", "canceled". |

**Request**

```python
import starkbank

logs = starkbank.corporateholder.log.query(
    limit=10,
    types=["blocked"]
)

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

**Response**

```python
Log(
    id=6299741604282368,
    type=blocked,
    holder=CorporateHolder(
        id=5155165527080960,
        name=Iron Bank S.A.,
        center_id=,
        status=blocked,
        tags=['traveler employee'],
        permissions=[],
        rules=[],
        updated=2022-01-02 00:00:00,
        created=2022-01-01 00:00:00
    ),
    created=2022-01-02 00:00:00
)
```

### Get a Corporate Holder Log

`GET /v2/corporate-holder/log/:id`

Get a single corporate holder log by its id.

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.corporateholder.log.get("6299741604282368")

print(log)
```

**Response**

```python
Log(
    id=6299741604282368,
    type=blocked,
    holder=CorporateHolder(
        id=5155165527080960,
        name=Iron Bank S.A.,
        center_id=,
        status=blocked,
        tags=['traveler employee'],
        permissions=[],
        rules=[],
        updated=2022-01-02 00:00:00,
        created=2022-01-01 00:00:00
    ),
    created=2022-01-02 00:00:00
)
```

## Corporate Rule

The Corporate Rule resource displays the spending rules of the Corporate Cards and [Corporate Holders](#corporate-holder) created in your [Workspace](#workspace).

Each rule sets the maximum amount that can be spent in an interval and may also restrict the merchant categories, the countries, the card purchase methods and the purposes that are accepted, as well as the days and hours in which the card can be used.

Corporate Rules are not created on their own. You inform them in the rules parameter when you create or update a Corporate Holder and when you update a Corporate Card: rules informed on a holder apply to every card bound to it, rules informed on a card apply to that card only, and both are verified on every purchase.

**NOTE:**Inform "expand=rules" when you read a card or a holder to also receive the amount already spent in the current interval and the full currency, category, country and method data of each rule.

### The Corporate Rule object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the corporate rule, returned when the rule is created and used to update it later. Example: "6539357404889088". |
| `name` | STRING | Rule name. Example: "General BRL". |
| `interval` | STRING | Interval after which the rule amount counter is reset to 0. Options: "instant", "day", "week", "month", "year", "lifetime". Example: "day". |
| `amount` | INTEGER | Maximum amount in cents that can be spent in the informed interval. 0 sets no amount limit. Example: 200000 (R$2000.00). |
| `currencyCode` | STRING | Code of the currency the rule amount refers to. Example: "BRL". |
| `schedule` | STRING | Days and hours in which the rule is active. Empty when the rule is always active. Example: "every monday, wednesday from 00:00 to 23:59 in America/Sao_Paulo". |
| `purposes` | LIST OF STRINGS | Purchase purposes accepted by the rule. Use it to restrict ATM withdrawals. An empty list accepts every purpose. Options: "purchase", "withdrawal", "verification". Example: ["purchase", "withdrawal"]. |
| `categories` | LIST OF OBJECTS | Merchant categories accepted by the rule, each with a code or a type. An empty list accepts every category. See the Merchant Category resource for the available codes and types. Example: [{"code": "fastFoodRestaurants"}]. |
| `countries` | LIST OF OBJECTS | Merchant countries accepted by the rule, each with a code. An empty list accepts every country. See the Merchant Country resource for the available codes. Example: [{"code": "BRA"}]. |
| `methods` | LIST OF OBJECTS | Card purchase methods accepted by the rule, each with a code. An empty list accepts every method. See the Card Method resource for the available codes. Example: [{"code": "token"}]. |
| `merchants` | LIST OF OBJECTS | Merchants accepted by the rule, each with an id. An empty list accepts every merchant. Not available in the SDKs. |
| `counterAmount` | INTEGER | Amount in cents already spent in the current interval. Returned only when you inform "expand=rules". Example: 1000 (R$10.00). |
| `currencyName` | STRING | Name of the rule currency. Returned only when you inform "expand=rules". Example: "Brazilian Real". |
| `currencySymbol` | STRING | Symbol of the rule currency. Returned only when you inform "expand=rules". Example: "R$". |

## Corporate Purchase

The Corporate Purchase resource displays the purchases made with the corporate cards issued in your [Workspace](#workspace).

You never create a purchase yourself. A purchase shows up when a cardholder pays at a merchant and the authorization request reaches us: we check it against the card and holder rules, answer the card network and register the resulting purchase here.

All amounts are integers in cents. When the purchase is made in another currency, the same money is recorded twice: merchantAmount (in merchantCurrencyCode) is what the merchant charged and issuerAmount (in issuerCurrencyCode) is what was debited from your corporate balance after conversion, with the IOF in tax.

You can list purchases, get a single purchase by its id, update its description and tags and follow its whole life cycle through the logs.

### The Corporate Purchase object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the corporate purchase. Example: "5353197895942144". |
| `amount` | INTEGER | Purchase amount in cents. Minimum = 0. Example: 12345 (R$123.45). |
| `attachments` | LIST OF OBJECTS | List of attachment objects linked to the purchase, each one with an id and a name. |
| `cardEnding` | STRING | Last 4 digits of the card number used in the purchase. Example: "1234". |
| `cardId` | STRING | Id of the corporate card used in the purchase. Example: "5671893688385536". |
| `centerId` | STRING | Id of the cost center the purchase was charged to. Empty string when the holder has no cost center. Example: "5656565656565656". |
| `centerName` | STRING | Name of the cost center the purchase was charged to. Returned only when you pass expand=centerName. Example: "Engineering". |
| `corporateTransactionIds` | LIST OF STRINGS | Ids of the corporate ledger transactions linked to this purchase. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `description` | STRING | Purchase description. Empty string until you set one. Example: "Team lunch". |
| `holderId` | STRING | Id of the cardholder. Example: "5917814565109760". |
| `holderName` | STRING | Name of the cardholder. Example: "Tony Stark". |
| `installmentCount` | INTEGER | Number of installments the purchase was split into. Example: 1. |
| `issuerAmount` | INTEGER | Amount in cents in the issuer currency, debited from your corporate balance. Example: 12345 (R$123.45). |
| `issuerCurrencyCode` | STRING | ISO 4217 currency code of the issuer. Example: "BRL". |
| `issuerCurrencySymbol` | STRING | Currency symbol of the issuer. Example: "R$". |
| `merchantAmount` | INTEGER | Amount in cents in the merchant currency. Example: 12345 (R$123.45). |
| `merchantCategoryCode` | STRING | Merchant category code (MCC) of the purchase. Example: "fastFoodRestaurants". |
| `merchantCategoryNumber` | STRING | Number of the merchant category code. Example: "5814". |
| `merchantCategoryType` | STRING | Type of the merchant category. Example: "food". |
| `merchantCountryCode` | STRING | ISO 3166 country code of the merchant. Example: "BRA". |
| `merchantCurrencyCode` | STRING | ISO 4217 currency code of the merchant. Example: "BRL". |
| `merchantCurrencySymbol` | STRING | Currency symbol of the merchant. Example: "R$". |
| `merchantDisplayName` | STRING | Merchant name ready to be displayed to your users. Falls back to the merchant category name followed by the merchant id when the merchant name is unknown. Example: "COMPANY 123". |
| `merchantDisplayUrl` | STRING | Public URL of the merchant icon (png image). Example: "https://sandbox.api.starkbank.com/v2/corporate-icon/type/food.png". |
| `merchantFee` | INTEGER | Fee charged by the merchant in cents to cover specific costs, such as ATM withdrawal logistics. Example: 200 (R$2.00). |
| `merchantName` | STRING | Merchant name as informed by the card network. Example: "COMPANY 123". |
| `methodCode` | STRING | Method used in the purchase. Options: "ocr", "chip", "token", "server", "manual", "unknown", "barcode", "magstripe", "contactless". |
| `status` | STRING | Current purchase status. Options: "approved", "canceled", "denied", "confirmed", "voided". |
| `tags` | LIST OF STRINGS | Tags associated with the purchase. Example: ["travel", "food"]. |
| `tax` | INTEGER | IOF amount in cents taxed on international purchases. Example: 638 (R$6.38). |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Corporate Purchases

`GET /v2/corporate-purchase`

Use this route to get a list of corporate purchases in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. Example: "2022-01-01". |
| `before` | OPTIONAL | Filter entities created before this date. Example: "2022-01-20". |
| `cardIds` | OPTIONAL | Filter purchases by the ids of the cards used. Max = 30 ids. |
| `centerIds` | OPTIONAL | Filter purchases by the ids of the cost centers they were charged to. Max = 30 ids. Not available in the SDKs. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `expand` | OPTIONAL | List of strings to add extra keys to the response JSON. Options: "centerName". Not available in the SDKs. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `holderIds` | OPTIONAL | Filter purchases by the ids of the cardholders. Max = 30 ids. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. Max = 100 ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default = 100. |
| `merchantCategoryTypes` | OPTIONAL | Filter purchases by the types of the merchant categories. Example: "food", "health", "transportation". |
| `status` | OPTIONAL | Filter purchases by the specified status. Options: "approved", "canceled", "denied", "confirmed", "voided". |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. Max = 30 tags. Not available in the SDKs. |

**Request**

```python
import starkbank

purchases = starkbank.corporatepurchase.query(
    after="2022-01-01",
    before="2022-01-20",
    limit=10
)

for purchase in purchases:
    print(purchase)
```

**Response**

```python
CorporatePurchase(
    amount=12345,
    card_ending=1234,
    card_id=5671893688385536,
    center_id=5656565656565656,
    corporate_transaction_ids=['5415434763141120'],
    created=2022-01-01 00:00:00,
    description=Team lunch,
    holder_id=5917814565109760,
    holder_name=Tony Stark,
    id=5353197895942144,
    issuer_amount=12345,
    issuer_currency_code=BRL,
    issuer_currency_symbol=R$,
    merchant_amount=12345,
    merchant_category_code=fastFoodRestaurants,
    merchant_category_type=food,
    merchant_country_code=BRA,
    merchant_currency_code=BRL,
    merchant_currency_symbol=R$,
    merchant_display_name=COMPANY 123,
    merchant_display_url=https://sandbox.api.starkbank.com/v2/corporate-icon/type/food.png,
    merchant_fee=0,
    merchant_name=COMPANY 123,
    method_code=chip,
    status=approved,
    tags=['travel', 'food'],
    tax=0,
    updated=2022-01-01 00:00:00
)
```

### Get a Corporate Purchase

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

Use this route to get a single corporate purchase by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the corporate purchase entity. Example: "5353197895942144". |
| `expand` | OPTIONAL | List of strings to add extra keys to the response JSON. Options: "centerName". Not available in the SDKs. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

purchase = starkbank.corporatepurchase.get("5353197895942144")

print(purchase)
```

**Response**

```python
CorporatePurchase(
    amount=12345,
    card_ending=1234,
    card_id=5671893688385536,
    center_id=5656565656565656,
    corporate_transaction_ids=['5415434763141120'],
    created=2022-01-01 00:00:00,
    description=Team lunch,
    holder_id=5917814565109760,
    holder_name=Tony Stark,
    id=5353197895942144,
    issuer_amount=12345,
    issuer_currency_code=BRL,
    issuer_currency_symbol=R$,
    merchant_amount=12345,
    merchant_category_code=fastFoodRestaurants,
    merchant_category_type=food,
    merchant_country_code=BRA,
    merchant_currency_code=BRL,
    merchant_currency_symbol=R$,
    merchant_display_name=COMPANY 123,
    merchant_display_url=https://sandbox.api.starkbank.com/v2/corporate-icon/type/food.png,
    merchant_fee=0,
    merchant_name=COMPANY 123,
    method_code=chip,
    status=approved,
    tags=['travel', 'food'],
    tax=0,
    updated=2022-01-01 00:00:00
)
```

### Update a Corporate Purchase

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

Use this route to update the description and the tags of a corporate purchase. A purchase is settled by the card network, so every other field is read-only.

**NOTE:**Each update creates an updated log, and the request body must contain at least one of description or tags.

This route is not yet mapped by our SDKs.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the corporate purchase entity. Example: "5353197895942144". |
| `description` | OPTIONAL | New description for the purchase. Max of 140 characters. Example: "Team lunch". |
| `tags` | OPTIONAL | New array of strings to tag the purchase. Max of 100 tags of up to 100 characters each. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

purchase = starkbank.request.patch(
    path="/corporate-purchase/5353197895942144",
    body={
        "description": "Team lunch",
        "tags": ["travel", "food"]
    }
).json()

print(purchase)
```

**Response**

```python
{
    'message': 'Purchase successfully updated.',
    'purchase': {
        'amount': 12345,
        'attachments': [],
        'cardEnding': '1234',
        'cardId': '5671893688385536',
        'centerId': '5656565656565656',
        'corporateTransactionIds': ['5415434763141120'],
        'created': '2022-01-01T00:00:00.000000+00:00',
        'description': 'Team lunch',
        'holderId': '5917814565109760',
        'holderName': 'Tony Stark',
        'id': '5353197895942144',
        'installmentCount': 1,
        'issuerAmount': 12345,
        'issuerCurrencyCode': 'BRL',
        'issuerCurrencySymbol': 'R$',
        'merchantAmount': 12345,
        'merchantCategoryCode': 'fastFoodRestaurants',
        'merchantCategoryNumber': '5814',
        'merchantCategoryType': 'food',
        'merchantCountryCode': 'BRA',
        'merchantCurrencyCode': 'BRL',
        'merchantCurrencySymbol': 'R$',
        'merchantDisplayName': 'COMPANY 123',
        'merchantDisplayUrl': 'https://sandbox.api.starkbank.com/v2/corporate-icon/type/food.png',
        'merchantFee': 0,
        'merchantName': 'COMPANY 123',
        'methodCode': 'chip',
        'status': 'approved',
        'tags': ['travel', 'food'],
        'tax': 0,
        'updated': '2022-01-02T12:30:00.000000+00:00'
    }
}
```

### List Corporate Purchase Logs

`GET /v2/corporate-purchase/log`

Use this route to get a paged list of corporate purchase logs. A log tracks a change in the corporate purchase entity according to its life cycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. Example: "2022-01-01". |
| `before` | OPTIONAL | Filter entities created before this date. Example: "2022-01-20". |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default = 100. |
| `purchaseIds` | OPTIONAL | Array of corporate purchase ids that are linked to the logs you desire. Max = 30 ids. |
| `types` | OPTIONAL | Filters logs by log types. Options: "approved", "denied", "canceled", "confirmed", "reversed", "voided", "updated". |

**Request**

```python
import starkbank

logs = starkbank.corporatepurchase.log.query(
    purchase_ids=["5353197895942144"],
    limit=10
)

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

**Response**

```python
Log(
    corporate_transaction_id=5415434763141120,
    created=2022-01-01 00:00:00,
    description=Purchase approved: R$ 123,45.,
    errors=[],
    id=6531653149130752,
    purchase=CorporatePurchase(amount=12345, card_id=5671893688385536, holder_name=Tony Stark, ...),
    type=approved
)
```

### Get a Corporate Purchase Log

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

Use this route to get a single corporate purchase log by its id.

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.corporatepurchase.log.get("6531653149130752")

print(log)
```

**Response**

```python
Log(
    corporate_transaction_id=5415434763141120,
    created=2022-01-01 00:00:00,
    description=Purchase approved: R$ 123,45.,
    errors=[],
    id=6531653149130752,
    purchase=CorporatePurchase(amount=12345, card_id=5671893688385536, holder_name=Tony Stark, ...),
    type=approved
)
```

## Corporate Invoice

The Corporate Invoice resource is used to add funds to your Corporate balance.

Create a Corporate Invoice to receive a Pix BR Code that you can pay from an account you hold in any bank. Once the Corporate Invoice is paid, the funds land in your Corporate balance and become available for card spending.

The payer name and tax ID are always taken from your [Workspace](#workspace) owner, so you only need to inform the amount you want to load.

### The Corporate Invoice object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `amount` | INTEGER | Corporate Invoice value in cents. Example: 1234 (R$12.34). |
| `brcode` | STRING | BR Code for the Corporate Invoice Pix payment. |
| `corporateTransactionId` | STRING | Id of the Corporate Transaction created when the Corporate Invoice is paid. Empty while the Corporate Invoice has not been paid. |
| `created` | STRING | Creation datetime. Example: "2023-05-10T17:10:57.261868+00:00". |
| `due` | STRING | Corporate Invoice due and expiration datetime. Example: "2023-05-17T17:10:57.261868+00:00". |
| `id` | STRING | Unique id for the Corporate Invoice. |
| `link` | STRING | Public URL to the Corporate Invoice payment page. |
| `name` | STRING | Payer full name, taken from your Workspace owner. Example: "Iron Bank S.A.". |
| `status` | STRING | Current Corporate Invoice status. Options: "created", "expired", "overdue", "paid". |
| `tags` | LIST OF STRINGS | Tags associated with the Corporate Invoice. All tags are returned in lowercase. |
| `taxId` | STRING | Payer CPF or CNPJ, taken from your Workspace owner. Example: "20.018.183/0001-80". |
| `updated` | STRING | Last update datetime. Example: "2023-05-10T17:10:57.261877+00:00". |

### Create a Corporate Invoice

`POST /v2/corporate-invoice`

Use this route to create a new Corporate Invoice and receive the BR Code you should pay to load your Corporate balance.

**NOTE:**The payer name and tax ID are always filled in with your [Workspace](#workspace) owner's data, so they cannot be sent in the request. The Corporate Invoice is due 7 days after creation and cannot be paid after that.

**NOTE:**You cannot create a Corporate Invoice while your Workspace has a pending or overdue Corporate Billing [Invoice](#invoice).

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | A positive integer that represents the amount in cents to be loaded into your Corporate balance. Example: 10000 (R$100.00) |
| `tags` | OPTIONAL | Array of up to 100 strings to tag the entity for future queries. Each tag can have up to 100 characters and all tags will be converted to lowercase. Example: ["travel", "food"] |

**Request**

```python
import starkbank

invoice = starkbank.corporateinvoice.create(
    invoice=starkbank.CorporateInvoice(
        amount=10000,
        tags=["travel", "food"]
    )
)

print(invoice)
```

**Response**

```python
CorporateInvoice(
    amount=10000,
    brcode=00020101021226930014br.gov.bcb.pix2571brcode-h.sandbox.starkbank.com/v2/d7f6546e194d4c64a153e8f79f1c41ac5204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63042109,
    corporate_transaction_id=,
    created=2023-05-10 17:10:57.261868+00:00,
    due=2023-05-17 17:10:57.261868+00:00,
    id=5656565656565656,
    link=https://starkbank-card-issuer.sandbox.starkbank.com/invoicelink/d7f6546e194d4c64a153e8f79f1c41ac,
    name=Iron Bank S.A.,
    status=created,
    tags=['travel', 'food'],
    tax_id=20.018.183/0001-80,
    updated=2023-05-10 17:10:57.261877+00:00
)
```

### List Corporate Invoices

`GET /v2/corporate-invoice`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default value = 100. |
| `status` | OPTIONAL | Filter Corporate Invoices by the specified status. Options: "created", "expired", "overdue", "paid". |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

invoices = starkbank.corporateinvoice.query(
    after="2023-05-01",
    before="2023-05-30",
    limit=10
)

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

**Response**

```python
CorporateInvoice(
    amount=10000,
    brcode=00020101021226930014br.gov.bcb.pix2571brcode-h.sandbox.starkbank.com/v2/d7f6546e194d4c64a153e8f79f1c41ac5204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63042109,
    corporate_transaction_id=6341320293482496,
    created=2023-05-10 17:10:57.261868+00:00,
    due=2023-05-17 17:10:57.261868+00:00,
    id=5656565656565656,
    link=https://starkbank-card-issuer.sandbox.starkbank.com/invoicelink/d7f6546e194d4c64a153e8f79f1c41ac,
    name=Iron Bank S.A.,
    status=paid,
    tags=['travel', 'food'],
    tax_id=20.018.183/0001-80,
    updated=2023-05-11 09:22:14.113450+00:00
)
```

## Corporate Withdrawal

The Corporate Withdrawal resource is used to return cash from your Corporate balance to your Banking balance.

Each Corporate Withdrawal debits your Corporate balance right away, creating a [Corporate Transaction](#corporate-transaction), and then credits the same amount to your Banking balance, creating a [Transaction](#transaction).

**NOTE:**You choose the externalId of every Corporate Withdrawal, and it must be unique within your [Workspace](#workspace), so a retried request never withdraws the same cash twice.

### The Corporate Withdrawal object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `amount` | INTEGER | Corporate Withdrawal value in cents. Example: 1234 (R$12.34). |
| `corporateTransactionId` | STRING | Id of the Corporate Transaction that debited this amount from your Corporate balance. |
| `created` | STRING | Creation datetime. Example: "2023-05-10T17:10:57.261868+00:00". |
| `externalId` | STRING | Unique id you chose for the Corporate Withdrawal. Example: "my-external-id". |
| `id` | STRING | Unique id for the Corporate Withdrawal. |
| `tags` | LIST OF STRINGS | Tags associated with the Corporate Withdrawal. All tags are returned in lowercase. |
| `transactionId` | STRING | Id of the Transaction created when the cash lands in your Banking balance. Empty while the Corporate Withdrawal has not been processed. |
| `updated` | STRING | Last update datetime. Example: "2023-05-10T17:10:57.261877+00:00". |

### Create a Corporate Withdrawal

`POST /v2/corporate-withdrawal`

Use this route to create a new Corporate Withdrawal and return cash from your Corporate balance to your Banking balance.

**NOTE:**The [Corporate Transaction](#corporate-transaction) that debits your Corporate balance is created within the same request, so corporateTransactionId comes back filled. The cash is credited to your Banking balance right after, so transactionId comes back empty and is filled in a few moments later.

**NOTE:**The request is refused when your Corporate balance does not cover the amount.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | A positive integer that represents the amount in cents to be returned to your Banking balance. Example: 10000 (R$100.00) |
| `externalId` | REQUIRED | Unique id chosen by you to identify the Corporate Withdrawal. An externalId already used in your Workspace is rejected instead of creating a second Corporate Withdrawal. Example: "my-external-id" |
| `tags` | OPTIONAL | Array of up to 100 strings to tag the entity for future queries. Each tag can have up to 100 characters and all tags will be converted to lowercase. Example: ["tony", "stark"] |

**Request**

```python
import starkbank

withdrawal = starkbank.corporatewithdrawal.create(
    withdrawal=starkbank.CorporateWithdrawal(
        amount=10000,
        external_id="my-external-id",
        tags=["tony", "stark"]
    )
)

print(withdrawal)
```

**Response**

```python
CorporateWithdrawal(
    amount=10000,
    corporate_transaction_id=6341320293482496,
    created=2023-05-10 17:10:57.261868+00:00,
    external_id=my-external-id,
    id=5656565656565656,
    tags=['tony', 'stark'],
    transaction_id=,
    updated=2023-05-10 17:10:57.261877+00:00
)
```

### List Corporate Withdrawals

`GET /v2/corporate-withdrawal`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default value = 100. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

withdrawals = starkbank.corporatewithdrawal.query(
    after="2023-05-01",
    before="2023-05-30",
    limit=10
)

for withdrawal in withdrawals:
    print(withdrawal)
```

**Response**

```python
CorporateWithdrawal(
    amount=10000,
    corporate_transaction_id=6341320293482496,
    created=2023-05-10 17:10:57.261868+00:00,
    external_id=my-external-id,
    id=5656565656565656,
    tags=['tony', 'stark'],
    transaction_id=6307474720260096,
    updated=2023-05-10 17:11:31.884502+00:00
)
```

### Get a Corporate Withdrawal

`GET /v2/corporate-withdrawal/:id`

Get a single Corporate Withdrawal by its id.

**Parameters**

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

**Request**

```python
import starkbank

withdrawal = starkbank.corporatewithdrawal.get("5155165527080960")

print(withdrawal)
```

**Response**

```python
CorporateWithdrawal(
    amount=10000,
    corporate_transaction_id=6341320293482496,
    created=2023-05-10 17:10:57.261868+00:00,
    external_id=my-external-id,
    id=5155165527080960,
    tags=['tony', 'stark'],
    transaction_id=6307474720260096,
    updated=2023-05-10 17:11:31.884502+00:00
)
```

## Corporate Balance

The Corporate Balance resource displays the current corporate balance of your workspace, which is the result of the sum of all [Corporate Transactions](#corporate-transaction) within this workspace.

This balance is separate from your main Stark Bank balance and is the money available to run card authorizations.

The balance is never generated by you, but it can be retrieved to see the available information.

**Note:** Add money to your corporate balance with [Corporate Invoices](#corporate-invoice) and send money back to your workspace with [Corporate Withdrawals](#corporate-withdrawal).

### The Corporate Balance object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the corporate balance, which is the id of your workspace. Example: "5155165527080960". |
| `amount` | INTEGER | Current corporate balance amount of the workspace in cents. Example: 5000000 (R$50,000.00). |
| `limit` | INTEGER | Maximum negative balance allowed by you, capped by maxLimit. Example: 5000000 (R$50,000.00). |
| `maxLimit` | INTEGER | Maximum negative balance allowed by Stark Bank. Example: 10000000 (R$100,000.00). |
| `currency` | STRING | Currency code of the corporate balance. Expect others to be added eventually. Example: "BRL". |
| `updated` | STRING | Latest update datetime for the corporate balance. Example: "2023-05-10T14:32:20.912604+00:00". |

### Get the Corporate Balance

`GET /v2/corporate-balance`

Get the current corporate balance in your workspace.

**NOTE:** This route requires a project or member with permission to view transactions. Requests without it fail with an invalid permission error.

**Request**

```python
import starkbank

balance = starkbank.corporatebalance.get()

print(balance)
```

**Response**

```python
CorporateBalance(
    amount=5000000,
    currency=BRL,
    id=5155165527080960,
    limit=5000000,
    max_limit=10000000,
    updated=2023-05-10 14:32:20.912604
)
```

## Corporate Transaction

The Corporate Transaction resource represents each balance shift in your corporate ledger.

Every corporate purchase, corporate withdrawal, corporate invoice payment and billing invoice cashback creates a Corporate Transaction, so you can use this resource to reconcile your corporate balance and understand your corporate statement.

**NOTE:**Corporate Transactions are created by Stark Bank as a consequence of other events. There is no route to create, update or cancel them.

### The Corporate Transaction object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the corporate transaction. Example: "5656565656565656". |
| `amount` | INTEGER | Corporate Transaction value in cents. It is positive for credits and negative for debits. Example: 1234 (R$12.34). |
| `balance` | INTEGER | Balance amount of the Workspace in cents at the instant of the corporate transaction. Example: 200 (R$2.00). |
| `description` | STRING | Corporate Transaction description. Example: "Buying food". |
| `source` | STRING | Source of the corporate transaction. Example: "corporate-purchase/5656565656565656". |
| `tags` | LIST OF STRINGS | List of strings inherited from the source resource. Example: ["tony", "stark"]. |
| `created` | STRING | Creation datetime. Example: "2020-03-10T10:30:00.000000+00:00". |

### List Corporate Transactions

`GET /v2/corporate-transaction`

Get a list of corporate transactions in chunks of at most 1000. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 1000. |
| `source` | OPTIONAL | Filter entities created by a single source resource. Example: "corporate-purchase/5730174175805440" |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank
from datetime import date

transactions = starkbank.corporatetransaction.query(
    after=date(2022, 3, 1),
    before=date(2022, 3, 31),
    limit=10
)

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

**Response**

```python
CorporateTransaction(
    amount=-9000,
    balance=1291000,
    created=2022-03-10 10:30:00.000000,
    description=Pizzaria Dom Domingos,
    id=5155165527080960,
    source=corporate-purchase/5730174175805440,
    tags=['corporate-holder/5484278772695040', 'corporate-card/5673295890087936']
)
```

### Get a Corporate Transaction

`GET /v2/corporate-transaction/:id`

Get a single corporate transaction by its id.

**Parameters**

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

**Request**

```python
import starkbank

transaction = starkbank.corporatetransaction.get("5155165527080960")

print(transaction)
```

**Response**

```python
CorporateTransaction(
    amount=-9000,
    balance=1291000,
    created=2022-03-10 10:30:00.000000,
    description=Pizzaria Dom Domingos,
    id=5155165527080960,
    source=corporate-purchase/5730174175805440,
    tags=['corporate-holder/5484278772695040', 'corporate-card/5673295890087936']
)
```

## Card Method

The Card Method resource is used to query the card purchase methods available in the Stark Bank API.

Card Method codes are used to define purchase method filters in [Corporate Rules](#corporate-rule).

**Note:** Card Methods are never created by you. They are an enum served by the API, so this resource is query-only.

### The Card Method object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `code` | STRING | Method's code. Options: "chip", "token", "server", "manual", "magstripe", "contactless". Example: "token". |
| `name` | STRING | Method's name, translated to the language of the Accept-Language header. Example: "token". |
| `number` | STRING | Method's number. Example: "81". |

### List Card Methods

`GET /v2/card-method`

Use this route to list the card purchase methods available in the Stark Bank API.

**NOTE:** This route returns the full enum in a single response. It is not paginated, so it accepts no limit or cursor parameters and returns no cursor.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `search` | OPTIONAL | Keyword to search for code, name or number. The match is case- and accent-insensitive. Example: "token" |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

methods = starkbank.cardmethod.query(search="token")

for method in methods:
    print(method)
```

**Response**

```python
CardMethod(
    code=token,
    name=token,
    number=81
)
```

## Merchant Category

The Merchant Category resource is used to query the merchant categories available in the Stark Bank API.

A category is identified either by its code, which specifies a single MCC, or by its type, which defines an entire group of merchant codes, such as "food" or "services".

Use these codes and types to define the category filters of the spending rules of your [Corporate Holder](#corporate-holder) resource and Corporate Card resource. A category filter must define exactly one parameter between code and type.

**Note:** Merchant Categories are never created by you. They are an enum served by the API, so this resource is query-only.

### The Merchant Category object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `code` | STRING | Category's code, which specifies a single MCC. Example: "fastFoodRestaurants". |
| `type` | STRING | Category's type, which defines an entire group of merchant codes. Options: "unknown", "pets", "food", "fuel", "retail", "health", "hotels", "leisure", "services", "clothing", "gambling", "airlines", "carRental", "education", "groceries", "financial", "government", "organizations", "transportation". Example: "food". |
| `name` | STRING | Category's name, translated to the language of the Accept-Language header. Example: "Fast food restaurants". |
| `number` | STRING | Category's number. Example: "5814". |

### List Merchant Categories

`GET /v2/merchant-category`

Use this route to list the merchant categories available in the Stark Bank API. Either codes, which specify single MCCs, or types, which define entire groups of merchant codes, will be accepted as category filters in your spending rules.

**NOTE:** This route returns the full enum in a single response. It is not paginated, so it accepts no limit or cursor parameters and returns no cursor.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `search` | OPTIONAL | Keyword to search for code, type, name or number. The match is case- and accent-insensitive. Example: "food" |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

categories = starkbank.merchantcategory.query(
    search="food"
)

for category in categories:
    print(category)
```

**Response**

```python
MerchantCategory(
    code=fastFoodRestaurants,
    type=food,
    name=Fast food restaurants,
    number=5814
)
```

## Merchant Country

The Merchant Country resource is used to query the countries available in the Stark Bank API.

Merchant Country codes are used to define country filters in [Corporate Rules](#corporate-rule).

**Note:** Merchant Countries are never created by you. They are an enum served by the API, so this resource is query-only.

### The Merchant Country object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `code` | STRING | Country's code. This is the only parameter you send when you use a country in a Corporate Rule. Example: "BRA". |
| `name` | STRING | Country's name, translated to the language of the Accept-Language header. Example: "Brazil". |
| `number` | STRING | Country's number. Example: "076". |
| `shortCode` | STRING | Country's short code. Example: "BR". |

### List Merchant Countries

`GET /v2/merchant-country`

Use this route to list the countries available in the Stark Bank API. Use the returned codes to define the country filters of your spending rules.

**NOTE:** This route returns the full enum in a single response. It is not paginated, so it accepts no limit or cursor parameters and returns no cursor.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `search` | OPTIONAL | Keyword to search for code, name, number or short code. The match is case- and accent-insensitive. Example: "brazil" |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

countries = starkbank.merchantcountry.query(
    search="brazil"
)

for country in countries:
    print(country)
```

**Response**

```python
MerchantCountry(
    code=BRA,
    name=Brazil,
    number=076,
    short_code=BR
)
```

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

If you send money repeatedly to the same receiver, you can confirm the account once with a [Verified Account](#verified-account) and then pay it with a [Verified Transfer](#verified-transfer), which creates a regular Transfer tagged with "verified-account/<accountId>".

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `accountNumber` | REQUIRED | Receiver bank account number. Use "-" before the validation digit. Example: 876543-2. |
| `amount` | REQUIRED | A positive integer that represents the amount in cents to be transferred. Example: 100 (R$1.00) |
| `bankCode` | REQUIRED | Besides informing the receiver bank, this parameter specifies whether this will be a Pix or a Ted transfer. If you wish to send a Pix, pass the bank ISPB (8 digits). Example: 20018183 = StarkBank. If you wish to send a Ted, pass the usual bank code (1 to 3 digits). Example: 665 = Stark |
| `branchCode` | REQUIRED | Receiver bank account branch. Use "-" in case there is a validation digit. Example: 1234-5 |
| `name` | REQUIRED | Receiver full name. Example: "Joana da Silva" |
| `taxId` | REQUIRED | Receiver CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90 |
| `accountType` | OPTIONAL | Receiver bank account type. Options are "checking", "payment", "savings" and "salary". "checking" is the default. This parameter only has effect on Pix Transfers. |
| `description` | OPTIONAL | Optional description to override default description to be shown in the bank statement. Example: "Payment for service #1234" |
| `displayDescription` | OPTIONAL | Description to be shown in the receiver bank interface. ex: "Payment for service #1234" |
| `externalId` | OPTIONAL | Unique ID to prevent duplicate transfers. Repeated externalIds should cause failures by duplication. By default, it blocks transfers to the same bank account with the same amount on the same day. Example: "my-internal-id-123456" |
| `rules` | OPTIONAL | List of rules for modifying transfer behavior. Example: ``` [{"key": "resendingLimit", "value": 5}] ``` |
| `scheduled` | OPTIONAL | Schedule the transfer for a specific date. Today is the default. Ted Transfer's schedules for today will be accepted until 16:00 (BRT) and will be pushed to the next business day afterwards. Pix Transfers are available 24/7 and can be scheduled for any date and time. Example: "2020-08-14T15:23:26+00:00" or "2020-08-14" |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `sort` | OPTIONAL | Sort order considered in the response. Options are: "created", "-created", "updated" and "-updated". "-" means descending order. Default is "-created". |
| `status` | OPTIONAL | Filter transfers by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `taxId` | OPTIONAL | Filter transfers sent to the specified tax ID. |
| `transactionIds` | OPTIONAL | List of transaction IDs linked to the desired transfers. |

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

**Parameters**

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

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

**Parameters**

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

**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. A receipt only exists while the transfer status is "processing" or "success".

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `transferIds` | OPTIONAL | Array of transfer ids that are linked to the logs you desire. |
| `types` | OPTIONAL | Filters logs by log types. |

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

**Parameters**

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

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

## Verified Account

Verified Accounts let you confirm that a bank account really belongs to a given tax ID before you send money to it.

You can verify an account in two ways: by informing the receiver's Pix key, or by informing the receiver's full bank details. Either way, we send a R$0.01 verification transfer to the account and only mark it as "active" if that transfer succeeds.

Once a Verified Account is active, you can use its id to create **[Verified Transfers](#verified-transfer)**, which reuse the verified receiver data instead of asking you for it again.

### The Verified Account object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `bankCode` | STRING | Receiver bank code or ISPB. Empty while an account verified by Pix key has not been resolved. |
| `bankName` | STRING | Name of the receiver bank institution. We fill it in when we resolve a Pix key. It stays empty for accounts verified with bank details. |
| `branchCode` | STRING | Receiver bank account branch. Empty while an account verified by Pix key has not been resolved. |
| `created` | STRING | Creation datetime. Example: "2024-05-10T17:10:57.261868+00:00". |
| `id` | STRING | Unique id for the Verified Account. Use it to create Verified Transfers to this receiver. |
| `keyId` | STRING | Pix key used to verify the account. Empty when the account was verified with bank details. Example: "arya.stark@starkbank.com". |
| `name` | STRING | Receiver full name. Informed by you when verifying with bank details, or resolved by us from the Pix key. Example: "Arya Stark". |
| `number` | STRING | Receiver bank account number. Empty while an account verified by Pix key has not been resolved. |
| `status` | STRING | Current Verified Account status. Options: "creating", "created", "processing", "active", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the Verified Account. All tags are returned in lowercase. |
| `taxId` | STRING | Receiver CPF or CNPJ, as informed on creation. Example: "012.345.678-90". |
| `type` | STRING | Receiver bank account type. Options: "checking", "savings", "salary", "payment". Empty while an account verified by Pix key has not been resolved. |
| `updated` | STRING | Last update datetime. Example: "2024-05-10T17:11:43.108224+00:00". |

### Create Verified Accounts

`POST /v2/verified-account`

This route is used to verify that a bank account belongs to the informed tax ID before you send money to it.

For each account, inform either the receiver's Pix key or the receiver's full bank details. Sending both in the same account is not allowed, and sending neither is not allowed either.

You can create up to 100 Verified Accounts in a single request.

**NOTE:**Verification is done with a real R$0.01 transfer to the receiver. It appears in your [Transfer](#transfer) list tagged with the Verified Account id and is charged your usual transfer fee.

**NOTE:**It is not possible to create more than three Verified Accounts for the same tax ID within 24 hours. Failed and canceled Verified Accounts do not count towards this limit.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `taxId` | REQUIRED | Receiver CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: "012.345.678-90" |
| `bankCode` | CONDITIONALLY REQUIRED | Required when verifying with bank details. Receiver bank ISPB (8 digits) or bank code (1 to 3 digits). Example: "20018183" or "341" |
| `branchCode` | CONDITIONALLY REQUIRED | Required when verifying with bank details. Receiver bank account branch. Use "-" in case there is a validation digit. Example: "1234-5" |
| `keyId` | CONDITIONALLY REQUIRED | Required when verifying with a Pix key. The receiver's Pix key, which can be a CPF, a CNPJ, an email, a phone or an EVP. Example: "arya.stark@starkbank.com" |
| `name` | CONDITIONALLY REQUIRED | Required when verifying with bank details. Receiver full name, with at least 3 characters. Example: "Arya Stark" |
| `number` | CONDITIONALLY REQUIRED | Required when verifying with bank details. Receiver bank account number. Use "-" before the validation digit. Example: "76543-8" |
| `type` | CONDITIONALLY REQUIRED | Required when verifying with bank details. Receiver bank account type. Options are "checking", "savings", "salary" and "payment". Example: "checking" |
| `tags` | OPTIONAL | Array of up to 100 strings to tag the entity for future queries. Each tag can have up to 100 characters and all tags will be converted to lowercase. Example: ["daenerys", "invoice/1234"] |

**Request**

```python
import starkbank

accounts = starkbank.verifiedaccount.create([
    starkbank.VerifiedAccount(
        tax_id="911.544.440-66",
        name="Daenerys Targaryen Stormborn",
        bank_code="341",
        branch_code="2201",
        number="76543-8",
        type="checking",
        tags=["daenerys", "invoice/1234"]
    ),
    starkbank.VerifiedAccount(
        tax_id="039.946.040-36",
        key_id="arya.stark@starkbank.com",
        tags=["arya"]
    )
])

for account in accounts:
    print(account)
```

**Response**

```python
VerifiedAccount(
    id=5155165527080960,
    tax_id=911.544.440-66,
    bank_code=341,
    branch_code=2201,
    key_id=,
    name=Daenerys Targaryen Stormborn,
    number=76543-8,
    type=checking,
    tags=['daenerys', 'invoice/1234'],
    bank_name=,
    status=creating,
    created=2024-05-10 17:10:57.261868,
    updated=2024-05-10 17:10:57.261868
)
VerifiedAccount(
    id=6244185527080960,
    tax_id=039.946.040-36,
    bank_code=,
    branch_code=,
    key_id=arya.stark@starkbank.com,
    name=,
    number=,
    type=,
    tags=['arya'],
    bank_name=,
    status=creating,
    created=2024-05-10 17:10:57.318402,
    updated=2024-05-10 17:10:57.318402
)
```

### List Verified Accounts

`GET /v2/verified-account`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. Maximum of 100 ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default value = 100. |
| `status` | OPTIONAL | Filter Verified Accounts by the specified status. Options: "creating", "created", "processing", "active", "failed", "canceled". |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `taxId` | OPTIONAL | Filter Verified Accounts created for the specified tax ID. Not available in the SDKs. Example: "012.345.678-90" |

**Request**

```python
import starkbank

accounts = starkbank.verifiedaccount.query(
    limit=10,
    status="active",
    after="2024-05-01",
    before="2024-05-30"
)

for account in accounts:
    print(account)
```

**Response**

```python
VerifiedAccount(
    id=6244185527080960,
    tax_id=039.946.040-36,
    bank_code=20018183,
    branch_code=0001,
    key_id=arya.stark@starkbank.com,
    name=Arya Stark,
    number=6341320293482496,
    type=checking,
    tags=['arya'],
    bank_name=Stark Bank S.A.,
    status=active,
    created=2024-05-10 17:10:57.318402,
    updated=2024-05-10 17:12:31.904771
)
```

### Get a Verified Account

`GET /v2/verified-account/:id`

Get a single Verified Account by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Verified Account you want to retrieve. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

account = starkbank.verifiedaccount.get("5155165527080960")

print(account)
```

**Response**

```python
VerifiedAccount(
    id=5155165527080960,
    tax_id=911.544.440-66,
    bank_code=341,
    branch_code=2201,
    key_id=,
    name=Daenerys Targaryen Stormborn,
    number=76543-8,
    type=checking,
    tags=['daenerys', 'invoice/1234'],
    bank_name=,
    status=active,
    created=2024-05-10 17:10:57.261868,
    updated=2024-05-10 17:12:30.117633
)
```

### Cancel a Verified Account

`DELETE /v2/verified-account/:id`

Cancel a Verified Account so it can no longer be used as a receiver in [Verified Transfers](#verified-transfer).

**NOTE:**Only Verified Accounts with status "creating", "created" or "active" can be canceled. Accounts that are already "processing", "failed" or "canceled" will be rejected.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Verified Account you want to cancel. |

**Request**

```python
import starkbank

account = starkbank.verifiedaccount.cancel("5155165527080960")

print(account)
```

**Response**

```python
VerifiedAccount(
    id=5155165527080960,
    tax_id=911.544.440-66,
    bank_code=341,
    branch_code=2201,
    key_id=,
    name=Daenerys Targaryen Stormborn,
    number=76543-8,
    type=checking,
    tags=['daenerys', 'invoice/1234'],
    bank_name=,
    status=canceled,
    created=2024-05-10 17:10:57.261868,
    updated=2024-05-11 13:04:12.552019
)
```

### List Verified Account Logs

`GET /v2/verified-account/log`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `accountIds` | OPTIONAL | Array of Verified Account ids that are linked to the logs you desire. Maximum of 100 ids. |
| `after` | OPTIONAL | Filter logs created after this date. |
| `before` | OPTIONAL | Filter logs created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default value = 100. |
| `types` | OPTIONAL | Filters logs by log types. Options: "creating", "created", "processing", "active", "failed", "canceled". |

**Request**

```python
import starkbank

logs = starkbank.verifiedaccount.log.query(
    limit=10,
    types=["failed"],
    after="2024-05-01",
    before="2024-05-30"
)

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

**Response**

```python
Log(
    id=5662318377566208,
    type=failed,
    errors=[{'code': 'keyNotFound', 'message': 'The key is not registered'}],
    account=VerifiedAccount(
        id=6244185527080960,
        tax_id=039.946.040-36,
        bank_code=,
        branch_code=,
        key_id=arya.stark@starkbank.com,
        name=,
        number=,
        type=,
        tags=['arya'],
        bank_name=,
        status=failed,
        created=2024-05-10 17:10:57.318402,
        updated=2024-05-10 17:11:43.108224
    ),
    created=2024-05-10 17:11:43.108224
)
```

### Get a Verified Account Log

`GET /v2/verified-account/log/:id`

Get a single Verified Account Log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Verified Account Log you want to retrieve. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

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

print(log)
```

**Response**

```python
Log(
    id=5662318377566208,
    type=failed,
    errors=[{'code': 'keyNotFound', 'message': 'The key is not registered'}],
    account=VerifiedAccount(
        id=6244185527080960,
        tax_id=039.946.040-36,
        bank_code=,
        branch_code=,
        key_id=arya.stark@starkbank.com,
        name=,
        number=,
        type=,
        tags=['arya'],
        bank_name=,
        status=failed,
        created=2024-05-10 17:10:57.318402,
        updated=2024-05-10 17:11:43.108224
    ),
    created=2024-05-10 17:11:43.108224
)
```

## Verified Transfer

Verified Transfers are used to send money to a receiver you have already confirmed through a [Verified Account](#verified-account), without repeating the receiver's data on every payment.

You only inform the Verified Account id and the amount. The receiver name, tax ID, bank code, branch, account number and account type are copied from the Verified Account, so the money can only reach an account that has already been validated.

Creating a Verified Transfer creates a regular [Transfer](#transfer). The object you get back is a Transfer and the id you get back is a Transfer id, so from that point on you list it, cancel it, download its PDF and receive its webhook events through the Transfer routes.

### The Verified Transfer object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the transfer. This is a Transfer id and can be used on every Transfer route. |
| `accountNumber` | STRING | Receiver bank account number, copied from the Verified Account. |
| `accountType` | STRING | Receiver bank account type, copied from the Verified Account. Options: "checking", "savings", "salary", "payment", "other". |
| `amount` | INTEGER | Amount in cents to be transferred. Example: 1000 (R$10.00). |
| `bankCode` | STRING | Receiver bank code or ISPB, copied from the Verified Account. |
| `branchCode` | STRING | Receiver bank account branch, copied from the Verified Account. |
| `created` | STRING | Creation datetime. Example: "2020-02-06T16:22:24.664148+00:00". |
| `description` | STRING | Text displayed in the bank statement. When you do not send one, it defaults to the receiver name and tax ID. Example: "Tony Stark (012.345.678-90)". |
| `displayDescription` | STRING | Description shown in the receiver bank interface. Returns an empty string when none was sent. |
| `externalId` | STRING | Unique external ID to prevent duplicates. When you do not send one, it is generated from the workspace, the amount, the Verified Account data and the scheduled date. |
| `fee` | INTEGER | Fee charged in cents when the transfer is created. Example: 200 (R$2.00). |
| `metadata` | OBJECT | Dictionary object used to store additional information about the transfer. |
| `name` | STRING | Receiver full name, copied from the Verified Account. |
| `rules` | LIST OF OBJECTS | List of rule objects with key and value. |
| `scheduled` | STRING | Scheduled payment datetime. Example: "2020-08-14T10:00:00+00:00". |
| `status` | STRING | Current transfer status. Options: "created", "processing", "success", "failed", "canceled", "unknown". |
| `tags` | LIST OF STRINGS | Tags associated with the transfer. The tag "verified-account/<accountId>" is always added by us. All tags are returned in lowercase. |
| `taxId` | STRING | Receiver CPF or CNPJ, copied from the Verified Account. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the transfer. |
| `updated` | STRING | Last update datetime. Example: "2020-02-06T16:22:24.664148+00:00". |

### Create Verified Transfers

`POST /v2/verified-transfer`

This route is used to send transfers to receivers you have already verified. You can create up to 100 Verified Transfers in a single request.

**NOTE:**The receiver data (name, taxId, bankCode, branchCode, accountNumber and accountType) is always copied from the [Verified Account](#verified-account) identified by accountId, so it cannot be sent in the request.

**NOTE:**The Verified Account must not be canceled or failed. Accounts in the "creating", "created", "processing" and "active" statuses are accepted.

**NOTE:**The response carries [Transfer](#transfer) objects. The accountId you sent is not echoed back as a field, but every created transfer is tagged with "verified-account/<accountId>".

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `accountId` | REQUIRED | Id of the Verified Account that will receive the money. Example: "5155165527080960" |
| `amount` | REQUIRED | A positive integer that represents the amount in cents to be transferred. Must be lower than 10^15. Example: 1000 (R$10.00) |
| `description` | OPTIONAL | Optional description to override the default description shown in the bank statement. Must have between 10 and 300 characters. Example: "Payment for service #1234" |
| `displayDescription` | OPTIONAL | Description to be shown in the receiver bank interface. Max = 300 characters. Example: "Payment for service #1234" |
| `externalId` | OPTIONAL | Unique url-safe ID to prevent duplicate transfers. Max = 170 characters. By default, it blocks transfers of the same amount to the same Verified Account on the same day. Example: "my-external-id" |
| `rules` | OPTIONAL | List of up to 3 rules for modifying transfer behavior. Keys are "resendingLimit" (integer from 0 to 10), "isReversalAllowed" (boolean) and "isPartialReversalAllowed" (boolean). Each key can be used only once. Example: ``` [{"key": "resendingLimit", "value": 5}] ``` |
| `scheduled` | OPTIONAL | Schedule the transfer for a specific date. Today is the default. A date without a time is scheduled for 07:00 (BRT). Example: "2020-08-14T15:23:26+00:00" or "2020-08-14" |
| `tags` | OPTIONAL | Array of up to 100 strings to tag the entity for future queries. Each tag can have up to 100 characters and all tags will be converted to lowercase. Example: ["iron", "suit"] |

**Request**

```python
import starkbank

transfers = starkbank.verifiedtransfer.create([
    starkbank.VerifiedTransfer(
        account_id="5155165527080960",
        amount=1000,
        external_id="my-external-id",
        scheduled="2020-08-14",
        description="Payment for service #1234",
        display_description="Payment for service #1234",
        tags=["iron", "suit"],
        rules=[
            starkbank.transfer.Rule(
                key="resendingLimit",
                value=5
            )
        ]
    )
])

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

**Response**

```python
VerifiedTransfer(
    id=5412038532661248,
    amount=1000,
    account_id=None,
    account_type=checking,
    external_id=my-external-id,
    scheduled=2020-08-14 10:00:00,
    description=Payment for service #1234,
    display_description=Payment for service #1234,
    tags=['iron', 'suit', 'verified-account/5155165527080960'],
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    fee=200,
    status=created,
    transaction_ids=[],
    metadata={},
    created=2020-02-06 16:22:24.664148,
    updated=2020-02-06 16:22:24.664148
)
```

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `brcode` | REQUIRED | Brcode that describes the payment. |
| `description` | REQUIRED | Text to be displayed in your statement. Min length = 10. |
| `taxId` | REQUIRED | Receiver CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90. |
| `amount` | CONDITIONALLY REQUIRED | If the brcode does not provide an amount, this parameter is mandatory, else it is optional. Example: 23456 (R$ 234,56). |
| `rules` | OPTIONAL | List of rules for modifying brcodePayment behavior. Example: ``` [{"key": "resendingLimit", "value": 5}] ``` |
| `scheduled` | OPTIONAL | Schedule the payment for a specific date. Default value is the current day. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

payments = starkbank.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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter brcode payments by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the brcode payment entity. |
| `status` | OPTIONAL | This can be used to cancel the payment by passing "canceled" as the status patch. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the brcode payment entity |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `paymentIds` | OPTIONAL | Array of payment ids linked to the desired logs. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.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.

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `description` | REQUIRED | Text to be displayed in your statement. Min length = 10. |
| `taxId` | REQUIRED | Receiver CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90. |
| `amount` | OPTIONAL | Amount to be paid. If none is informed, the current boleto value will be used. Example: 23456 (= R$ 234.56) |
| `barCode` | CONDITIONALLY REQUIRED | Bar code number that describes the payment. Either "line" or "barCode" parameters are required. If both are sent, they must match. |
| `line` | CONDITIONALLY REQUIRED | Number sequence that describes the payment. Either "line" or "barCode" parameters are required. If both are sent, they must match. |
| `scheduled` | OPTIONAL | Schedule the payment for a specific date. Default value is the current day. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

payments = starkbank.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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter boleto payments by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the boleto payment entity |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `paymentIds` | OPTIONAL | Array of payment ids linked to the desired logs. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.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.

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `description` | REQUIRED | Text to be displayed in your statement. Min length = 10. |
| `barCode` | CONDITIONALLY REQUIRED | Bar code number that describes the payment. Either "line" or "barCode" parameters are required. If both are sent, they must match. |
| `line` | CONDITIONALLY REQUIRED | Number sequence that describes the payment. Either "line" or "barCode" parameters are required. If both are sent, they must match. |
| `scheduled` | OPTIONAL | Schedule the payment for a specific date. Default value is the current day. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

payments = starkbank.utilitypayment.create([
    starkbank.UtilityPayment(
        line="83640000001 1 08740138007 0 61053026111 0 08067159411 9",
        tags=["Energy", "Winterfell"],
        description="Electricity for the Long Night",
        scheduled="2020-04-25"
    )
])

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

**Response**

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

### List Utility Payments

`GET /v2/utility-payment`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter utility payments by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

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

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

**Response**

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

### Get a Utility Payment

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

Get a single utility payment by its id.

**Parameters**

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

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

### Delete a Utility Payment

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

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

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

**Parameters**

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

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

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

### Get a Utility Payment PDF

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the utility payment entity |

**Request**

```python
import starkbank

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

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

### List Utility Payment Logs

`GET /v2/utility-payment/log`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `paymentIds` | OPTIONAL | Array of payment ids linked to the desired logs. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.utilitypayment.log.query(
    payment_ids=["5949004768608256"]
)

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

**Response**

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

### Get a Utility Payment Log

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

Get a single utility payment log by its id.

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.utilitypayment.log.get("5369811349536768")

print(log)
```

**Response**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `description` | REQUIRED | Text to be displayed in your statement. Min length = 10. |
| `barCode` | CONDITIONALLY REQUIRED | Bar code number that describes the payment. Either "line" or "barCode" parameters are required. If both are sent, they must match. |
| `line` | CONDITIONALLY REQUIRED | Number sequence that describes the payment. Either "line" or "barCode" parameters are required. If both are sent, they must match. |
| `scheduled` | OPTIONAL | Schedule the payment for a specific date. Default value is the current day. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

payments = starkbank.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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter tax payments by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

**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. This is only allowed while the payment's status is "created", i.e. before Stark Bank has started processing it.

**NOTE:**Once processing has begun, or the payment has already been canceled, the delete request is rejected.

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the tax payment entity |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `paymentIds` | OPTIONAL | Array of payment ids linked to the desired logs. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.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.

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `competence` | REQUIRED | Competence month of the service. Example: '2020-03-10' |
| `description` | REQUIRED | Text to be displayed in your statement (min. 10 characters). Example: "payment ABC" |
| `due` | REQUIRED | Due date for payment. Example: '2020-03-10' |
| `fineAmount` | REQUIRED | Fixed amount due in cents for fines. Example: 234 (= R$ 2.34) |
| `interestAmount` | REQUIRED | Amount due in cents for interest. Example: 456 (= R$ 4.56) |
| `nominalAmount` | REQUIRED | Amount due in cents without fee or interest. Example: 23456 (= R$ 234.56) |
| `revenueCode` | REQUIRED | 4-digit tax code assigned by Federal Revenue. Example: "5948" |
| `taxId` | REQUIRED | Payer CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90 |
| `referenceNumber` | OPTIONAL | Number assigned to the region of the tax. Example: "08.1.17.00-4" |
| `scheduled` | OPTIONAL | Schedule the payment for a specific date. Default value is the current day. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

payments = starkbank.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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter Darfs by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

**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 a Darf payment while its status is still "created", before backend processing begins.

**NOTE:**Once processing has started, the payment can no longer be canceled or deleted.

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Darf payment entity |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `paymentIds` | OPTIONAL | Array of payment ids linked to the desired logs. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.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.

**Parameters**

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

**Request**

```python
import starkbank

log = starkbank.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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Main identification of the payment. This should be the BR Code for Pix payments and lines or bar codes for payment slips. Example: '34191.09008 63571.277308 71444.640008 5 81960000000062'. |
| `scheduled` | OPTIONAL | Intended payment date. Right now, this parameter only has effect on BrcodePreviews. Example: '2020-03-10' |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `centerId` | REQUIRED | Unique ID of the targeted cost center. You can check out the cost center ID directly on its approval section on our Web Banking. Example: 5656565656565656 |
| `payment` | REQUIRED | JSON specifying the requested payment. The payment JSON is the same as those passed in the requests that create the payments without going through the approval flow (see transfer and boleto payment). The only exception is that the "scheduled" parameter cannot be sent on these JSONs, as the PaymentRequest "due" parameter already serves this purpose. The SDKs also accept their respective objects instead of JSONs. |
| `due` | OPTIONAL | Suggested payment date. This parameter may be altered by the controllers of the cost center. Default is today. Example: "2020-08-01" |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |
| `type` | CONDITIONALLY REQUIRED | Payment type. The SDKs will take care of this parameter for you if you use their specialized objects. But if you pass a dictionary in payment parameter you need to inform its type. Examples: "transfer", "brcode-payment", "boleto-payment", "utility-payment". |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `centerId` | REQUIRED | Unique ID of the targeted cost center. You can check out the cost center ID directly on its approval section on our Web Banking. Example: 5656565656565656 |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `sort` | OPTIONAL | Sort order considered in the response. Options are: "-created" and "-due". Default is "-created". |
| `status` | OPTIONAL | Filter payment requests by the specified status. Example: success |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `type` | OPTIONAL | Filters payment requests by the type inferred from the payment parameter, if it is not a dictionary. Example: boleto-payment |

**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 in the example, 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, tax-payment, payment-request, verified-account, corporate-purchase, corporate-card or invoice.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `subscriptions` | REQUIRED | Array of subscriptions. Possible values: "deposit", "invoice", "brcode-payment", "transfer", "utility-payment", "boleto", "boleto-payment", "darf-payment", "tax-payment", "payment-request", "verified-account", "corporate-purchase", "corporate-card" or "boleto-holmes" |
| `url` | REQUIRED | The server URL that will receive the Webhook Events. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Maximum number of Webhooks to be retrieved. Max = 100. |

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Webhook to be canceled. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Date filter for Events created only after a specific date. Example: "2022-01-20" |
| `before` | OPTIONAL | Date filter for Events created only before a specific date. Example: "2022-02-20" |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `isDelivered` | OPTIONAL | If false, only gets Events that haven't been delivered. If true, only gets Events that have already been delivered. |
| `limit` | OPTIONAL | Maximum number of Events to be retrieved. Max = 100. |

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Event entity to be canceled. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the event entity. Example: "5719405850615809" |
| `isDelivered` | REQUIRED | Bool signaling if the Event has or hasn't been successfully delivered. |

**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](#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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `eventIds` | OPTIONAL | List of Event ids to filter attempts. Example: ["5656565656565656", "4545454545454545"] |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `webhookIds` | OPTIONAL | list of Webhook ids to filter attempts. Example: ["5656565656565656", "4545454545454545"] |

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

**Parameters**

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

**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](#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](#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 (return-only). Options: "individual", "business". |
| `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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter dicts by the specified status. |
| `type` | OPTIONAL | DICT Key type. Options are: "cpf", "cnpj", "phone", "email" or "evp". |

**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](#transfer).

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the dict key. Examples: "jon.snow@starkbank.com", "012.345.678-90" |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `search` | OPTIONAL | Part of the institution name to be searched. Example: "stark" |
| `spiCodes` | OPTIONAL | List of SPI (Pix) codes to be searched. Example: ["20018183"] |
| `strCodes` | OPTIONAL | List of STR (Ted) codes to be searched. Example: ["260"] |

**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-----\nMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEt/jVM/DGqfJ9GxctQMqrtjmIFoODoaHR\ncX0c/pIWCgBv1o5Zqk+ni027I/fRWl2XKvrZeFpjFufq6B1hInXowQ==\n-----END PUBLIC KEY-----,
    created=2020-03-27 03:31:00.000000
)
```