# API Reference

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

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

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

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

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

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

**Install (Python)**

```python
pip install starkinfra
```

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

## Tech Support

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

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

**CONTACT US**

help@starkinfra.com

## Testing in Sandbox

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

Create a Workspace in Sandbox

Your initial balance is zero. You can add balance by creating Pix Requests, as they will be processed automatically in the Sandbox environment within a few minutes.

**BASE URL - Sandbox**

https://sandbox.api.starkinfra.com

## Moving to Production

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

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

Note 2: The response times are different in each environment as we emulate the results in Sandbox, while in Production we depend on other financial institutions to operate.

You can request an account in Production here:

Create a Workspace in Production

**BASE URL - Production**

https://api.starkinfra.com

## Versioning

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

We consider the following changes to be backward-compatible:

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

**Current API Version**

v2

## Authentication

## Static IP list

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

**Production**

- 35.199.76.124 
  - 34.85.188.162

**Sandbox**

- 35.247.226.240 
  - 35.245.182.229

## Errors

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

**HTTP STATUS CODE SUMMARY**

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

**ERROR SAMPLE**

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

## Supported Languages

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

**Accept-Language Header**

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

## Pagination

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

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

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

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

**Example: Handling cursors**

path = "https://sandbox.api.starkinfra.com/v2/pix-request"

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

print(cursor)  # CkYKFAoHY3JlYXRlZBIJCMWGnoWVoukCEipqE2l-YXBpLW1zLWNoYXJnZS1zYnhyEwsSBkNoYXJnZRiAgICC28rtCAwYACAB

nextResponse = request.get(path + "?cursor=" + cursor)
pixRequestList += nextResponse["requests"]
nextCursor = nextResponse["cursor"]

...

## Date & Time

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

**Example**

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

# Pix

## Pix Request

A Pix Request represents an inbound or outbound Pix payment in the Brazilian instant payment system.

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

### The Pix Request Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix request. |
| `amount` | INTEGER | Amount in cents to be transferred. Example: 100 (R$1.00). |
| `endToEndId` | STRING | Unique end-to-end ID assigned by the Pix system. |
| `fee` | INTEGER | Fee charged in cents for this Pix request. |
| `flow` | STRING | Direction of the Pix request. Options: "in" (received), "out" (sent). |
| `method` | STRING | Method through which this Pix was processed. Options: "manual", "dict", "initiator", "dynamicQrcode", "staticQrcode", "payerQrcode", "subscription", "contactless", "staticContactless". |
| `externalId` | STRING | Unique external ID to prevent duplicates. |
| `initiatorTaxId` | STRING | Tax ID of the payment initiator. |
| `receiverBankCode` | STRING | Bank ISPB code of the receiver. |
| `receiverBranchCode` | STRING | Branch code of the receiver's bank account. |
| `receiverAccountNumber` | STRING | Account number of the receiver. |
| `receiverAccountType` | STRING | Account type of the receiver. Options: "checking", "savings", "salary", "payment". |
| `receiverName` | STRING | Full name of the receiver. |
| `receiverTaxId` | STRING | CPF or CNPJ of the receiver. |
| `senderBankCode` | STRING | Bank ISPB code of the sender. |
| `senderBranchCode` | STRING | Branch code of the sender's bank account. |
| `senderAccountNumber` | STRING | Account number of the sender. |
| `senderAccountType` | STRING | Account type of the sender. Options: "checking", "savings", "salary", "payment". |
| `senderName` | STRING | Full name of the sender. |
| `senderTaxId` | STRING | CPF or CNPJ of the sender. |
| `status` | STRING | Current status. Options: "created", "processing", "success", "failed". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix request. |
| `description` | STRING | Description of the Pix request. |
| `reconciliationId` | STRING | Reconciliation ID for the Pix request. |
| `cashAmount` | INTEGER | Amount in cents to be withdrawal when paying. Example: 1000 (R$10.00). |
| `cashierType` | STRING | Cashier's type for Pix Cash-out and Pix Change. Options: "merchant", "participant", "other". |
| `cashierBankCode` | STRING | Cashier's bank ISPB code for Pix Cash-out and Pix Change. |
| `priority` | STRING | Pix request processing priority. Options: "high", "low". |
| `reason` | STRING | Reason why this Pix request was created. Options: "customerRequest", "subscriptionFlaw", "fraud". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Pix Requests

`POST /v2/pix-request`

Send Pix payments to any Pix-enabled bank account in Brazil.

To create a manual Pix Request you need the receiver's account information. If you only have a Pix Key, use Get a Pix Key to retrieve the required information before creating the Pix Request.

Every time a participant sends you a Pix, an inbound Pix Request is created and a synchronous POST authorization request is sent to your registered pixRequestUrl, which you must answer with approval or denial within 1 second (HTTP 200) or it is denied by default. Approve with status "approved"; deny with status "denied" and a reason such as "invalidAccountNumber".

**Request**

```python
import starkinfra

requests = starkinfra.pixrequest.create([
    starkinfra.PixRequest(
        amount=1000,
        external_id="my-external-id-1",
        end_to_end_id="E20018183202201011000r01",
        sender_account_number="00000-0",
        sender_branch_code="0001",
        sender_account_type="checking",
        sender_name="Arya Stark",
        sender_tax_id="012.345.678-90",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_bank_code="20018183",
        receiver_tax_id="98.765.432/0001-10",
        receiver_branch_code="0001",
        receiver_name="Jon Snow",
        tags=["transfer", "pix"]
    )
])

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

**Response**

```python
[
    PixRequest(
        id="5656565656565656",
        amount=1000,
        end_to_end_id="E20018183202201011000r01",
        fee=0,
        flow="out",
        method="manual",
        external_id="my-external-id-1",
        initiator_tax_id="",
        receiver_bank_code="20018183",
        receiver_branch_code="0001",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_name="Jon Snow",
        receiver_tax_id="98.765.432/0001-10",
        sender_bank_code="34052649",
        sender_branch_code="0001",
        sender_account_number="00000-0",
        sender_account_type="checking",
        sender_name="Arya Stark",
        sender_tax_id="012.345.678-90",
        status="created",
        tags=["transfer", "pix"],
        description="",
        reconciliation_id="",
        cash_amount=0,
        cashier_type="",
        cashier_bank_code="",
        priority="high",
        reason="customerRequest",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Requests

`GET /v2/pix-request`

List and filter all Pix requests. Results are paged.

Every time a participant sends you a Pix, an inbound Pix Request is created and a synchronous POST authorization request is sent to your registered pixRequestUrl, which you must answer with approval or denial within 1 second (HTTP 200) or it is denied by default. Approve with status "approved"; deny with status "denied" and a reason such as "invalidAccountNumber".

**Request**

```python
import starkinfra

requests = starkinfra.pixrequest.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["success"],
    tags=["pix"]
)

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

**Response**

```python
<generator object query at 0x...>

PixRequest(
    id="5656565656565656",
    amount=1000,
    end_to_end_id="E20018183202201011000r01",
    fee=0,
    flow="out",
    method="manual",
    status="success",
    tags=["pix"],
    priority="high",
    reason="customerRequest",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Pix Request

`GET /v2/pix-request/:id`

Get a single Pix request by its id.

**Request**

```python
import starkinfra

request = starkinfra.pixrequest.get("5656565656565656")

print(request)
```

**Response**

```python
PixRequest(
    id="5656565656565656",
    amount=1000,
    end_to_end_id="E20018183202201011000r01",
    fee=0,
    flow="out",
    method="manual",
    external_id="my-external-id-1",
    initiator_tax_id="",
    receiver_bank_code="20018183",
    receiver_branch_code="0001",
    receiver_account_number="10000-0",
    receiver_account_type="checking",
    receiver_name="Jon Snow",
    receiver_tax_id="98.765.432/0001-10",
    sender_bank_code="34052649",
    sender_branch_code="0001",
    sender_account_number="00000-0",
    sender_account_type="checking",
    sender_name="Arya Stark",
    sender_tax_id="012.345.678-90",
    status="success",
    tags=["pix"],
    description="",
    reconciliation_id="",
    cash_amount=0,
    cashier_type="",
    cashier_bank_code="",
    priority="high",
    reason="customerRequest",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### List Pix Request Logs

`GET /v2/pix-request/log`

Get a paged list of all Pix request logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixrequest.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["success"],
    request_ids=["5656565656565656"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    type="success",
    errors=[],
    request=PixRequest(
        id="5656565656565656",
        amount=1000,
        end_to_end_id="E20018183202201011000r01",
        fee=0,
        flow="out",
        method="manual",
        external_id="my-external-id-1",
        initiator_tax_id="",
        receiver_bank_code="20018183",
        receiver_branch_code="0001",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_name="Jon Snow",
        receiver_tax_id="98.765.432/0001-10",
        sender_bank_code="34052649",
        sender_branch_code="0001",
        sender_account_number="00000-0",
        sender_account_type="checking",
        sender_name="Arya Stark",
        sender_tax_id="012.345.678-90",
        status="success",
        tags=["pix"],
        description="",
        reconciliation_id="",
        cash_amount=0,
        cashier_type="",
        cashier_bank_code="",
        priority="high",
        reason="customerRequest",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Request Log

`GET /v2/pix-request/log/:id`

Get a single Pix request log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixrequest.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    type="success",
    errors=[],
    request=PixRequest(
        id="5656565656565656",
        amount=1000,
        end_to_end_id="E20018183202201011000r01",
        fee=0,
        flow="out",
        method="manual",
        external_id="my-external-id-1",
        initiator_tax_id="",
        receiver_bank_code="20018183",
        receiver_branch_code="0001",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_name="Jon Snow",
        receiver_tax_id="98.765.432/0001-10",
        sender_bank_code="34052649",
        sender_branch_code="0001",
        sender_account_number="00000-0",
        sender_account_type="checking",
        sender_name="Arya Stark",
        sender_tax_id="012.345.678-90",
        status="success",
        tags=["pix"],
        description="",
        reconciliation_id="",
        cash_amount=0,
        cashier_type="",
        cashier_bank_code="",
        priority="high",
        reason="customerRequest",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    created="2022-01-01T00:01:00+00:00"
)
```

## Pix Reversal

A Pix Reversal allows you to reverse a previously made Pix transfer, sending the funds back to the original sender.

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

### The Pix Reversal Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix reversal. |
| `amount` | INTEGER | Amount in cents to be reversed. |
| `externalId` | STRING | Unique external ID to prevent duplicates. |
| `endToEndId` | STRING | End-to-end ID of the original Pix request to be reversed. |
| `returnId` | STRING | Central Bank return ID generated for the Pix reversal. |
| `reason` | STRING | Reason for the reversal. Options: "fraud", "bankError", "cashierError", "customerRequest". |
| `status` | STRING | Current status. Options: "created", "processing", "success", "failed". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix reversal. |
| `fee` | INTEGER | Fee charged in cents for this reversal. |
| `flow` | STRING | Direction of the reversal. Options: "in" (received), "out" (sent). |
| `description` | STRING | Description of the reversal. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Pix Reversals

`POST /v2/pix-reversal`

Reverse a Pix payment by providing the original end-to-end ID.

Pix Reversals can only be created for inbound Pix Requests with status success. Reference the original Pix Request by passing its endToEndId.

When a participant reverses a Pix you successfully sent, an authorization request is sent to your pixReversalUrl (which must differ from your pixRequestUrl); answer within 1 second (HTTP 200) or it is denied by default; if no pixReversalUrl is registered, inbound Pix Reversals are accepted by default.

**Request**

```python
import starkinfra

reversals = starkinfra.pixreversal.create([
    starkinfra.PixReversal(
        amount=1000,
        external_id="my-reversal-id-1",
        end_to_end_id="E20018183202201060100rq1feOMJqtZ",
        reason="fraud",
        description="reversing a fraudulent transfer",
        tags=["reversal", "pix"]
    )
])

for reversal in reversals:
    print(reversal)
```

**Response**

```python
[
    PixReversal(
        id="5656565656565656",
        amount=1000,
        external_id="my-reversal-id-1",
        end_to_end_id="E20018183202201060100rq1feOMJqtZ",
        return_id="D20018183202202030109X3OoBHG74wo",
        reason="fraud",
        status="created",
        flow="out",
        fee=0,
        description="reversing a fraudulent transfer",
        tags=["reversal", "pix"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Reversals

`GET /v2/pix-reversal`

List and filter all Pix reversals. Results are paged.

**Request**

```python
import starkinfra

reversals = starkinfra.pixreversal.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["success"],
    external_ids=["my-reversal-id-1"],
    tags=["pix"]
)

for reversal in reversals:
    print(reversal)
```

**Response**

```python
<generator object query at 0x...>

PixReversal(
    id="5656565656565656",
    amount=1000,
    external_id="my-reversal-id-1",
    end_to_end_id="E20018183202201060100rq1feOMJqtZ",
    return_id="D20018183202202030109X3OoBHG74wo",
    reason="fraud",
    status="success",
    flow="out",
    fee=0,
    description="reversing a fraudulent transfer",
    tags=["pix"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Pix Reversal

`GET /v2/pix-reversal/:id`

Get a single Pix reversal by its id.

**Request**

```python
import starkinfra

reversal = starkinfra.pixreversal.get("5656565656565656")

print(reversal)
```

**Response**

```python
PixReversal(
    id="5656565656565656",
    amount=1000,
    external_id="my-reversal-id-1",
    end_to_end_id="E20018183202201060100rq1feOMJqtZ",
    return_id="D20018183202202030109X3OoBHG74wo",
    reason="fraud",
    status="success",
    flow="out",
    fee=0,
    description="reversing a fraudulent transfer",
    tags=["pix"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### List Pix Reversal Logs

`GET /v2/pix-reversal/log`

Get a paged list of all Pix reversal logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixreversal.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["success"],
    reversal_ids=["5656565656565656"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    type="success",
    reversal=PixReversal(
        id="5656565656565656",
        amount=1000,
        external_id="my-reversal-id-1",
        end_to_end_id="E20018183202201060100rq1feOMJqtZ",
        return_id="D20018183202202030109X3OoBHG74wo",
        reason="fraud",
        status="success",
        flow="out",
        fee=0,
        description="reversing a fraudulent transfer",
        tags=["pix"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Reversal Log

`GET /v2/pix-reversal/log/:id`

Get a single Pix reversal log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixreversal.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    type="success",
    reversal=PixReversal(
        id="5656565656565656",
        amount=1000,
        external_id="my-reversal-id-1",
        end_to_end_id="E20018183202201060100rq1feOMJqtZ",
        return_id="D20018183202202030109X3OoBHG74wo",
        reason="fraud",
        status="success",
        flow="out",
        fee=0,
        description="reversing a fraudulent transfer",
        tags=["pix"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    created="2022-01-01T00:01:00+00:00"
)
```

## Pix Internal Transaction Report

A Pix Internal Transaction Report lets Direct and Indirect participants report transactions that were settled internally on the participant, such as transfers between two Indirect participants of the same Direct participant or between accounts of the same participant.

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

### The Pix Internal Transaction Report Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix internal transaction report. |
| `referenceType` | STRING | Origin of the report's reference id. Options: "request" (derived from endToEndId), "reversal" (derived from returnId). |
| `amount` | INTEGER | Transaction amount in cents. Example: 100 (R$1.00). |
| `endToEndId` | STRING | End-to-end id of the reported Pix transaction. |
| `returnId` | STRING | Return id of the reported transaction. Present when referenceType is "reversal". |
| `method` | STRING | Type of the reported transaction. Options: "manual", "dict", "initiator", "dynamicQrcode", "staticQrcode", "payerQrcode", "subscription", "contactless", "staticContactless". |
| `senderBankCode` | STRING | Bank ISPB code of the sender. |
| `senderBranchCode` | STRING | Branch code of the sender's bank account. |
| `senderAccountNumber` | STRING | Account number of the sender. |
| `senderAccountType` | STRING | Account type of the sender. Options: "checking", "savings", "salary", "payment", "other". |
| `senderTaxId` | STRING | CPF or CNPJ of the sender. |
| `receiverBankCode` | STRING | Bank ISPB code of the receiver. |
| `receiverBranchCode` | STRING | Branch code of the receiver's bank account. |
| `receiverAccountNumber` | STRING | Account number of the receiver. |
| `receiverAccountType` | STRING | Account type of the receiver. Options: "checking", "savings", "salary", "payment", "other". |
| `receiverTaxId` | STRING | CPF or CNPJ of the receiver. |
| `receiverKeyId` | STRING | Pix key of the receiver, when the transaction used one. |
| `status` | STRING | Current status of the report. Options: "created", "processing", "success", "failed". |
| `created` | STRING | Datetime of the original transaction, supplied at creation. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Pix Internal Transaction Reports

`POST /v2/pix-internal-transaction-report`

Report transactions that were settled internally on the participant, such as transfers between two Indirect participants of the same Direct participant or between accounts of the same participant.

**Request**

```python
import starkinfra

reports = starkinfra.pixinternaltransactionreport.create([
    starkinfra.PixInternalTransactionReport(
        reference_type="request",
        amount=1000,
        end_to_end_id="E20018183202201011000r01",
        method="manual",
        created="2022-01-01T00:00:00+00:00",
        sender_bank_code="34052649",
        sender_branch_code="0001",
        sender_account_number="00000-0",
        sender_account_type="checking",
        sender_tax_id="012.345.678-90",
        receiver_bank_code="20018183",
        receiver_branch_code="0001",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_tax_id="20.018.183/0001-80",
        receiver_key_id="20.018.183/0001-80"
    )
])

for report in reports:
    print(report)
```

**Response**

```python
[
    PixInternalTransactionReport(
        id="5656565656565656",
        reference_type="request",
        amount=1000,
        end_to_end_id="E20018183202201011000r01",
        return_id="",
        method="manual",
        sender_bank_code="34052649",
        sender_branch_code="0001",
        sender_account_number="00000-0",
        sender_account_type="checking",
        sender_tax_id="012.345.678-90",
        receiver_bank_code="20018183",
        receiver_branch_code="0001",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_tax_id="20.018.183/0001-80",
        receiver_key_id="20.018.183/0001-80",
        status="created",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Internal Transaction Reports

`GET /v2/pix-internal-transaction-report`

List and filter all Pix internal transaction reports. Results are paged.

**Request**

```python
import starkinfra

reports = starkinfra.pixinternaltransactionreport.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["success"],
    ids=["5656565656565656"]
)

for report in reports:
    print(report)
```

**Response**

```python
<generator object query at 0x...>

PixInternalTransactionReport(
    id="5656565656565656",
    reference_type="request",
    amount=1000,
    end_to_end_id="E20018183202201011000r01",
    method="manual",
    status="success",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Pix Internal Transaction Report

`GET /v2/pix-internal-transaction-report/:id`

Get a single Pix internal transaction report by its id.

**Request**

```python
import starkinfra

report = starkinfra.pixinternaltransactionreport.get("5656565656565656")

print(report)
```

**Response**

```python
PixInternalTransactionReport(
    id="5656565656565656",
    reference_type="request",
    amount=1000,
    end_to_end_id="E20018183202201011000r01",
    return_id="",
    method="manual",
    sender_bank_code="34052649",
    sender_branch_code="0001",
    sender_account_number="00000-0",
    sender_account_type="checking",
    sender_tax_id="012.345.678-90",
    receiver_bank_code="20018183",
    receiver_branch_code="0001",
    receiver_account_number="10000-0",
    receiver_account_type="checking",
    receiver_tax_id="20.018.183/0001-80",
    receiver_key_id="20.018.183/0001-80",
    status="success",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### List Pix Internal Transaction Report Logs

`GET /v2/pix-internal-transaction-report/log`

Get a paged list of all Pix internal transaction report logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixinternaltransactionreport.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["success"],
    report_ids=["5656565656565656"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    type="success",
    errors=[],
    report=PixInternalTransactionReport(
        id="5656565656565656",
        reference_type="request",
        amount=1000,
        end_to_end_id="E20018183202201011000r01",
        return_id="",
        method="manual",
        sender_bank_code="34052649",
        sender_branch_code="0001",
        sender_account_number="00000-0",
        sender_account_type="checking",
        sender_tax_id="012.345.678-90",
        receiver_bank_code="20018183",
        receiver_branch_code="0001",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_tax_id="20.018.183/0001-80",
        receiver_key_id="20.018.183/0001-80",
        status="success",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Internal Transaction Report Log

`GET /v2/pix-internal-transaction-report/log/:id`

Get a single Pix internal transaction report log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixinternaltransactionreport.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    type="success",
    errors=[],
    report=PixInternalTransactionReport(
        id="5656565656565656",
        reference_type="request",
        amount=1000,
        end_to_end_id="E20018183202201011000r01",
        return_id="",
        method="manual",
        sender_bank_code="34052649",
        sender_branch_code="0001",
        sender_account_number="00000-0",
        sender_account_type="checking",
        sender_tax_id="012.345.678-90",
        receiver_bank_code="20018183",
        receiver_branch_code="0001",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_tax_id="20.018.183/0001-80",
        receiver_key_id="20.018.183/0001-80",
        status="success",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    created="2022-01-01T00:01:00+00:00"
)
```

## Static Brcode

A Static Brcode is a QR Code that can receive multiple Pix payments with a fixed or open amount.

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

### The Static Brcode Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the static Brcode. |
| `name` | STRING | Receiver name displayed in the QR code. |
| `keyId` | STRING | Pix key to which payments will be directed. |
| `city` | STRING | City of the receiver. |
| `amount` | INTEGER | Fixed amount in cents. Leave empty for open amount QR codes. |
| `reconciliationId` | STRING | Reconciliation ID included in the QR code. |
| `cashierBankCode` | STRING | Bank ISPB code of the cashier for Pix Saque/Troco operations. |
| `type` | STRING | Type of the static Brcode. Options: "instant", "instantAndOrSubscription". |
| `description` | STRING | Description of the static Brcode. |
| `tags` | LIST OF STRINGS | Tags associated with the static Brcode. |
| `uuid` | STRING | Unique UUID used to identify this QR code. |
| `url` | STRING | URL for the QR code image. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Static Brcodes

`POST /v2/static-brcode`

Create static Pix QR codes for receiving payments.

**Request**

```python
import starkinfra

brcodes = starkinfra.staticbrcode.create([
    starkinfra.StaticBrcode(
        name="Jon Snow",
        key_id="+5511989898989",
        city="São Paulo",
        amount=1000,
        cashier_bank_code="20018183",
        type="instant",
        reconciliation_id="my-reconciliation-id",
        description="Payment for services",
        tags=["invoice", "payment"]
    )
])

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

**Response**

```python
[
    StaticBrcode(
        id="5656565656565656",
        name="Jon Snow",
        key_id="+5511989898989",
        city="São Paulo",
        amount=1000,
        reconciliation_id="my-reconciliation-id",
        cashier_bank_code="20018183",
        type="instant",
        description="Payment for services",
        tags=["invoice", "payment"],
        uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        url="https://brcode.starkinfra.com/static-qrcode/a1b2c3d4-e5f6-7890-abcd-ef1234567890.png",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Static Brcodes

`GET /v2/static-brcode`

List and filter all static Brcodes. Results are paged.

**Request**

```python
import starkinfra

brcodes = starkinfra.staticbrcode.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    uuids=["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    tags=["invoice"]
)

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

**Response**

```python
StaticBrcode(
    id="5656565656565656",
    name="Jon Snow",
    key_id="+5511989898989",
    city="São Paulo",
    amount=1000,
    reconciliation_id="my-reconciliation-id",
    cashier_bank_code="20018183",
    type="instant",
    description="Payment for services",
    tags=["invoice"],
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    url="https://brcode.starkinfra.com/static-qrcode/a1b2c3d4-e5f6-7890-abcd-ef1234567890.png",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Static Brcode

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

Get a single static Brcode by its UUID.

**Request**

```python
import starkinfra

brcode = starkinfra.staticbrcode.get("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

print(brcode)
```

**Response**

```python
StaticBrcode(
    id="5656565656565656",
    name="Jon Snow",
    key_id="+5511989898989",
    city="São Paulo",
    amount=1000,
    reconciliation_id="my-reconciliation-id",
    cashier_bank_code="20018183",
    type="instant",
    description="Payment for services",
    tags=["invoice", "payment"],
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    url="https://brcode.starkinfra.com/static-qrcode/a1b2c3d4-e5f6-7890-abcd-ef1234567890.png",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

## Dynamic Brcode

A Dynamic Brcode is a QR Code that returns payment details dynamically from your server when scanned.

The "subscription", "subscriptionAndInstant" and "dueAndOrSubscription" types let a Dynamic Brcode initiate a Pix Automático recurring authorization.

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

### The Dynamic Brcode Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the dynamic Brcode. |
| `name` | STRING | Receiver name displayed in the QR code. |
| `city` | STRING | City of the receiver. |
| `externalId` | STRING | Your internal ID for this Brcode, used to prevent duplicates. |
| `type` | STRING | Type of dynamic Brcode. Options: "instant", "due", "subscription", "subscriptionAndInstant", "dueAndOrSubscription". |
| `tags` | LIST OF STRINGS | Tags associated with the dynamic Brcode. |
| `uuid` | STRING | Unique UUID used to identify this QR code. |
| `url` | STRING | URL for the QR code image. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Dynamic Brcodes

`POST /v2/dynamic-brcode`

Create dynamic Pix QR codes that fetch payment details from your server.

**Request**

```python
import starkinfra

brcodes = starkinfra.dynamicbrcode.create([
    starkinfra.DynamicBrcode(
        name="Jon Snow",
        city="São Paulo",
        external_id="my-dynamic-brcode-id-1",
        type="subscription",
        tags=["dynamic", "subscription"]
    )
])

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

**Response**

```python
[
    DynamicBrcode(
        id="5656565656565656",
        name="Jon Snow",
        city="São Paulo",
        external_id="my-dynamic-brcode-id-1",
        type="subscription",
        tags=["dynamic", "subscription"],
        uuid="b2c3d4e5-f6a7-8901-bcde-f12345678901",
        url="https://brcode.starkinfra.com/dynamic-qrcode/b2c3d4e5-f6a7-8901-bcde-f12345678901.png",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Dynamic Brcodes

`GET /v2/dynamic-brcode`

List and filter all dynamic Brcodes. Results are paged.

**Request**

```python
import starkinfra

brcodes = starkinfra.dynamicbrcode.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    tags=["dynamic"]
)

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

**Response**

```python
DynamicBrcode(
    id="5656565656565656",
    name="Jon Snow",
    city="São Paulo",
    external_id="my-dynamic-brcode-id-1",
    type="instant",
    tags=["dynamic"],
    uuid="b2c3d4e5-f6a7-8901-bcde-f12345678901",
    url="https://brcode.starkinfra.com/dynamic-qrcode/b2c3d4e5-f6a7-8901-bcde-f12345678901.png",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Dynamic Brcode

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

Get a single dynamic Brcode by its UUID.

**Request**

```python
import starkinfra

brcode = starkinfra.dynamicbrcode.get("b2c3d4e5-f6a7-8901-bcde-f12345678901")

print(brcode)
```

**Response**

```python
DynamicBrcode(
    id="5656565656565656",
    name="Jon Snow",
    city="São Paulo",
    external_id="my-dynamic-brcode-id-1",
    type="instant",
    tags=["dynamic", "instant"],
    uuid="b2c3d4e5-f6a7-8901-bcde-f12345678901",
    url="https://brcode.starkinfra.com/dynamic-qrcode/b2c3d4e5-f6a7-8901-bcde-f12345678901.png",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

## Brcode Preview

A Brcode Preview allows you to fetch the information encoded in a QR code before initiating a Pix payment or accepting a Pix Subscription.

Here we will show you how to retrieve Brcode previews.

### The Brcode Preview Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | QR code content (the EMV string from the QR code). |
| `payerId` | STRING | CPF or CNPJ of the payer. |
| `endToEndId` | STRING | Unique end-to-end ID of the Pix transaction associated with this preview. |
| `status` | STRING | Status of the QR code. Options: "active", "paid", "canceled", "unknown". |
| `name` | STRING | Receiver name. |
| `taxId` | STRING | CPF or CNPJ of the receiver. |
| `bankCode` | STRING | Bank ISPB code of the receiver. |
| `branchCode` | STRING | Branch code of the receiver's account. |
| `accountNumber` | STRING | Account number of the receiver. |
| `accountType` | STRING | Account type of the receiver. |
| `amount` | INTEGER | Amount in cents to be paid. |
| `nominalAmount` | INTEGER | Nominal amount in cents before discounts, fines and interest. |
| `amountType` | STRING | Type of amount. Options: "fixed", "minimum". |
| `reconciliationId` | STRING | Reconciliation ID from the QR code. |
| `description` | STRING | Description of the payment. |
| `cashierType` | STRING | Cashier type for Pix Saque/Troco. Options: "merchant", "other", "participant". |
| `cashierBankCode` | STRING | Bank ISPB code of the cashier. |
| `cashAmount` | INTEGER | Cash amount in cents for Pix Saque/Troco. |
| `discountAmount` | INTEGER | Discount amount in cents. |
| `fineAmount` | INTEGER | Fine amount in cents for late payment. |
| `interestAmount` | INTEGER | Interest amount in cents for late payment. |
| `reductionAmount` | INTEGER | Reduction (abatement) amount in cents. |
| `due` | STRING | Due date and time for payment of the dynamic QR code. Example: "2020-04-23T23:00:00.000000+00:00". |
| `expired` | STRING | Date and time after which the dynamic QR code is considered expired. Example: "2020-04-23T23:00:00.000000+00:00". |
| `keyId` | STRING | Pix key of the receiver. |
| `data` | LIST OF OBJECTS | List of additional data objects with key and value. |
| `scheduled` | STRING | Date and time the payment is scheduled for. Example: "2020-04-23T23:00:00.000000+00:00". |
| `jws` | STRING | JWS (JSON Web Signature) of the dynamic QR code. Returned only when "jws" is passed in the expand query parameter. |
| `subscription.bacenId` | STRING | Central Bank identifier of the recurring authorization. The subscription fields are returned only when the Brcode initiates a Pix Automático recurring authorization. |
| `subscription.amount` | INTEGER | Fixed amount in cents pulled on each cycle. 0 when the amount is variable. |
| `subscription.amountMinLimit` | INTEGER | Minimum amount in cents allowed per pull when the amount is variable. |
| `subscription.interval` | STRING | Billing interval. Options: "week", "month", "quarter", "semester", "year". |
| `subscription.description` | STRING | Description presented to the payer. |
| `subscription.referenceCode` | STRING | Free reference code for the subscription. |
| `subscription.installmentStart` | STRING | Date when the recurring authorization starts. |
| `subscription.installmentEnd` | STRING | Date when the recurring authorization ends. |
| `subscription.pullRetryLimit` | INTEGER | Maximum number of pull retries allowed per cycle. |
| `subscription.receiverName` | STRING | Name of the receiver (creditor). |
| `subscription.receiverTaxId` | STRING | CPF or CNPJ of the receiver. |
| `subscription.receiverBankCode` | STRING | Bank ISPB code of the receiver. |
| `subscription.senderFinalName` | STRING | Name of the final payer, when applicable. |
| `subscription.senderFinalTaxId` | STRING | CPF or CNPJ of the final payer, when applicable. |
| `subscription.type` | STRING | Subscription type. Options: "qrcode", "qrcodeAndPayment", "paymentAndOrQrcode". |
| `subscription.status` | STRING | Current status. Options: "created", "approved", "denied", "expired", "canceled". |
| `subscription.created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `subscription.updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Brcode Previews

`POST /v2/brcode-preview`

Fetch and preview the details of one or more Pix QR codes before payment.

**Request**

```python
import starkinfra

previews = starkinfra.brcodepreview.create([
    starkinfra.BrcodePreview(
        id="00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540510.005802BR5905Stark6009Sao Paulo62070503***63041D3D",
        payer_id="012.345.678-90",
        end_to_end_id="E20018183202201201450u34sDGd19lz",
        scheduled="2022-01-31"
    )
])

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

**Response**

```python
[
    BrcodePreview(
        id="00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540510.005802BR5905Stark6009Sao Paulo62070503***63041D3D",
        payer_id="012.345.678-90",
        end_to_end_id="E20018183202201201450u34sDGd19lz",
        status="active",
        name="Jon Snow",
        tax_id="012.345.678-90",
        bank_code="20018183",
        branch_code="0001",
        account_number="10000-0",
        account_type="checking",
        amount=1000,
        nominal_amount=1000,
        amount_type="fixed",
        reconciliation_id="my-reconciliation-id",
        description="Payment for services",
        cashier_type="merchant",
        cashier_bank_code="20018183",
        cash_amount=0,
        discount_amount=0,
        fine_amount=0,
        interest_amount=0,
        reduction_amount=0,
        due="2022-01-31T00:00:00+00:00",
        expired="2022-02-01T00:00:00+00:00",
        key_id="+5511989898989",
        data=[
            {"key": "additional-info", "value": "order #12345"}
        ],
        scheduled="2022-01-31T00:00:00+00:00",
        jws="eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
        subscription=Subscription(
            bacen_id="RR20220101200181830000000000001",
            amount=1000,
            amount_min_limit=0,
            interval="month",
            description="Subscription for services",
            reference_code="contract-12345",
            installment_start="2022-01-01T00:00:00+00:00",
            installment_end="2023-01-01T00:00:00+00:00",
            pull_retry_limit=3,
            receiver_name="Stark Bank S.A.",
            receiver_tax_id="20.018.183/0001-80",
            receiver_bank_code="20018183",
            sender_final_name="Jon Snow",
            sender_final_tax_id="012.345.678-90",
            type="qrcodeAndPayment",
            status="approved",
            created="2022-01-01T00:00:00+00:00",
            updated="2022-01-01T00:00:00+00:00"
        )
    )
]
```

## Pix Pull Subscription

A Pix Pull Subscription is a recurring authorization (Pix Automático) that lets a receiver pull Pix payments from a payer's account on a defined schedule.

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

### The Pix Pull Subscription Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix pull subscription. |
| `bacenId` | STRING | Central Bank identifier of the recurring authorization. |
| `amount` | INTEGER | Fixed amount in cents pulled on each cycle. 0 when the amount is variable. |
| `amountMinLimit` | INTEGER | Minimum amount in cents allowed per pull when the amount is variable. |
| `interval` | STRING | Billing interval. Options: "week", "month", "quarter", "semester", "year". |
| `description` | STRING | Description presented to the payer. |
| `referenceCode` | STRING | Free reference code for the subscription. |
| `installmentStart` | STRING | Date when the recurring authorization starts. |
| `installmentEnd` | STRING | Date when the recurring authorization ends. |
| `due` | STRING | Due datetime for the payer to approve the authorization. |
| `pullRetryLimit` | INTEGER | Maximum number of pull retries allowed per cycle. |
| `type` | STRING | Subscription type. Options: "push", "qrcode", "qrcodeAndPayment", "paymentAndOrQrcode". |
| `externalId` | STRING | Unique external id to prevent duplicates. |
| `receiverName` | STRING | Name of the receiver (creditor). |
| `receiverTaxId` | STRING | CPF or CNPJ of the receiver. |
| `receiverBankCode` | STRING | Bank ISPB code of the receiver. |
| `senderTaxId` | STRING | CPF or CNPJ of the payer (debtor). |
| `senderAccountNumber` | STRING | Account number of the payer. |
| `senderBranchCode` | STRING | Branch code of the payer's account. |
| `senderBankCode` | STRING | Bank ISPB code of the payer. |
| `senderFinalName` | STRING | Name of the final payer, when different from the account holder. |
| `senderFinalTaxId` | STRING | CPF or CNPJ of the final payer, when different from the account holder. |
| `senderCityCode` | STRING | IBGE city code of the payer. |
| `status` | STRING | Current status. Options: "created", "pending", "approved", "active", "failed", "denied", "canceled", "expired". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix pull subscription. |
| `flow` | STRING | Direction of the subscription. Options: "out" (you are the receiver), "in" (you are the payer). |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Pix Pull Subscriptions

`POST /v2/pix-pull-subscription`

Create recurring Pix authorizations (Pix Automático).

Authorization is obtained through one of four journeys via the subscription type: push (push notification to the payer's bank), qrcode (QR Code with direct authorization), qrcodeAndPayment (QR Code with authorization upon payment), and paymentAndOrQrcode (billing QR Code with an authorization offer).

**Request**

```python
import starkinfra

subscriptions = starkinfra.pixpullsubscription.create([
    starkinfra.PixPullSubscription(
        type="push",
        external_id="my-subscription-id-1",
        bacen_id="RR20220101200181830000000000001",
        reference_code="contract-12345",
        interval="month",
        installment_start="2022-01-01",
        amount=1000,
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        sender_tax_id="012.345.678-90",
        sender_account_number="00000-0",
        sender_branch_code="0001",
        tags=["automatic", "pix"]
    )
])

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

**Response**

```python
[
    PixPullSubscription(
        id="5656565656565656",
        bacen_id="RR20220101200181830000000000001",
        amount=1000,
        amount_min_limit=0,
        interval="month",
        description="",
        reference_code="contract-12345",
        installment_start="2022-01-01T00:00:00+00:00",
        installment_end="",
        due="",
        pull_retry_limit=3,
        type="push",
        external_id="my-subscription-id-1",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        sender_tax_id="012.345.678-90",
        sender_account_number="00000-0",
        sender_branch_code="0001",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        sender_city_code="",
        status="created",
        tags=["automatic", "pix"],
        flow="out",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Pull Subscriptions

`GET /v2/pix-pull-subscription`

List and filter all Pix pull subscriptions. Results are paged.

**Request**

```python
import starkinfra

subscriptions = starkinfra.pixpullsubscription.query(
    limit=10,
    status="active"
)

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

**Response**

```python
PixPullSubscription(
    id="5656565656565656",
    bacen_id="RR20220101200181830000000000001",
    amount=1000,
    amount_min_limit=0,
    interval="month",
    description="",
    reference_code="contract-12345",
    installment_start="2022-01-01T00:00:00+00:00",
    installment_end="",
    due="",
    pull_retry_limit=3,
    type="push",
    external_id="my-subscription-id-1",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    sender_tax_id="012.345.678-90",
    sender_account_number="00000-0",
    sender_branch_code="0001",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    sender_city_code="",
    status="active",
    tags=["automatic", "pix"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-02T00:00:00+00:00"
)
```

### Get a Pix Pull Subscription

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

Get a single Pix pull subscription by its id.

**Request**

```python
import starkinfra

subscription = starkinfra.pixpullsubscription.get("5656565656565656")

print(subscription)
```

**Response**

```python
PixPullSubscription(
    id="5656565656565656",
    bacen_id="RR20220101200181830000000000001",
    amount=1000,
    amount_min_limit=0,
    interval="month",
    description="",
    reference_code="contract-12345",
    installment_start="2022-01-01T00:00:00+00:00",
    installment_end="",
    due="",
    pull_retry_limit=3,
    type="push",
    external_id="my-subscription-id-1",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    sender_tax_id="012.345.678-90",
    sender_account_number="00000-0",
    sender_branch_code="0001",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    sender_city_code="",
    status="active",
    tags=["automatic", "pix"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-02T00:00:00+00:00"
)
```

### Update a Pix Pull Subscription

`PATCH /v2/pix-pull-subscription/:id`

Approve, deny or activate a Pix pull subscription. The allowed status transitions depend on whether you are the payer or the receiver.

When confirming a received subscription, include the senderCityCode field.

**Request**

```python
import starkinfra

subscription = starkinfra.pixpullsubscription.update(
    "5656565656565656",
    status="approved",
    sender_city_code="3550308"
)

print(subscription)
```

**Response**

```python
PixPullSubscription(
    id="5656565656565656",
    bacen_id="RR20220101200181830000000000001",
    amount=1000,
    amount_min_limit=0,
    interval="month",
    description="",
    reference_code="contract-12345",
    installment_start="2022-01-01T00:00:00+00:00",
    installment_end="",
    due="",
    pull_retry_limit=3,
    type="push",
    external_id="my-subscription-id-1",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    sender_tax_id="012.345.678-90",
    sender_account_number="00000-0",
    sender_branch_code="0001",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    sender_city_code="3550308",
    status="approved",
    tags=["automatic", "pix"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-02T00:00:00+00:00"
)
```

### Cancel a Pix Pull Subscription

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

Cancel a Pix pull subscription.

**Request**

```python
import starkinfra

subscription = starkinfra.pixpullsubscription.cancel("5656565656565656")

print(subscription)
```

**Response**

```python
PixPullSubscription(
    id="5656565656565656",
    bacen_id="RR20220101200181830000000000001",
    amount=1000,
    amount_min_limit=0,
    interval="month",
    description="",
    reference_code="contract-12345",
    installment_start="2022-01-01T00:00:00+00:00",
    installment_end="",
    due="",
    pull_retry_limit=3,
    type="push",
    external_id="my-subscription-id-1",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    sender_tax_id="012.345.678-90",
    sender_account_number="00000-0",
    sender_branch_code="0001",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    sender_city_code="",
    status="canceled",
    tags=["automatic", "pix"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-03T00:00:00+00:00"
)
```

### List Pix Pull Subscription Logs

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

Get a paged list of all Pix pull subscription logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixpullsubscription.log.query(
    limit=10,
    types=["approved"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    subscription=PixPullSubscription(
        id="5656565656565656",
        bacen_id="RR20220101200181830000000000001",
        amount=1000,
        amount_min_limit=0,
        interval="month",
        description="",
        reference_code="contract-12345",
        installment_start="2022-01-01T00:00:00+00:00",
        installment_end="",
        due="",
        pull_retry_limit=3,
        type="push",
        external_id="my-subscription-id-1",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        sender_tax_id="012.345.678-90",
        sender_account_number="00000-0",
        sender_branch_code="0001",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        sender_city_code="",
        status="approved",
        tags=["automatic", "pix"],
        flow="out",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-02T00:00:00+00:00"
    ),
    type="approved",
    errors=[],
    reason="",
    created="2022-01-02T00:00:00+00:00"
)
```

### Get a Pix Pull Subscription Log

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

Get a single Pix pull subscription log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixpullsubscription.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    subscription=PixPullSubscription(
        id="5656565656565656",
        bacen_id="RR20220101200181830000000000001",
        amount=1000,
        amount_min_limit=0,
        interval="month",
        description="",
        reference_code="contract-12345",
        installment_start="2022-01-01T00:00:00+00:00",
        installment_end="",
        due="",
        pull_retry_limit=3,
        type="push",
        external_id="my-subscription-id-1",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        sender_tax_id="012.345.678-90",
        sender_account_number="00000-0",
        sender_branch_code="0001",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        sender_city_code="",
        status="approved",
        tags=["automatic", "pix"],
        flow="out",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-02T00:00:00+00:00"
    ),
    type="approved",
    errors=[],
    reason="",
    created="2022-01-02T00:00:00+00:00"
)
```

## Pix Pull Request

A Pix Pull Request is a single charge issued against an active Pix Pull Subscription (Pix Automático), pulling a payment from the payer's account.

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

### The Pix Pull Request Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix pull request. |
| `amount` | INTEGER | Amount in cents to be pulled. |
| `description` | STRING | Description of the pull request. |
| `due` | STRING | Due datetime for the pull. |
| `endToEndId` | STRING | End-to-end id of the Pix pull request. |
| `reconciliationId` | STRING | Reconciliation id (txid) of the pull. |
| `subscriptionId` | STRING | Id of the Pix pull subscription this request belongs to. |
| `subscriptionBacenId` | STRING | Central Bank id of the related subscription. |
| `receiverName` | STRING | Name of the receiver (creditor). |
| `receiverTaxId` | STRING | CPF or CNPJ of the receiver. |
| `receiverBankCode` | STRING | Bank ISPB code of the receiver. |
| `receiverAccountNumber` | STRING | Account number of the receiver. |
| `receiverBranchCode` | STRING | Branch code of the receiver's account. |
| `receiverAccountType` | STRING | Type of the receiver's account. |
| `senderTaxId` | STRING | CPF or CNPJ of the payer (debtor). |
| `senderBankCode` | STRING | Bank ISPB code of the payer. |
| `senderFinalName` | STRING | Name of the final payer, when different from the account holder. |
| `senderFinalTaxId` | STRING | CPF or CNPJ of the final payer, when different from the account holder. |
| `attemptType` | STRING | Pull attempt type. Options: "default", "scheduledRetry", "instantRetry". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix pull request. |
| `flow` | STRING | Direction of the pull request. Options: "out" (you are the receiver), "in" (you are the payer). |
| `status` | STRING | Current status. Options: "created", "processing", "scheduled", "denied", "success", "failed", "canceled", "expired". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Pix Pull Requests

`POST /v2/pix-pull-request`

Issue charges against active Pix pull subscriptions.

As the receiver bank, create a Pix Pull Request to instruct a debit from the payer's account on a scheduled date. Stark Infra verifies that the subscription is approved, the amount is within the authorized limit, the settlement date matches the subscription's charge cycle, payer/receiver details match the contract, the request is made between 10 and 2 days before settlement, and there is no other scheduled request for the same cycle.

**Request**

```python
import starkinfra

requests = starkinfra.pixpullrequest.create([
    starkinfra.PixPullRequest(
        subscription_id="5656565656565656",
        amount=1000,
        due="2022-02-01T00:00:00+00:00",
        attempt_type="default",
        end_to_end_id="E20018183202201010000000000001",
        reconciliation_id="txid1234567890",
        receiver_account_number="00000-0",
        receiver_account_type="checking",
        tags=["automatic", "pix"]
    )
])

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

**Response**

```python
[
    PixPullRequest(
        id="4646464646464646",
        amount=1000,
        description="",
        due="2022-02-01T00:00:00+00:00",
        end_to_end_id="E20018183202201010000000000001",
        reconciliation_id="txid1234567890",
        subscription_id="5656565656565656",
        subscription_bacen_id="RR20220101200181830000000000001",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        receiver_account_number="00000-0",
        receiver_branch_code="0001",
        receiver_account_type="checking",
        sender_tax_id="012.345.678-90",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        attempt_type="default",
        tags=["automatic", "pix"],
        flow="out",
        status="created",
        created="2022-01-15T00:00:00+00:00",
        updated="2022-01-15T00:00:00+00:00"
    )
]
```

### List Pix Pull Requests

`GET /v2/pix-pull-request`

List and filter all Pix pull requests. Results are paged.

**Request**

```python
import starkinfra

requests = starkinfra.pixpullrequest.query(
    limit=10,
    subscription_ids=["5656565656565656"]
)

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

**Response**

```python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="out",
    status="success",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-02-01T00:00:00+00:00"
)
```

### Get a Pix Pull Request

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

Get a single Pix pull request by its id.

**Request**

```python
import starkinfra

request = starkinfra.pixpullrequest.get("4646464646464646")

print(request)
```

**Response**

```python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="out",
    status="success",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-02-01T00:00:00+00:00"
)
```

### Update a Pix Pull Request

`PATCH /v2/pix-pull-request/:id`

Schedule or deny a Pix pull request. Only the payer may update a pull request.

**Request**

```python
import starkinfra

request = starkinfra.pixpullrequest.update(
    "4646464646464646",
    status="denied",
    reason="senderAccountClosed"
)

print(request)
```

**Response**

```python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="in",
    status="denied",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-01-16T00:00:00+00:00"
)
```

### Cancel a Pix Pull Request

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

Cancel a Pix pull request.

**Request**

```python
import starkinfra

request = starkinfra.pixpullrequest.cancel(
    "4646464646464646",
    reason="senderAccountClosed"
)

print(request)
```

**Response**

```python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="out",
    status="canceled",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-01-16T00:00:00+00:00"
)
```

### List Pix Pull Request Logs

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

Get a paged list of all Pix pull request logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixpullrequest.log.query(
    limit=10,
    types=["success"]
)

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

**Response**

```python
Log(
    id="5757575757575757",
    request=PixPullRequest(
        id="4646464646464646",
        amount=1000,
        description="",
        due="2022-02-01T00:00:00+00:00",
        end_to_end_id="E20018183202201010000000000001",
        reconciliation_id="txid1234567890",
        subscription_id="5656565656565656",
        subscription_bacen_id="RR20220101200181830000000000001",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        receiver_account_number="00000-0",
        receiver_branch_code="0001",
        receiver_account_type="checking",
        sender_tax_id="012.345.678-90",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        attempt_type="default",
        tags=["automatic", "pix"],
        flow="out",
        status="success",
        created="2022-01-15T00:00:00+00:00",
        updated="2022-02-01T00:00:00+00:00"
    ),
    type="success",
    errors=[],
    reason="",
    description="The Pix Pull Request was settled.",
    created="2022-02-01T00:00:00+00:00"
)
```

### Get a Pix Pull Request Log

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

Get a single Pix pull request log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixpullrequest.log.get("5757575757575757")

print(log)
```

**Response**

```python
Log(
    id="5757575757575757",
    request=PixPullRequest(
        id="4646464646464646",
        amount=1000,
        description="",
        due="2022-02-01T00:00:00+00:00",
        end_to_end_id="E20018183202201010000000000001",
        reconciliation_id="txid1234567890",
        subscription_id="5656565656565656",
        subscription_bacen_id="RR20220101200181830000000000001",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        receiver_account_number="00000-0",
        receiver_branch_code="0001",
        receiver_account_type="checking",
        sender_tax_id="012.345.678-90",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        attempt_type="default",
        tags=["automatic", "pix"],
        flow="out",
        status="success",
        created="2022-01-15T00:00:00+00:00",
        updated="2022-02-01T00:00:00+00:00"
    ),
    type="success",
    errors=[],
    reason="",
    description="The Pix Pull Request was settled.",
    created="2022-02-01T00:00:00+00:00"
)
```

## Pix Key

A Pix Key is an alias that can be used to identify a bank account in the Brazilian Pix system (DICT).

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

### The Pix Key Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix key (the key value itself, e.g., CPF, email, phone, EVP). |
| `type` | STRING | Type of the Pix key. Options: "cpf", "cnpj", "phone", "email", "evp". |
| `accountCreated` | STRING | Creation date of the linked bank account. |
| `accountType` | STRING | Type of the linked bank account. Options: "checking", "savings", "salary", "payment", "other". |
| `bankCode` | STRING | Bank ISPB code of the linked account. |
| `branchCode` | STRING | Branch code of the linked bank account. |
| `accountNumber` | STRING | Account number of the linked bank account. |
| `holderName` | STRING | Name of the account holder. |
| `holderTaxId` | STRING | CPF or CNPJ of the account holder. |
| `status` | STRING | Current status. Options: "created", "registered", "canceled", "failed". |
| `owned` | STRING | Datetime when the key was registered in DICT. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create a Pix Key

`POST /v2/pix-key`

Register a new Pix key in DICT for your workspace.

**Request**

```python
import starkinfra

key = starkinfra.pixkey.create(
    starkinfra.PixKey(
        account_created="2022-01-01",
        account_number="10000-0",
        account_type="checking",
        branch_code="0001",
        name="Jon Snow",
        tax_id="012.345.678-90",
        id="jon.snow@starkinfra.com",
        tags=["pix", "key"]
    )
)

print(key)
```

**Response**

```python
PixKey(
    id="jon.snow@starkinfra.com",
    type="email",
    account_created="2022-01-01",
    account_type="checking",
    bank_code="20018183",
    branch_code="0001",
    account_number="10000-0",
    name="Jon Snow",
    tax_id="012.345.678-90",
    status="created",
    owned="2022-01-01T00:00:00+00:00",
    tags=["pix", "key"],
    created="2022-01-01T00:00:00+00:00"
)
```

### List Pix Keys

`GET /v2/pix-key`

List and filter all Pix keys registered in your workspace.

**Request**

```python
import starkinfra

keys = starkinfra.pixkey.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status="registered",
    tags=["pix", "key"],
    ids=["jon.snow@starkinfra.com"],
    type="email",
    tax_id="012.345.678-90"
)

for key in keys:
    print(key)
```

**Response**

```python
<generator object query at 0x...>

PixKey(
    id="jon.snow@starkinfra.com",
    type="email",
    account_created="2022-01-01",
    account_type="checking",
    bank_code="20018183",
    branch_code="0001",
    account_number="10000-0",
    name="Jon Snow",
    tax_id="012.345.678-90",
    status="registered",
    owned="2022-01-01T00:00:00+00:00",
    tags=["pix", "key"],
    created="2022-01-01T00:00:00+00:00"
)
```

### Get a Pix Key

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

Get a single Pix key by its id.

**Request**

```python
import starkinfra

key = starkinfra.pixkey.get(
    "jon.snow@starkinfra.com",
    payer_id="012.345.678-90",
    end_to_end_id="E00002649202201172211u34srod19le",
    expand=["statistics", "owner_statistics"]
)

print(key)
```

**Response**

```python
PixKey(
    id="jon.snow@starkinfra.com",
    type="email",
    account_created="2022-01-01",
    account_type="checking",
    bank_code="20018183",
    branch_code="0001",
    account_number="10000-0",
    name="Jon Snow",
    tax_id="012.345.678-90",
    status="registered",
    owned="2022-01-01T00:00:00+00:00",
    tags=["pix", "key"],
    statistics=[Statistic(after="2022-01-01", type="reconciliations", value=1)],
    owner_statistics=[Statistic(after="2022-01-01", type="settlements", value=3)],
    created="2022-01-01T00:00:00+00:00"
)
```

### Update a Pix Key

`PATCH /v2/pix-key/:id`

Update the account information linked to a Pix key.

**Request**

```python
import starkinfra

key = starkinfra.pixkey.update(
    "jon.snow@starkinfra.com",
    reason="branchTransfer",
    account_created="2022-01-01",
    account_number="20000-1",
    account_type="savings",
    branch_code="0002",
    name="Jon Snow"
)

print(key)
```

**Response**

```python
PixKey(
    id="jon.snow@starkinfra.com",
    type="email",
    account_created="2022-01-01",
    account_type="savings",
    bank_code="20018183",
    branch_code="0002",
    account_number="20000-1",
    name="Jon Snow",
    tax_id="012.345.678-90",
    status="registered",
    owned="2022-01-01T00:00:00+00:00",
    tags=["pix", "key"],
    created="2022-01-01T00:00:00+00:00"
)
```

### Cancel a Pix Key

`DELETE /v2/pix-key/:id`

Cancel a Pix key and remove it from DICT.

**Request**

```python
import starkinfra

key = starkinfra.pixkey.cancel("jon.snow@starkinfra.com")

print(key)
```

**Response**

```python
PixKey(
    id="jon.snow@starkinfra.com",
    type="email",
    account_created="2022-01-01",
    account_type="checking",
    bank_code="20018183",
    branch_code="0001",
    account_number="10000-0",
    name="Jon Snow",
    tax_id="012.345.678-90",
    status="canceled",
    owned="2022-01-01T00:00:00+00:00",
    tags=["pix", "key"],
    created="2022-01-01T00:00:00+00:00"
)
```

### List Pix Key Logs

`GET /v2/pix-key/log`

Get a paged list of all Pix key logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixkey.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    ids=["6767676767676767"],
    types=["registered"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    key=PixKey(
        id="jon.snow@starkinfra.com",
        type="email",
        account_created="2022-01-01",
        account_type="checking",
        bank_code="20018183",
        branch_code="0001",
        account_number="10000-0",
        name="Jon Snow",
        tax_id="012.345.678-90",
        status="registered",
        owned="2022-01-01T00:00:00+00:00",
        tags=["pix", "key"],
        statistics=[Statistic(after="2022-01-01", type="reconciliations", value=1)],
        owner_statistics=[Statistic(after="2022-01-01", type="settlements", value=3)],
        created="2022-01-01T00:00:00+00:00"
    ),
    type="registered",
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Key Log

`GET /v2/pix-key/log/:id`

Get a single Pix key log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixkey.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    key=PixKey(
        id="jon.snow@starkinfra.com",
        type="email",
        account_created="2022-01-01",
        account_type="checking",
        bank_code="20018183",
        branch_code="0001",
        account_number="10000-0",
        name="Jon Snow",
        tax_id="012.345.678-90",
        status="registered",
        owned="2022-01-01T00:00:00+00:00",
        tags=["pix", "key"],
        statistics=[Statistic(after="2022-01-01", type="reconciliations", value=1)],
        owner_statistics=[Statistic(after="2022-01-01", type="settlements", value=3)],
        created="2022-01-01T00:00:00+00:00"
    ),
    type="registered",
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

## Pix Key Holmes

PixKeyHolmes are used by a Pix participant to verify whether a Pix key is registered in DICT, the Brazilian Central Bank's key directory.

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

### The Pix Key Holmes Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix key holmes. |
| `status` | STRING | Current status. Options: "solving", "solved". |
| `keyId` | STRING | Pix key under verification. |
| `result` | STRING | Verification result. Options: "registered", "unregistered". Empty until the status is "solved". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix key holmes. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Pix Key Holmes

`POST /v2/pix-key-holmes`

Request the verification of one or more Pix keys in DICT.

You can create up to 100 Pix key holmes in a single request.

**Request**

```python
import starkinfra

holmes = starkinfra.pixkeyholmes.create([
    starkinfra.PixKeyHolmes(
        key_id="jon.snow@starkinfra.com",
        tags=["key-check"]
    )
])

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

**Response**

```python
[
    PixKeyHolmes(
        id="5656565656565656",
        status="solving",
        key_id="jon.snow@starkinfra.com",
        result="",
        tags=["key-check"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Key Holmes

`GET /v2/pix-key-holmes`

List and filter all Pix key holmes. Results are paged.

**Request**

```python
import starkinfra

holmes = starkinfra.pixkeyholmes.query(
    limit=10,
    status="solved"
)

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

**Response**

```python
<generator object query at 0x...>

PixKeyHolmes(
    id="5656565656565656",
    status="solved",
    key_id="jon.snow@starkinfra.com",
    result="registered",
    tags=["key-check"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:05+00:00"
)
```

### Get a Pix Key Holmes

`GET /v2/pix-key-holmes/:id`

Get a single Pix key holmes by its id.

**Request**

```python
import starkinfra

sherlock = starkinfra.pixkeyholmes.get("5656565656565656")

print(sherlock)
```

**Response**

```python
PixKeyHolmes(
    id="5656565656565656",
    status="solved",
    key_id="jon.snow@starkinfra.com",
    result="registered",
    tags=["key-check"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:05+00:00"
)
```

### List Pix Key Holmes Logs

`GET /v2/pix-key-holmes/log`

Get a paged list of all Pix key holmes logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixkeyholmes.log.query(
    limit=10,
    types="solved"
)

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

**Response**

```python
<generator object query at 0x...>

PixKeyHolmes.Log(
    id="6767676767676767",
    type="solved",
    holmes=PixKeyHolmes(
        id="5656565656565656",
        status="solved",
        key_id="jon.snow@starkinfra.com",
        result="registered",
        tags=["key-check"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:05+00:00"
    ),
    errors=[],
    created="2022-01-01T00:00:05+00:00"
)
```

### Get a Pix Key Holmes Log

`GET /v2/pix-key-holmes/log/:id`

Get a single Pix key holmes log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixkeyholmes.log.get("6767676767676767")

print(log)
```

**Response**

```python
PixKeyHolmes.Log(
    id="6767676767676767",
    type="solved",
    holmes=PixKeyHolmes(
        id="5656565656565656",
        status="solved",
        key_id="jon.snow@starkinfra.com",
        result="registered",
        tags=["key-check"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:05+00:00"
    ),
    errors=[],
    created="2022-01-01T00:00:05+00:00"
)
```

## Pix Claim

A Pix Claim is used to port or own a Pix key from another institution to your workspace.

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

### The Pix Claim Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix claim. |
| `type` | STRING | Type of the claim. Options: "ownership", "portability". |
| `keyType` | STRING | Type of the Pix key being claimed. Options: "cpf", "cnpj", "phone", "email", "evp". |
| `keyId` | STRING | Value of the Pix key being claimed. |
| `status` | STRING | Current status. Options: "created", "failed", "delivered", "confirmed", "success", "canceled". |
| `flow` | STRING | Direction of the Pix claim. Options: "out" (you are claiming a key from another institution), "in" (another institution is claiming a key from you). |
| `name` | STRING | Name of the account holder. |
| `taxId` | STRING | CPF or CNPJ of the account holder. |
| `bacenId` | STRING | Central Bank ID for this Pix claim. |
| `tags` | LIST OF STRINGS | Tags associated with the Pix claim. |
| `claimerBankCode` | STRING | Bank ISPB code of the institution claiming the Pix key. |
| `claimedBankCode` | STRING | Bank ISPB code of the institution that currently owns the Pix key. |
| `branchCode` | STRING | Branch code of the linked bank account. |
| `accountNumber` | STRING | Account number of the linked bank account. |
| `accountType` | STRING | Type of the linked bank account. Options: "checking", "savings", "salary", "payment", "other". |
| `accountCreated` | STRING | Creation date of the linked bank account. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create a Pix Claim

`POST /v2/pix-claim`

Initiate a Pix key portability or ownership claim.

An ownership claim changes the holder of a Pix Key (only phone keyType). A portability claim changes the linked account without changing the holder (phone, email or taxId keyTypes).

**Request**

```python
import starkinfra

claim = starkinfra.pixclaim.create(
    starkinfra.PixClaim(
        account_created="2022-01-01",
        account_number="10000-0",
        account_type="checking",
        branch_code="0001",
        name="Jon Snow",
        tax_id="012.345.678-90",
        key_id="jon.snow@starkinfra.com",
        tags=["claim", "portability"]
    )
)

print(claim)
```

**Response**

```python
PixClaim(
    id="5656565656565656",
    type="portability",
    key_type="email",
    key_id="jon.snow@starkinfra.com",
    status="created",
    flow="out",
    name="Jon Snow",
    tax_id="012.345.678-90",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    tags=["claim", "portability"],
    claimer_bank_code="20018183",
    claimed_bank_code="60701190",
    branch_code="0001",
    account_number="10000-0",
    account_type="checking",
    account_created="2022-01-01T00:00:00+00:00",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### List Pix Claims

`GET /v2/pix-claim`

List and filter all Pix claims. Results are paged.

**Request**

```python
import starkinfra

claims = starkinfra.pixclaim.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["delivered"],
    type="portability",
    flow="out"
)

for claim in claims:
    print(claim)
```

**Response**

```python
<generator object query at 0x...>

PixClaim(
    id="5656565656565656",
    type="portability",
    key_type="email",
    key_id="jon.snow@starkinfra.com",
    status="delivered",
    flow="out",
    name="Jon Snow",
    tax_id="012.345.678-90",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    tags=["claim", "portability"],
    claimer_bank_code="20018183",
    claimed_bank_code="60701190",
    branch_code="0001",
    account_number="10000-0",
    account_type="checking",
    account_created="2022-01-01T00:00:00+00:00",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Claim

`GET /v2/pix-claim/:id`

Get a single Pix claim by its id.

**Request**

```python
import starkinfra

claim = starkinfra.pixclaim.get("5656565656565656")

print(claim)
```

**Response**

```python
PixClaim(
    id="5656565656565656",
    type="portability",
    key_type="email",
    key_id="jon.snow@starkinfra.com",
    status="delivered",
    flow="out",
    name="Jon Snow",
    tax_id="012.345.678-90",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    tags=["claim", "portability"],
    claimer_bank_code="20018183",
    claimed_bank_code="60701190",
    branch_code="0001",
    account_number="10000-0",
    account_type="checking",
    account_created="2022-01-01T00:00:00+00:00",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Update a Pix Claim

`PATCH /v2/pix-claim/:id`

Confirm or cancel an incoming Pix claim.

You must answer an inbound Pix Claim within 7 days of its status changing to delivered. If unanswered, a portability claim is rejected by default and an ownership claim is accepted by default, both with reason defaultBehavior.

You can only confirm Pix Claims with delivered status; confirming deletes the referenced Pix Key from Stark Infra and the Central Bank.

You can only cancel Pix Claims with delivered or confirmed status.

**Request**

```python
import starkinfra

claim = starkinfra.pixclaim.update(
    "5656565656565656",
    status="confirmed",
    reason="userRequested"
)

print(claim)
```

**Response**

```python
PixClaim(
    id="5656565656565656",
    type="portability",
    key_type="email",
    key_id="jon.snow@starkinfra.com",
    status="confirmed",
    flow="out",
    name="Jon Snow",
    tax_id="012.345.678-90",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    tags=["claim", "portability"],
    claimer_bank_code="20018183",
    claimed_bank_code="60701190",
    branch_code="0001",
    account_number="10000-0",
    account_type="checking",
    account_created="2022-01-01T00:00:00+00:00",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:02:00+00:00"
)
```

### List Pix Claim Logs

`GET /v2/pix-claim/log`

Get a paged list of all Pix claim logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixclaim.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["confirmed"],
    claim_ids=["5656565656565656"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    claim=PixClaim(
        id="5656565656565656",
        type="portability",
        key_type="email",
        key_id="jon.snow@starkinfra.com",
        status="delivered",
        flow="out",
        name="Jon Snow",
        tax_id="012.345.678-90",
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        tags=["claim", "portability"],
        claimer_bank_code="20018183",
        claimed_bank_code="60701190",
        branch_code="0001",
        account_number="10000-0",
        account_type="checking",
        account_created="2022-01-01T00:00:00+00:00",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    type="confirmed",
    errors=[],
    reason="userRequested",
    created="2022-01-01T00:02:00+00:00"
)
```

### Get a Pix Claim Log

`GET /v2/pix-claim/log/:id`

Get a single Pix claim log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixclaim.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    claim=PixClaim(
        id="5656565656565656",
        type="portability",
        key_type="email",
        key_id="jon.snow@starkinfra.com",
        status="delivered",
        flow="out",
        name="Jon Snow",
        tax_id="012.345.678-90",
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        tags=["claim", "portability"],
        claimer_bank_code="20018183",
        claimed_bank_code="60701190",
        branch_code="0001",
        account_number="10000-0",
        account_type="checking",
        account_created="2022-01-01T00:00:00+00:00",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    type="confirmed",
    errors=[],
    reason="userRequested",
    created="2022-01-01T00:02:00+00:00"
)
```

## Pix Infraction

A Pix Infraction is used to respond to Pix fraud and operational issues to the Brazilian Central Bank.

Here we will show you how to manage them.

### The Pix Infraction Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix infraction. |
| `referenceId` | STRING | End-to-end id of the transaction the infraction refers to. |
| `type` | STRING | Type of infraction. Options: "fraud", "reversal", "reversalChargeback". |
| `method` | STRING | Fraud method. Options: "scam", "invasion", "other", "unauthorized", "coercion", "unknown". |
| `operatorEmail` | STRING | Contact email of the operator responsible for the Pix infraction. |
| `operatorPhone` | STRING | Contact phone number of the operator responsible for the Pix infraction. |
| `fraudId` | STRING | Id of the Pix fraud marking associated with the infraction. |
| `fraudType` | STRING | Type of fraud associated with the infraction. Options: "identity", "mule", "scam", "other", "unknown". |
| `description` | STRING | Description of the infraction. |
| `analysis` | STRING | Analysis text that justifies the result of the infraction report. |
| `tags` | LIST OF STRINGS | Tags associated with the Pix infraction. |
| `bacenId` | STRING | Id of the infraction at the Brazilian Central Bank. |
| `disputeId` | STRING | Id of the Pix dispute associated with the infraction. |
| `amount` | INTEGER | Amount in cents related to the infraction. Example: 1234 (= R$ 12.34). |
| `flow` | STRING | Direction of the infraction report. Options: "out" (reported by you), "in" (reported against you). |
| `status` | STRING | Current status. Options: "created", "failed", "delivered", "closed", "canceled". |
| `creditedBankCode` | STRING | Bank ISPB code of the credited party. |
| `debitedBankCode` | STRING | Bank ISPB code of the debited party. |
| `reportedBy` | STRING | Institution that reported the infraction. Options: "debited", "credited". |
| `result` | STRING | Result of the infraction analysis. Options: "agreed", "disagreed". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### List Pix Infractions

`GET /v2/pix-infraction`

List and filter all Pix infractions. Results are paged.

**Request**

```python
import starkinfra

infractions = starkinfra.pixinfraction.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["delivered"],
    type=["fraud"],
    flow="out",
    tags=["infraction", "fraud"]
)

for infraction in infractions:
    print(infraction)
```

**Response**

```python
<generator object query at 0x...>

PixInfraction(
    id="5656565656565656",
    reference_id="E20018183202201060100rq1feOMJqtZ",
    type="fraud",
    method="scam",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    fraud_id="5741774970552320",
    fraud_type="scam",
    description="Client reported unauthorized transaction.",
    analysis="Fraud confirmed after investigation.",
    tags=["infraction", "fraud"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="4545454545454545",
    amount=1234,
    flow="out",
    status="delivered",
    credited_bank_code="20018183",
    debited_bank_code="20018183",
    reported_by="credited",
    result="agreed",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Infraction

`GET /v2/pix-infraction/:id`

Get a single Pix infraction by its id.

**Request**

```python
import starkinfra

infraction = starkinfra.pixinfraction.get("5656565656565656")

print(infraction)
```

**Response**

```python
PixInfraction(
    id="5656565656565656",
    reference_id="E20018183202201060100rq1feOMJqtZ",
    type="fraud",
    method="scam",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    fraud_id="5741774970552320",
    fraud_type="scam",
    description="Client reported unauthorized transaction.",
    analysis="Fraud confirmed after investigation.",
    tags=["infraction", "fraud"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="4545454545454545",
    amount=1234,
    flow="out",
    status="delivered",
    credited_bank_code="20018183",
    debited_bank_code="20018183",
    reported_by="credited",
    result="agreed",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Update a Pix Infraction

`PATCH /v2/pix-infraction/:id`

Respond to an incoming Pix infraction report.

Agree with an inbound infraction by patching its analysis to agreed, or disagree by patching it to disagreed.

**Request**

```python
import starkinfra

infraction = starkinfra.pixinfraction.update(
    "5656565656565656",
    result="agreed",
    fraud_type="scam",
    analysis="Fraud confirmed after investigation."
)

print(infraction)
```

**Response**

```python
PixInfraction(
    id="5656565656565656",
    reference_id="E20018183202201060100rq1feOMJqtZ",
    type="fraud",
    method="scam",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    fraud_id="5741774970552320",
    fraud_type="scam",
    description="Client reported unauthorized transaction.",
    analysis="Fraud confirmed after investigation.",
    tags=["infraction", "fraud"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="4545454545454545",
    amount=1234,
    flow="in",
    status="closed",
    credited_bank_code="20018183",
    debited_bank_code="20018183",
    reported_by="debited",
    result="agreed",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:02:00+00:00"
)
```

### Cancel a Pix Infraction

`DELETE /v2/pix-infraction/:id`

Cancel a Pix infraction you reported.

**Request**

```python
import starkinfra

infraction = starkinfra.pixinfraction.cancel("5656565656565656")

print(infraction)
```

**Response**

```python
PixInfraction(
    id="5656565656565656",
    reference_id="E20018183202201060100rq1feOMJqtZ",
    type="fraud",
    method="scam",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    fraud_id="5741774970552320",
    fraud_type="scam",
    description="Client reported unauthorized transaction.",
    analysis="Fraud confirmed after investigation.",
    tags=["infraction", "fraud"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="4545454545454545",
    amount=1234,
    flow="out",
    status="canceled",
    credited_bank_code="20018183",
    debited_bank_code="20018183",
    reported_by="credited",
    result="agreed",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:03:00+00:00"
)
```

### List Pix Infraction Logs

`GET /v2/pix-infraction/log`

Get a paged list of all Pix infraction logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixinfraction.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["delivered"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    infraction=PixInfraction(
        id="5656565656565656",
        reference_id="E20018183202201060100rq1feOMJqtZ",
        type="fraud",
        method="scam",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        fraud_id="5741774970552320",
        fraud_type="scam",
        description="Client reported unauthorized transaction.",
        analysis="Fraud confirmed after investigation.",
        tags=["infraction", "fraud"],
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        dispute_id="4545454545454545",
        amount=1234,
        flow="out",
        status="delivered",
        credited_bank_code="20018183",
        debited_bank_code="20018183",
        reported_by="credited",
        result="agreed",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    type="delivered",
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Infraction Log

`GET /v2/pix-infraction/log/:id`

Get a single Pix infraction log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixinfraction.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    infraction=PixInfraction(
        id="5656565656565656",
        reference_id="E20018183202201060100rq1feOMJqtZ",
        type="fraud",
        method="scam",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        fraud_id="5741774970552320",
        fraud_type="scam",
        description="Client reported unauthorized transaction.",
        analysis="Fraud confirmed after investigation.",
        tags=["infraction", "fraud"],
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        dispute_id="4545454545454545",
        amount=1234,
        flow="out",
        status="delivered",
        credited_bank_code="20018183",
        debited_bank_code="20018183",
        reported_by="credited",
        result="agreed",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    type="delivered",
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

## Pix Chargeback

A Pix Chargeback allows you to request the return of funds from a Pix transaction made in error or due to fraud, and to respond to chargebacks opened against your transactions, through MED.

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

### The Pix Chargeback Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix chargeback. |
| `amount` | INTEGER | Amount in cents to be charged back. |
| `referenceId` | STRING | End-to-end ID of the original Pix transaction. |
| `reason` | STRING | Reason for the chargeback. Options: "fraud", "flaw", "reversalChargeback". |
| `result` | STRING | Result of the chargeback. Options: "rejected", "accepted", "partiallyAccepted". |
| `analysis` | STRING | Analysis text from the responding party. |
| `description` | STRING | Description of the chargeback request. |
| `senderBankCode` | STRING | Bank ISPB code of the sender in the original transaction. |
| `receiverBankCode` | STRING | Bank ISPB code of the receiver in the original transaction. |
| `rejectionReason` | STRING | Reason for rejection if the chargeback was not agreed. Options: "other", "noBalance", "accountClosed", "invalidRequest". |
| `bacenId` | STRING | Central Bank ID for this Pix chargeback. |
| `disputeId` | STRING | Unique id of the Pix dispute associated with the chargeback. |
| `isMonitoringRequired` | BOOLEAN | Indicates whether monitoring is required for this chargeback. |
| `reversalBankCode` | STRING | Bank ISPB code of the account that received the reversal. |
| `reversalBranchCode` | STRING | Branch code of the account that received the reversal. |
| `reversalAccountNumber` | STRING | Number of the account that received the reversal. |
| `reversalAccountType` | STRING | Type of the account that received the reversal. Options: "checking", "savings", "salary", "payment", "other". |
| `reversalTaxId` | STRING | Tax ID (CPF/CNPJ) of the account that received the reversal. |
| `status` | STRING | Current status. Options: "created", "failed", "delivered", "closed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix chargeback. |
| `flow` | STRING | Direction of the chargeback. Options: "out" (you requested), "in" (requested against you). |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Pix Chargebacks

`POST /v2/pix-chargeback`

Request a chargeback for a Pix transaction.

A Pix Chargeback requests the reversal of a Pix transaction and should only be created after a corresponding Pix Infraction is completed (or a system malfunction). The other participant must answer within 24 hours. The only supported reason is flaw — reversing an erroneous transaction caused by a system malfunction.

**Request**

```python
import starkinfra

chargebacks = starkinfra.pixchargeback.create([
    starkinfra.PixChargeback(
        amount=1000,
        reason="flaw",
        reference_id="E20018183202201201450u34sDjD7334",
        description="Chargeback request due to confirmed fraud",
        tags=["chargeback", "fraud"]
    )
])

for chargeback in chargebacks:
    print(chargeback)
```

**Response**

```python
[
    PixChargeback(
        id="5656565656565656",
        amount=1000,
        reference_id="E20018183202201201450u34sDjD7334",
        reason="flaw",
        result=None,
        analysis=None,
        description="Chargeback request due to confirmed fraud",
        sender_bank_code="20018183",
        receiver_bank_code="34052649",
        rejection_reason=None,
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        dispute_id="d20018183202201201450u34sDjD7334",
        is_monitoring_required=False,
        reversal_bank_code=None,
        reversal_branch_code=None,
        reversal_account_number=None,
        reversal_account_type=None,
        reversal_tax_id=None,
        status="created",
        tags=["chargeback", "fraud"],
        flow="out",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Chargebacks

`GET /v2/pix-chargeback`

List and filter all Pix chargebacks. Results are paged.

**Request**

```python
import starkinfra

chargebacks = starkinfra.pixchargeback.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["delivered"],
    ids=["5656565656565656"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    reference_ids=["E20018183202201201450u34sDjD7334"],
    flow="out",
    tags=["fraud"]
)

for chargeback in chargebacks:
    print(chargeback)
```

**Response**

```python
PixChargeback(
    id="5656565656565656",
    amount=1000,
    reference_id="E20018183202201201450u34sDjD7334",
    reason="fraud",
    result=None,
    analysis=None,
    description="Chargeback request due to confirmed fraud",
    sender_bank_code="20018183",
    receiver_bank_code="34052649",
    rejection_reason=None,
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="d20018183202201201450u34sDjD7334",
    is_monitoring_required=False,
    reversal_bank_code=None,
    reversal_branch_code=None,
    reversal_account_number=None,
    reversal_account_type=None,
    reversal_tax_id=None,
    status="delivered",
    tags=["fraud"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Pix Chargeback

`GET /v2/pix-chargeback/:id`

Get a single Pix chargeback by its id.

**Request**

```python
import starkinfra

chargeback = starkinfra.pixchargeback.get("5656565656565656")

print(chargeback)
```

**Response**

```python
PixChargeback(
    id="5656565656565656",
    amount=1000,
    reference_id="E20018183202201201450u34sDjD7334",
    reason="fraud",
    result=None,
    analysis=None,
    description="Chargeback request due to confirmed fraud",
    sender_bank_code="20018183",
    receiver_bank_code="34052649",
    rejection_reason=None,
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="d20018183202201201450u34sDjD7334",
    is_monitoring_required=False,
    reversal_bank_code=None,
    reversal_branch_code=None,
    reversal_account_number=None,
    reversal_account_type=None,
    reversal_tax_id=None,
    status="delivered",
    tags=["fraud"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Update a Pix Chargeback

`PATCH /v2/pix-chargeback/:id`

Respond to an incoming Pix chargeback request.

**Request**

```python
import starkinfra

chargeback = starkinfra.pixchargeback.update(
    "5656565656565656",
    result="agreed",
    analysis="Fraud confirmed, agreeing to chargeback.",
    reversal_reference_id="D20018183202201201450u34sDjD7334"
)

print(chargeback)
```

**Response**

```python
PixChargeback(
    id="5656565656565656",
    amount=1000,
    reference_id="E20018183202201201450u34sDjD7334",
    reason="fraud",
    result="agreed",
    analysis="Fraud confirmed, agreeing to chargeback.",
    description="Chargeback request due to confirmed fraud",
    sender_bank_code="20018183",
    receiver_bank_code="34052649",
    rejection_reason=None,
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="d20018183202201201450u34sDjD7334",
    is_monitoring_required=False,
    reversal_bank_code="20018183",
    reversal_branch_code="0001",
    reversal_account_number="5341615776841728",
    reversal_account_type="checking",
    reversal_tax_id="012.345.678-90",
    status="closed",
    tags=["chargeback", "fraud"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-06-01T00:00:00+00:00"
)
```

### Cancel a Pix Chargeback

`DELETE /v2/pix-chargeback/:id`

Cancel a Pix chargeback you requested.

**Request**

```python
import starkinfra

chargeback = starkinfra.pixchargeback.cancel("5656565656565656")

print(chargeback)
```

**Response**

```python
PixChargeback(
    id="5656565656565656",
    amount=1000,
    reference_id="E20018183202201201450u34sDjD7334",
    reason="fraud",
    result=None,
    analysis=None,
    description="Chargeback request due to confirmed fraud",
    sender_bank_code="20018183",
    receiver_bank_code="34052649",
    rejection_reason=None,
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="d20018183202201201450u34sDjD7334",
    is_monitoring_required=False,
    reversal_bank_code=None,
    reversal_branch_code=None,
    reversal_account_number=None,
    reversal_account_type=None,
    reversal_tax_id=None,
    status="canceled",
    tags=["chargeback", "fraud"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-06-01T00:00:00+00:00"
)
```

### List Pix Chargeback Logs

`GET /v2/pix-chargeback/log`

Get a paged list of all Pix chargeback logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixchargeback.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["delivered"],
    chargeback_ids=["5656565656565656"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    chargeback=PixChargeback(
        id="5656565656565656",
        amount=1000,
        reference_id="E20018183202201201450u34sDjD7334",
        reason="flaw",
        result=None,
        analysis=None,
        description="Chargeback request due to confirmed fraud",
        sender_bank_code="20018183",
        receiver_bank_code="34052649",
        rejection_reason=None,
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        dispute_id="d20018183202201201450u34sDjD7334",
        is_monitoring_required=False,
        reversal_bank_code=None,
        reversal_branch_code=None,
        reversal_account_number=None,
        reversal_account_type=None,
        reversal_tax_id=None,
        status="delivered",
        tags=["fraud"],
        flow="out",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    type="delivered",
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Chargeback Log

`GET /v2/pix-chargeback/log/:id`

Get a single Pix chargeback log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixchargeback.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    chargeback=PixChargeback(
        id="5656565656565656",
        amount=1000,
        reference_id="E20018183202201201450u34sDjD7334",
        reason="flaw",
        result=None,
        analysis=None,
        description="Chargeback request due to confirmed fraud",
        sender_bank_code="20018183",
        receiver_bank_code="34052649",
        rejection_reason=None,
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        dispute_id="d20018183202201201450u34sDjD7334",
        is_monitoring_required=False,
        reversal_bank_code=None,
        reversal_branch_code=None,
        reversal_account_number=None,
        reversal_account_type=None,
        reversal_tax_id=None,
        status="delivered",
        tags=["fraud"],
        flow="out",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    type="delivered",
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

## Pix Fraud

A Pix Fraud report allows you to flag suspicious users or keys in the Brazilian Pix system (DICT).

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

### The Pix Fraud Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix fraud report. |
| `externalId` | STRING | Unique external ID to prevent duplicates. |
| `type` | STRING | Type of fraud. Options: "identity", "mule", "scam", "other", "unknown". |
| `taxId` | STRING | CPF or CNPJ of the fraudster. |
| `keyId` | STRING | Pix key associated with the fraud. |
| `bacenId` | STRING | Central Bank ID for this fraud report. |
| `status` | STRING | Current status. Options: "created", "failed", "registered", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix fraud report. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Pix Fraud Reports

`POST /v2/pix-fraud`

Report a fraudulent user or Pix key to DICT.

**Request**

```python
import starkinfra

frauds = starkinfra.pixfraud.create([
    starkinfra.PixFraud(
        external_id="my-fraud-id-1",
        type="mule",
        tax_id="012.345.678-90",
        key_id="jon.snow@starkinfra.com",
        tags=["fraud", "mule"]
    )
])

for fraud in frauds:
    print(fraud)
```

**Response**

```python
[
    PixFraud(
        id="5656565656565656",
        external_id="my-fraud-id-1",
        type="mule",
        tax_id="012.345.678-90",
        key_id="jon.snow@starkinfra.com",
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        status="created",
        tags=["fraud", "mule"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Fraud Reports

`GET /v2/pix-fraud`

List and filter all Pix fraud reports. Results are paged.

**Request**

```python
import starkinfra

frauds = starkinfra.pixfraud.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["registered"],
    type=["mule"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    tags=["fraud", "mule"]
)

for fraud in frauds:
    print(fraud)
```

**Response**

```python
<generator object query at 0x...>

PixFraud(
    id="5656565656565656",
    external_id="my-fraud-id-1",
    type="mule",
    tax_id="012.345.678-90",
    key_id="jon.snow@starkinfra.com",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    status="registered",
    tags=["fraud", "mule"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Fraud Report

`GET /v2/pix-fraud/:id`

Get a single Pix fraud report by its id.

**Request**

```python
import starkinfra

fraud = starkinfra.pixfraud.get("5656565656565656")

print(fraud)
```

**Response**

```python
PixFraud(
    id="5656565656565656",
    external_id="my-fraud-id-1",
    type="mule",
    tax_id="012.345.678-90",
    key_id="jon.snow@starkinfra.com",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    status="registered",
    tags=["fraud", "mule"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Cancel a Pix Fraud Report

`DELETE /v2/pix-fraud/:id`

Cancel a Pix fraud report you submitted.

**Request**

```python
import starkinfra

fraud = starkinfra.pixfraud.cancel("5656565656565656")

print(fraud)
```

**Response**

```python
PixFraud(
    id="5656565656565656",
    external_id="my-fraud-id-1",
    type="mule",
    tax_id="012.345.678-90",
    key_id="jon.snow@starkinfra.com",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    status="canceled",
    tags=["fraud", "mule"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:02:00+00:00"
)
```

### List Pix Fraud Logs

`GET /v2/pix-fraud/log`

Get a paged list of all Pix fraud logs.

### Get a Pix Fraud Log

`GET /v2/pix-fraud/log/:id`

Get a single Pix fraud log by its id.

## Pix Dispute

A Pix Dispute allows you to request, cancel and consult disputes related to Pix transactions through MED 2.0.

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

### The Pix Dispute Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix dispute. |
| `referenceId` | STRING | End-to-end ID of the original Pix transaction. |
| `bacenId` | STRING | Central Bank's unique ID for the Pix dispute. |
| `method` | STRING | Method of the dispute. Options: "scam", "unauthorized", "coercion", "invasion", "other", "unknown". |
| `description` | STRING | Description of the Pix dispute. |
| `operatorEmail` | STRING | Contact email of the operator responsible for the Pix dispute. |
| `operatorPhone` | STRING | Contact phone number of the operator responsible for the Pix dispute. |
| `status` | STRING | Current status. Options: "created", "failed", "delivered", "analysed", "processing", "closed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix dispute. |
| `flow` | STRING | Direction of the dispute. Options: "out" (you initiated), "in" (raised against you). |
| `minTransactionAmount` | INTEGER | Minimum amount in cents of the transactions to be tracked in the dispute. |
| `maxTransactionCount` | INTEGER | Maximum number of transactions to be tracked in the dispute. |
| `maxHopCount` | INTEGER | Maximum number of hops to be tracked in the dispute. |
| `maxHopInterval` | INTEGER | Maximum interval in seconds between hops to be tracked in the dispute. |
| `transactions` | LIST OF OBJECTS | List of transaction objects tracked in the dispute. |
| `transactions.endToEndId` | STRING | End-to-end ID of the tracked Pix transaction. |
| `transactions.amount` | INTEGER | Transaction amount in cents. |
| `transactions.nominalAmount` | INTEGER | Refundable amount in cents of the transaction. |
| `transactions.senderId` | STRING | Bacen-generated pseudo ID for the sender, used only for transaction-tracking context (not a real account identifier). |
| `transactions.senderType` | STRING | Type of the sender entity. Options: "individual", "business". |
| `transactions.senderTaxIdCreated` | STRING | Returned only for CNPJ tax IDs: the date the sender company was opened. Example: "2020-04-23T23:00:00.000000+00:00". |
| `transactions.senderAccountCreated` | STRING | Datetime when the sender's account was opened. Example: "2020-04-23T23:00:00.000000+00:00". |
| `transactions.senderBankCode` | STRING | Bank code of the sender's institution. |
| `transactions.receiverId` | STRING | Bacen-generated pseudo ID for the receiver, used only for transaction-tracking context (not a real account identifier). |
| `transactions.receiverType` | STRING | Type of the receiver entity. Options: "individual", "business". |
| `transactions.receiverTaxIdCreated` | STRING | Returned only for CNPJ tax IDs: the date the receiver company was opened. Example: "2020-04-23T23:00:00.000000+00:00". |
| `transactions.receiverAccountCreated` | STRING | Datetime when the receiver's account was opened. Example: "2020-04-23T23:00:00.000000+00:00". |
| `transactions.receiverBankCode` | STRING | Bank code of the receiver's institution. |
| `transactions.settled` | STRING | Datetime when the transaction was settled. Example: "2020-04-23T23:00:00.000000+00:00". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Pix Disputes

`POST /v2/pix-dispute`

Initiate a Pix dispute for a transaction.

**Request**

```python
import starkinfra

disputes = starkinfra.pixdispute.create([
    starkinfra.PixDispute(
        reference_id="E20018183202201201450u34sDjD7334",
        method="scam",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        description="Transaction reported by the account holder as fraudulent.",
        min_transaction_amount=100,
        max_transaction_count=10,
        max_hop_count=5,
        max_hop_interval=3600,
        tags=["dispute", "scam"]
    )
])

for dispute in disputes:
    print(dispute)
```

**Response**

```python
[
    PixDispute(
        id="5656565656565656",
        reference_id="E20018183202201201450u34sDjD7334",
        bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
        method="scam",
        description="Transaction reported by the account holder as fraudulent.",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        status="created",
        tags=["dispute", "scam"],
        flow="out",
        min_transaction_amount=100,
        max_transaction_count=10,
        max_hop_count=5,
        max_hop_interval=3600,
        transactions=[],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Disputes

`GET /v2/pix-dispute`

List and filter all Pix disputes. Results are paged.

**Request**

```python
import starkinfra

disputes = starkinfra.pixdispute.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status="delivered",
    flow="out",
    bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
    reference_ids=["E20018183202201201450u34sDjD7334"],
    ids=["5656565656565656", "4545454545454545"],
    tags=["scam"]
)

for dispute in disputes:
    print(dispute)
```

**Response**

```python
PixDispute(
    id="5656565656565656",
    reference_id="E20018183202201201450u34sDjD7334",
    bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
    method="scam",
    description="Transaction reported by the account holder as fraudulent.",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    status="delivered",
    tags=["scam"],
    flow="out",
    min_transaction_amount=100,
    max_transaction_count=10,
    max_hop_count=5,
    max_hop_interval=3600,
    transactions=[],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Pix Dispute

`GET /v2/pix-dispute/:id`

Get a single Pix dispute by its id.

**Request**

```python
import starkinfra

dispute = starkinfra.pixdispute.get("5656565656565656")

print(dispute)
```

**Response**

```python
PixDispute(
    id="5656565656565656",
    reference_id="E20018183202201201450u34sDjD7334",
    bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
    method="scam",
    description="Transaction reported by the account holder as fraudulent.",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    status="delivered",
    tags=["dispute", "scam"],
    flow="out",
    min_transaction_amount=100,
    max_transaction_count=10,
    max_hop_count=5,
    max_hop_interval=3600,
    transactions=[],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Cancel a Pix Dispute

`DELETE /v2/pix-dispute/:id`

Cancel a Pix dispute you initiated.

**Request**

```python
import starkinfra

dispute = starkinfra.pixdispute.cancel("5656565656565656")

print(dispute)
```

**Response**

```python
PixDispute(
    id="5656565656565656",
    reference_id="E20018183202201201450u34sDjD7334",
    bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
    method="scam",
    description="Transaction reported by the account holder as fraudulent.",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    status="canceled",
    tags=["dispute", "scam"],
    flow="out",
    min_transaction_amount=100,
    max_transaction_count=10,
    max_hop_count=5,
    max_hop_interval=3600,
    transactions=[],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-06-01T00:00:00+00:00"
)
```

### List Pix Dispute Logs

`GET /v2/pix-dispute/log`

Get a paged list of all Pix dispute logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixdispute.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["delivered"],
    dispute_ids=["5656565656565656"],
    ids=["6767676767676767"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    type="delivered",
    dispute=PixDispute(
        id="5656565656565656",
        reference_id="E20018183202201201450u34sDjD7334",
        bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
        method="scam",
        description="Transaction reported by the account holder as fraudulent.",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        status="delivered",
        tags=["dispute", "scam"],
        flow="out",
        min_transaction_amount=100,
        max_transaction_count=10,
        max_hop_count=5,
        max_hop_interval=3600,
        transactions=[],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Dispute Log

`GET /v2/pix-dispute/log/:id`

Get a single Pix dispute log by its id.

**Request**

```python
import starkinfra

log = starkinfra.pixdispute.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    type="delivered",
    dispute=PixDispute(
        id="5656565656565656",
        reference_id="E20018183202201201450u34sDjD7334",
        bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
        method="scam",
        description="Transaction reported by the account holder as fraudulent.",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        status="delivered",
        tags=["dispute", "scam"],
        flow="out",
        min_transaction_amount=100,
        max_transaction_count=10,
        max_hop_count=5,
        max_hop_interval=3600,
        transactions=[],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    created="2022-01-01T00:01:00+00:00"
)
```

## Pix User

The Pix User resource lets you consult, through DICT, an end user's statistics on Pix keys, Pix requests, frauds and infractions registered across Bacen's systems (e.g. SPI for Pix requests).

Here we will show you how to retrieve user data.

### The Pix User Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Tax ID (CPF or CNPJ) used to query the user. |
| `statistics.value` | INTEGER | Number of occurrences counted for this statistic. |
| `statistics.type` | STRING | Type of the statistic; the valid values depend on the source. Options: "registered", "unique" (pix-key); "settled" (pix-request); "identity", "mule", "scam", "other", "unknown", "amount", "unique" (pix-fraud); "open", "denied", "unique" (pix-infraction). |
| `statistics.source` | STRING | Source of the statistic. Options: "pix-key", "pix-fraud", "pix-request", "pix-infraction". |
| `statistics.after` | STRING | Datetime from which the statistic was computed. Example: "2020-04-23T23:00:00.000000+00:00". |
| `statistics.updated` | STRING | Last update datetime of the statistic. Example: "2020-04-23T23:00:00.000000+00:00". |

### Get a Pix User

`GET /v2/pix-user/:taxId`

Retrieve a user's aggregated Pix statistics — Pix keys, Pix requests, frauds and infractions — for a specific user by their tax ID.

**Request**

```python
import starkinfra

user = starkinfra.pixuser.get("012.345.678-90")

print(user)
```

**Response**

```python
PixUser(
    id="012.345.678-90",
    statistics=[
        PixUser.Statistics(
            value=3,
            type="open",
            source="pix-infraction",
            after="2020-04-23T23:00:00.000000+00:00",
            updated="2020-04-23T23:00:00.000000+00:00"
        )
    ]
)
```

## Pix Balance

The Pix Balance represents the current available balance in your Pix account.

Here we will show you how to retrieve it.

### The Pix Balance Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Identifier of the balance. Holds the participant bank code for direct participants or the workspace id for indirect participants. |
| `currency` | STRING | Currency of the balance amount. Example: "BRL". |
| `amount` | INTEGER | Current balance amount in cents. Example: 1234 (R$ 12.34). |
| `updated` | STRING | ISO datetime that represents when the balance was last updated. Example: "2020-04-23T23:00:00.000000+00:00". |

### Get Pix Balance

`GET /v2/pix-balance`

Retrieve the current Pix balance of your workspace.

**Request**

```python
import starkinfra

balance = starkinfra.pixbalance.get(
    before="2022-01-31"
)

print(balance)
```

**Response**

```python
PixBalance(
    id="5656565656565656",
    amount=10000000,
    currency="BRL",
    updated="2022-01-01T00:00:00+00:00"
)
```

## Pix Domain

Pix Domains are the domains Pix participants register with Bacen to provide Brcodes, along with their respective certificate chains used for secure communication.

Here we will show you how to list them.

### The Pix Domain Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `name` | STRING | Domain name registered in the Pix system. |
| `certificates` | LIST OF OBJECTS | List of certificate objects that make up the domain's certificate chain. |
| `certificates.content` | STRING | Certificate in PEM format. |

### List Pix Domains

`GET /v2/pix-domain`

List all registered Pix domains and their certificate chains.

**Request**

```python
import starkinfra

domains = starkinfra.pixdomain.query()

for domain in domains:
    print(domain)
```

**Response**

```python
PixDomain(
    name="pix.starkbank.com",
    certificates=[
        pixdomain.Certificate(
            content="-----BEGIN CERTIFICATE-----..."
        )
    ]
)
```

## Pix Statement

A Pix Statement allows you to request a detailed report of all Pix transactions in your account for a given period.

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

### The Pix Statement Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix statement. |
| `after` | STRING | Start date of the statement period. |
| `before` | STRING | End date of the statement period. |
| `type` | STRING | Type of the statement. Options: "interchange", "interchangeTotal", "transaction". |
| `status` | STRING | Current status. Options: "created", "looking", "success", "failed". |
| `chunkCount` | INTEGER | Number of chunks the statement file is split into. Each chunk can be downloaded individually. |
| `transactionCount` | INTEGER | Number of transactions in the statement. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create a Pix Statement

`POST /v2/pix-statement`

Request a Pix statement for a specific period and type.

**Request**

```python
import starkinfra

statement = starkinfra.pixstatement.create(
    starkinfra.PixStatement(
        after="2022-01-01",
        before="2022-01-31",
        type="transaction"
    )
)

print(statement)
```

**Response**

```python
PixStatement(
    id="5656565656565656",
    after="2022-01-01",
    before="2022-01-31",
    type="transaction",
    status="created",
    chunk_count=0,
    transaction_count=0,
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### List Pix Statements

`GET /v2/pix-statement`

List and filter all Pix statements. Results are paged.

**Request**

```python
import starkinfra

statements = starkinfra.pixstatement.query(limit=10)

for statement in statements:
    print(statement)
```

**Response**

```python
<generator object query at 0x...>

PixStatement(
    id="5656565656565656",
    after="2022-01-01",
    before="2022-01-31",
    type="transaction",
    status="success",
    chunk_count=2,
    transaction_count=150,
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:05:00+00:00"
)
```

### Get a Pix Statement

`GET /v2/pix-statement/:id`

Get a single Pix statement by its id.

**Request**

```python
import starkinfra

statement = starkinfra.pixstatement.get("5656565656565656")

print(statement)
```

**Response**

```python
PixStatement(
    id="5656565656565656",
    after="2022-01-01",
    before="2022-01-31",
    type="transaction",
    status="success",
    chunk_count=2,
    transaction_count=150,
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:05:00+00:00"
)
```

### Get a Pix Statement CSV

`GET /v2/pix-statement/:id/csv`

Get the CSV file for a completed Pix statement. The file is returned compressed in the gzip format.

**Request**

```python
import starkinfra

csv = starkinfra.pixstatement.csv("5656565656565656")

with open("statement.zip", "wb") as f:
    f.write(csv)
```

**Response**

```python
<bytes: statement zip file content>
```

### Get a Pix Statement Chunk

`GET /v2/pix-statement/:id/chunk/:number`

Get a single chunk of a completed Pix statement. Large statements are split into numbered parts, letting you download one chunk at a time. The chunk is returned compressed in the gzip format.

## Pix Director

The Pix Director represents the responsible officer for Pix operations in your institution, as required by the Brazilian Central Bank.

Here we will show you how to register them.

### The Pix Director Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `name` | STRING | Full name of the director. |
| `taxId` | STRING | CPF of the director. |
| `phone` | STRING | Phone number of the director. |
| `email` | STRING | Email address of the director. |
| `password` | STRING | Password for director access. |
| `teamEmail` | STRING | Team email for Pix notifications. |
| `teamPhones` | LIST OF STRINGS | List of team phone numbers for Pix notifications. |
| `status` | STRING | Current registration status of the Pix director. Options: "success", "processing", "failed". |

### Create a Pix Director

`POST /v2/pix-director`

Register the Pix director for your institution as required by the Brazilian Central Bank.

**Request**

```python
import starkinfra

director = starkinfra.pixdirector.create(
    starkinfra.PixDirector(
        name="Jon Snow",
        tax_id="012.345.678-90",
        phone="+5511999999999",
        email="jon.snow@starkinfra.com",
        password="P@ssword1234",
        team_email="team@starkinfra.com",
        team_phones=["+5511888888888", "+5511777777777"]
    )
)

print(director)
```

**Response**

```python
PixDirector(
    id="5656565656565656",
    name="Jon Snow",
    tax_id="012.345.678-90",
    phone="+5511999999999",
    email="jon.snow@starkinfra.com",
    password="P@ssword1234",
    team_email="team@starkinfra.com",
    team_phones=["+5511888888888", "+5511777777777"],
    status="success"
)
```

# Issuing

## Issuing Balance

The Issuing Balance resource represents the total funds available in your issuing wallet.

This balance is separate from your main Stark Infra balance and is used exclusively for card spending.

Fund your issuing balance using Issuing Invoices and withdraw using Issuing Withdrawals.

### The Issuing Balance object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing balance. |
| `amount` | INTEGER | Current issuing balance amount in cents. Example: 5000000 (R$50,000.00). |
| `limit` | INTEGER | Spending limit of the balance. |
| `maxLimit` | INTEGER | Maximum spending limit. This field is currently always equal to limit. |
| `currency` | STRING | Currency code of the balance. Example: "BRL". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Get the Issuing Balance

`GET /v2/issuing-balance`

Get the current balance in your issuing wallet.

**Request**

```python
import starkinfra

balance = starkinfra.issuingbalance.get()

print(balance)
```

**Response**

```python
IssuingBalance(
    id=5715709195239424,
    amount=5000000,
    limit=100000000,
    max_limit=100000000,
    currency=BRL,
    updated=2022-01-01 00:00:00
)
```

## Issuing Product

The Issuing Product resource lists the card products available to your workspace.

Each product has a network, funding type, holder type, and product code that define the characteristics of cards that can be created using that product.

### The Issuing Product object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing product. |
| `network` | STRING | Card network. Options: "Mastercard", "Visa". |
| `fundingType` | STRING | Funding type of the card. Options: "prepaid", "credit". |
| `holderType` | STRING | Holder type for the card. Options: "individual", "business". |
| `code` | STRING | Product code that identifies the specific card product. |
| `settlement` | STRING | Same as fundingType. Kept for backward compatibility. |
| `client` | STRING | Same as holderType. Kept for backward compatibility. |
| `customerType` | STRING | Same as holderType. Kept for backward compatibility. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Issuing Products

`GET /v2/issuing-product`

Get a list of available issuing products for your workspace.

**Request**

```python
import starkinfra

products = starkinfra.issuingproduct.query()

for product in products:
    print(product)
```

**Response**

```python
IssuingProduct(
    id=5715709195239424,
    network=Mastercard,
    funding_type=credit,
    holder_type=individual,
    code=ABC,
    settlement=credit,
    client=individual,
    customer_type=individual,
    created=2022-01-01 00:00:00
)
```

## Issuing Holder

The Issuing Holder resource represents the card holder entity in your workspace.

A holder is associated with one or more issuing cards and defines who can use the cards issued.

You can set rules on the holder level to control spending limits and merchant restrictions.

### The Issuing Holder object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing holder. |
| `name` | STRING | Full name of the holder. |
| `taxId` | STRING | Holder CPF (11 digits) or CNPJ (14 digits). |
| `externalId` | STRING | Your external reference for this holder. Must be unique per workspace to prevent duplicates. |
| `status` | STRING | Current holder status. Options: "active", "blocked", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the holder. |
| `rules` | LIST OF OBJECTS | List of spending rule objects applied to the holder. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Issuing Holders

`POST /v2/issuing-holder`

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

**Request**

```python
import starkinfra

holders = starkinfra.issuingholder.create([
    starkinfra.IssuingHolder(
        name="Tony Stark",
        tax_id="012.345.678-90",
        external_id="my-holder-id-1234",
        tags=["department: tech", "team: backend"],
        rules=[
            starkinfra.IssuingRule(
                name="max-spend",
                interval="day",
                amount=10000,
                currency_code="BRL"
            )
        ]
    )
])

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

**Response**

```python
IssuingHolder(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    external_id=my-holder-id-1234,
    status=active,
    tags=['department: tech'],
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Holders

`GET /v2/issuing-holder`

Get a list of issuing holders in chunks of at most 100.

**Request**

```python
import starkinfra

holders = starkinfra.issuingholder.query(
    limit=10,
    status="active"
)

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

**Response**

```python
IssuingHolder(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    external_id=my-holder-id-1234,
    status=active,
    tags=['department: tech'],
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Holder

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

Get a single issuing holder by its id.

**Request**

```python
import starkinfra

holder = starkinfra.issuingholder.get("5715709195239424")

print(holder)
```

**Response**

```python
IssuingHolder(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    external_id=my-holder-id-1234,
    status=active,
    tags=['department: tech'],
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Update an Issuing Holder

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

Update the properties of an existing issuing holder.

**Request**

```python
import starkinfra

holder = starkinfra.issuingholder.update(
    "5715709195239424",
    status="blocked"
)

print(holder)
```

**Response**

```python
IssuingHolder(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    external_id=my-holder-id-1234,
    status=blocked,
    tags=['department: tech'],
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### Cancel an Issuing Holder

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

Cancel an issuing holder. This action is irreversible.

**Request**

```python
import starkinfra

holder = starkinfra.issuingholder.cancel("5715709195239424")

print(holder)
```

**Response**

```python
IssuingHolder(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    external_id=my-holder-id-1234,
    status=canceled,
    tags=['department: tech'],
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### List Issuing Holder Logs

`GET /v2/issuing-holder/log`

Get a paged list of issuing holder logs.

**Request**

```python
import starkinfra

logs = starkinfra.issuingholder.log.query(limit=10)

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

**Response**

```python
Log(
    id=5715709195239424,
    type=created,
    holder=IssuingHolder(id=5715709195239424, name=Tony Stark, status=active),
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Holder Log

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

Get a single issuing holder log by its id.

**Request**

```python
import starkinfra

log = starkinfra.issuingholder.log.get("5715709195239424")

print(log)
```

**Response**

```python
Log(
    id=5715709195239424,
    type=created,
    holder=IssuingHolder(id=5715709195239424, name=Tony Stark, status=active),
    created=2022-01-01 00:00:00
)
```

## Issuing Card

The Issuing Card resource represents a physical or virtual card issued to a holder.

Cards can be created as virtual (immediately available) or physical (requires embossing and shipping).

You can set rules on the card level to control spending limits, merchant restrictions, and other card behaviors.

### The Issuing Card object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing card. |
| `holderId` | STRING | Id of the IssuingHolder associated with this card. |
| `holderName` | STRING | Name of the holder printed on the card. |
| `holderTaxId` | STRING | Tax id of the IssuingHolder associated with this card. |
| `holderExternalId` | STRING | External id of the IssuingHolder associated with this card. |
| `displayName` | STRING | Name displayed on the card face. Example: "TONY STARK". |
| `rules` | LIST OF OBJECTS | List of spending rule objects applied to the card. |
| `productId` | STRING | Id of the IssuingProduct associated with this card. |
| `tags` | LIST OF STRINGS | Tags associated with the card. |
| `streetLine1` | STRING | Primary line of the billing address. |
| `streetLine2` | STRING | Secondary line of the billing address. |
| `district` | STRING | District of the billing address. |
| `city` | STRING | City of the billing address. |
| `stateCode` | STRING | State code of the billing address. Example: "SP". |
| `zipCode` | STRING | ZIP code of the billing address. Example: "01311-000". |
| `type` | STRING | Card type. Options: "virtual", "physical". |
| `status` | STRING | Current card status. Options: "active", "blocked", "canceled", "expired". |
| `number` | STRING | Card number (PAN). Masked unless "expand=number" is informed in the request. |
| `securityCode` | STRING | Card security code (CVV). Masked unless "expand=securityCode" is informed in the request. |
| `expiration` | STRING | Card expiration datetime. Masked unless "expand=expiration" is informed in the request. |
| `isPinDefined` | BOOLEAN | Whether the card has a PIN defined. Returned only when "expand=isPinDefined" is informed in the request. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Issuing Cards

`POST /v2/issuing-card`

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

**Request**

```python
import starkinfra

cards = starkinfra.issuingcard.create([
    starkinfra.IssuingCard(
        holder_name="Tony Stark",
        holder_tax_id="012.345.678-90",
        holder_external_id="my-holder-id-1234",
        product_id="654321",
        type="virtual",
        display_name="TONY STARK",
        tags=["department: tech", "team: backend"]
    )
])

for card in cards:
    print(card)
```

**Response**

```python
IssuingCard(
    id=5715709195239424,
    holder_id=5155165527080960,
    holder_name=Tony Stark,
    holder_tax_id=012.345.678-90,
    holder_external_id=my-holder-id-1234,
    display_name=TONY STARK,
    product_id=654321,
    type=virtual,
    status=active,
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=10 andar,
    district=Itaim Bibi,
    city=Sao Paulo,
    state_code=SP,
    zip_code=01311-000,
    tags=['department: tech', 'team: backend'],
    number=**** **** **** 1234,
    security_code=***,
    expiration=****-**-**T**:**:**.******+00:00,
    is_pin_defined=False,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Cards

`GET /v2/issuing-card`

Get a list of issuing cards in chunks of at most 100.

**Request**

```python
import starkinfra

cards = starkinfra.issuingcard.query(
    limit=10,
    status="active"
)

for card in cards:
    print(card)
```

**Response**

```python
IssuingCard(
    id=5715709195239424,
    holder_id=5155165527080960,
    holder_name=Tony Stark,
    holder_tax_id=012.345.678-90,
    holder_external_id=my-holder-id-1234,
    display_name=TONY STARK,
    product_id=654321,
    type=virtual,
    status=active,
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=10 andar,
    district=Itaim Bibi,
    city=Sao Paulo,
    state_code=SP,
    zip_code=01311-000,
    tags=['department: tech', 'team: backend'],
    number=**** **** **** 1234,
    security_code=***,
    expiration=****-**-**T**:**:**.******+00:00,
    is_pin_defined=False,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Card

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

Get a single issuing card by its id.

**Request**

```python
import starkinfra

card = starkinfra.issuingcard.get("5715709195239424")

print(card)
```

**Response**

```python
IssuingCard(
    id=5715709195239424,
    holder_id=5155165527080960,
    holder_name=Tony Stark,
    holder_tax_id=012.345.678-90,
    holder_external_id=my-holder-id-1234,
    display_name=TONY STARK,
    product_id=654321,
    type=virtual,
    status=active,
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=10 andar,
    district=Itaim Bibi,
    city=Sao Paulo,
    state_code=SP,
    zip_code=01311-000,
    tags=['department: tech', 'team: backend'],
    number=**** **** **** 1234,
    security_code=***,
    expiration=****-**-**T**:**:**.******+00:00,
    is_pin_defined=False,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Update an Issuing Card

`PATCH /v2/issuing-card/:id`

Update the properties of an existing issuing card.

**Request**

```python
import starkinfra

card = starkinfra.issuingcard.update(
    "5715709195239424",
    status="blocked",
    pin="1234",
    tags=["blocked-reason: fraud"]
)

print(card)
```

**Response**

```python
IssuingCard(
    id=5715709195239424,
    holder_id=5155165527080960,
    holder_name=Tony Stark,
    holder_tax_id=012.345.678-90,
    holder_external_id=my-holder-id-1234,
    display_name=TONY STARK,
    product_id=654321,
    type=virtual,
    status=blocked,
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=10 andar,
    district=Itaim Bibi,
    city=Sao Paulo,
    state_code=SP,
    zip_code=01311-000,
    tags=['blocked-reason: fraud'],
    number=**** **** **** 1234,
    security_code=***,
    expiration=****-**-**T**:**:**.******+00:00,
    is_pin_defined=False,
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### Cancel an Issuing Card

`DELETE /v2/issuing-card/:id`

Cancel an issuing card. This action is irreversible.

**Request**

```python
import starkinfra

card = starkinfra.issuingcard.cancel("5715709195239424")

print(card)
```

**Response**

```python
IssuingCard(
    id=5715709195239424,
    holder_id=5155165527080960,
    holder_name=Tony Stark,
    holder_tax_id=012.345.678-90,
    holder_external_id=my-holder-id-1234,
    display_name=TONY STARK,
    product_id=654321,
    type=virtual,
    status=canceled,
    rules=[
        IssuingRule(
            id=5155165527080960,
            name=General BRL,
            amount=100000,
            interval=day,
            currency_code=BRL,
            schedule=,
            purposes=[],
            categories=[],
            countries=[],
            methods=[],
            merchants=[]
        )
    ],
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=10 andar,
    district=Itaim Bibi,
    city=Sao Paulo,
    state_code=SP,
    zip_code=01311-000,
    tags=['department: tech', 'team: backend'],
    number=**** **** **** 1234,
    security_code=***,
    expiration=****-**-**T**:**:**.******+00:00,
    is_pin_defined=False,
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### List Issuing Card Logs

`GET /v2/issuing-card/log`

Get a paged list of issuing card logs.

**Request**

```python
import starkinfra

logs = starkinfra.issuingcard.log.query(
    limit=10,
    types=["blocked"]
)

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

**Response**

```python
Log(
    id=6724771005489152,
    type=blocked,
    card=IssuingCard(id=5715709195239424, status=blocked),
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Card Log

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

Get a single issuing card log by its id.

**Request**

```python
import starkinfra

log = starkinfra.issuingcard.log.get("6724771005489152")

print(log)
```

**Response**

```python
Log(
    id=6724771005489152,
    type=blocked,
    card=IssuingCard(id=5715709195239424, status=blocked),
    created=2022-01-01 00:00:00
)
```

## Issuing Design

The Issuing Design resource represents the visual design of a physical card.

Designs define the artwork, fonts, and layout used when embossing and printing cards.

You can retrieve available designs and download their PDF templates.

### The Issuing Design object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing design. |
| `name` | STRING | Name of the design. |
| `type` | STRING | Design type. Options: "card", "envelope". |
| `embosserIds` | LIST OF STRINGS | List of embosser ids that support this design. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Issuing Designs

`GET /v2/issuing-design`

Get a list of available issuing designs for your workspace.

**Request**

```python
import starkinfra

designs = starkinfra.issuingdesign.query(limit=10)

for design in designs:
    print(design)
```

**Response**

```python
IssuingDesign(
    id=5715709195239424,
    name=Standard Blue,
    embosser_ids=['6724771005489152'],
    type=card,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Design

`GET /v2/issuing-design/:id`

Get a single issuing design by its id.

**Request**

```python
import starkinfra

design = starkinfra.issuingdesign.get("5715709195239424")

print(design)
```

**Response**

```python
IssuingDesign(
    id=5715709195239424,
    name=Standard Blue,
    embosser_ids=['6724771005489152'],
    type=card,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Design PDF

`GET /v2/issuing-design/:id/pdf`

Get the PDF file for a specific issuing design. This file can be used to preview the card layout.

**Request**

```python
import starkinfra

pdf = starkinfra.issuingdesign.pdf("5715709195239424")

with open("design.pdf", "wb") as f:
    f.write(pdf)
```

**Response**

```python
b'%PDF-1.4 ...' # Binary PDF content
```

## Issuing Embossing Kit

The Issuing Embossing Kit resource represents a kit used for embossing physical cards.

Each kit defines the card design and packaging used during the card personalization process.

### The Issuing Embossing Kit object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing embossing kit. |
| `name` | STRING | Name of the embossing kit. |
| `designs` | LIST OF OBJECTS | List of objects referencing the designs that compose the kit. Each object contains the design id. Example: [{"id": "6284441486065664"}]. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Issuing Embossing Kits

`GET /v2/issuing-embossing-kit`

Get a list of available issuing embossing kits for your workspace.

**Request**

```python
import starkinfra

kits = starkinfra.issuingembossingkit.query(limit=10)

for kit in kits:
    print(kit)
```

**Response**

```python
IssuingEmbossingKit(
    id=5715709195239424,
    name=Standard Kit,
    designs=[
        IssuingDesign(
            id=6284441486065664,
            name=None,
            embosser_ids=None,
            type=None,
            created=None,
            updated=None
        ),
        IssuingDesign(
            id=6284441486065665,
            name=None,
            embosser_ids=None,
            type=None,
            created=None,
            updated=None
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Embossing Kit

`GET /v2/issuing-embossing-kit/:id`

Get a single issuing embossing kit by its id.

**Request**

```python
import starkinfra

kit = starkinfra.issuingembossingkit.get("5715709195239424")

print(kit)
```

**Response**

```python
IssuingEmbossingKit(
    id=5715709195239424,
    name=Standard Kit,
    designs=[
        IssuingDesign(
            id=6284441486065664,
            name=None,
            embosser_ids=None,
            type=None,
            created=None,
            updated=None
        ),
        IssuingDesign(
            id=6284441486065665,
            name=None,
            embosser_ids=None,
            type=None,
            created=None,
            updated=None
        )
    ],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

## Issuing Stock

The Issuing Stock resource tracks the inventory of physical card blanks available for embossing.

Each stock entry is associated with a specific card design and holder type.

Monitor your stock levels to ensure cards are available when needed.

### The Issuing Stock object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing stock. |
| `designId` | STRING | Id of the IssuingDesign of the card blanks in stock. |
| `embosserId` | STRING | Id of the embosser that holds this stock. |
| `embosserName` | STRING | Name of the embosser that holds this stock. |
| `balance` | INTEGER | Number of card blanks currently available in stock. Returned when "expand=balance" is informed in the request. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Issuing Stocks

`GET /v2/issuing-stock`

Get a list of issuing stocks in chunks of at most 100.

**Request**

```python
import starkinfra

stocks = starkinfra.issuingstock.query(limit=10)

for stock in stocks:
    print(stock)
```

**Response**

```python
IssuingStock(
    id=5715709195239424,
    design_id=6724771005489152,
    embosser_id=7834882116598271,
    embosser_name=Stark Embosser,
    balance=500,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Stock

`GET /v2/issuing-stock/:id`

Get a single issuing stock entry by its id.

**Request**

```python
import starkinfra

stock = starkinfra.issuingstock.get("5715709195239424")

print(stock)
```

**Response**

```python
IssuingStock(
    id=5715709195239424,
    design_id=6724771005489152,
    embosser_id=7834882116598271,
    embosser_name=Stark Embosser,
    balance=500,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Stock Logs

`GET /v2/issuing-stock/log`

Get a paged list of issuing stock logs.

**Request**

```python
import starkinfra

logs = starkinfra.issuingstock.log.query(
    limit=10,
    types=["created"]
)

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

**Response**

```python
Log(
    id=6724771005489152,
    type=created,
    stock=IssuingStock(id=5715709195239424, balance=500),
    count=10,
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Stock Log

`GET /v2/issuing-stock/log/:id`

Get a single issuing stock log by its id.

**Request**

```python
import starkinfra

log = starkinfra.issuingstock.log.get("6724771005489152")

print(log)
```

**Response**

```python
Log(
    id=6724771005489152,
    type=created,
    stock=IssuingStock(id=5715709195239424, balance=500),
    count=10,
    created=2022-01-01 00:00:00
)
```

## Issuing Stock Rule

The Issuing Stock Rule resource lets you register low-balance alerts for your card stocks.

When the available count of an issuing stock falls below the configured minimum balance, the registered emails and phones are notified.

Each issuing stock can have only one active rule at a time.

### The Issuing Stock Rule object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing stock rule. |
| `minimumBalance` | INTEGER | Stock count threshold that triggers the alert. Example: 1000. |
| `stockId` | STRING | Id of the IssuingStock monitored by this rule. |
| `emails` | LIST OF STRINGS | List of email addresses notified when the rule is triggered. Max: 10. |
| `phones` | LIST OF STRINGS | List of phone numbers notified when the rule is triggered. Max: 10. |
| `tags` | LIST OF STRINGS | Array of strings to tag the entity for future queries. |
| `status` | STRING | Current rule status. Options: "active", "canceled". |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Issuing Stock Rules

`POST /v2/issuing-stock-rule`

Use this route to register stock rules.

Send a "rules" array where each element carries the parameters below. At least one email or phone must be informed per rule.

**Request**

```python
import starkinfra

rules = starkinfra.issuingstockrule.create([
    starkinfra.IssuingStockRule(
        minimum_balance=1000,
        stock_id="6724771005489152",
        emails=["aria@stark.com"],
        phones=["+5511999999999"],
        tags=["stock: black-card"]
    )
])

for rule in rules:
    print(rule)
```

**Response**

```python
IssuingStockRule(
    id=5715709195239424,
    minimum_balance=1000,
    stock_id=6724771005489152,
    emails=['aria@stark.com'],
    phones=['+5511999999999'],
    tags=['stock: black-card'],
    status=active,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Stock Rules

`GET /v2/issuing-stock-rule`

Get a list of issuing stock rules in chunks of at most 100.

**Request**

```python
import starkinfra

rules = starkinfra.issuingstockrule.query(
    limit=10,
    status="active"
)

for rule in rules:
    print(rule)
```

**Response**

```python
IssuingStockRule(
    id=5715709195239424,
    minimum_balance=1000,
    stock_id=6724771005489152,
    emails=['aria@stark.com'],
    phones=['+5511999999999'],
    tags=['stock: black-card'],
    status=active,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Update an Issuing Stock Rule

`PATCH /v2/issuing-stock-rule/:id`

Update the properties of an existing issuing stock rule.

**Request**

```python
import starkinfra

rule = starkinfra.issuingstockrule.update(
    "5715709195239424",
    minimum_balance=2000,
    emails=["aria@stark.com", "tony@stark.com"]
)

print(rule)
```

**Response**

```python
IssuingStockRule(
    id=5715709195239424,
    minimum_balance=2000,
    stock_id=6724771005489152,
    emails=['aria@stark.com', 'tony@stark.com'],
    phones=['+5511999999999'],
    tags=['stock: black-card'],
    status=active,
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### Cancel an Issuing Stock Rule

`DELETE /v2/issuing-stock-rule/:id`

Cancel an issuing stock rule. This action is irreversible.

**Request**

```python
import starkinfra

rule = starkinfra.issuingstockrule.cancel("5715709195239424")

print(rule)
```

**Response**

```python
IssuingStockRule(
    id=5715709195239424,
    minimum_balance=2000,
    stock_id=6724771005489152,
    emails=['aria@stark.com', 'tony@stark.com'],
    phones=['+5511999999999'],
    tags=['stock: black-card'],
    status=canceled,
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

## Issuing Restock

The Issuing Restock resource is used to request additional card blanks when your stock is running low.

Each restock request specifies the quantity needed and the stock to replenish.

Monitor the status of your restock requests through the log endpoints.

### The Issuing Restock object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing restock. |
| `count` | INTEGER | Number of card blanks requested in this restock. |
| `stockId` | STRING | Id of the IssuingStock to be replenished. |
| `status` | STRING | Current restock status. Options: "created", "processing", "confirmed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the restock. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Issuing Restocks

`POST /v2/issuing-restock`

Use this route to create up to 100 new issuing restock requests at a time.

**Request**

```python
import starkinfra

restocks = starkinfra.issuingrestock.create([
    starkinfra.IssuingRestock(
        count=100,
        stock_id="5715709195239424"
    )
])

for restock in restocks:
    print(restock)
```

**Response**

```python
IssuingRestock(
    id=6724771005489152,
    count=100,
    stock_id=5715709195239424,
    status=created,
    tags=[],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Restocks

`GET /v2/issuing-restock`

Get a list of issuing restock requests in chunks of at most 100.

**Request**

```python
import starkinfra

restocks = starkinfra.issuingrestock.query(limit=10)

for restock in restocks:
    print(restock)
```

**Response**

```python
IssuingRestock(
    id=6724771005489152,
    count=100,
    stock_id=5715709195239424,
    status=confirmed,
    tags=[],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Restock

`GET /v2/issuing-restock/:id`

Get a single issuing restock by its id.

**Request**

```python
import starkinfra

restock = starkinfra.issuingrestock.get("6724771005489152")

print(restock)
```

**Response**

```python
IssuingRestock(
    id=6724771005489152,
    count=100,
    stock_id=5715709195239424,
    status=confirmed,
    tags=[],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Restock Logs

`GET /v2/issuing-restock/log`

Get a paged list of issuing restock logs.

**Request**

```python
import starkinfra

logs = starkinfra.issuingrestock.log.query(
    limit=10,
    types=["confirmed"]
)

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

**Response**

```python
Log(
    id=7834882116598271,
    type=confirmed,
    restock=IssuingRestock(id=6724771005489152, status=confirmed),
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Restock Log

`GET /v2/issuing-restock/log/:id`

Get a single issuing restock log by its id.

**Request**

```python
import starkinfra

log = starkinfra.issuingrestock.log.get("7834882116598271")

print(log)
```

**Response**

```python
Log(
    id=7834882116598271,
    type=confirmed,
    restock=IssuingRestock(id=6724771005489152, status=confirmed),
    created=2022-01-01 00:00:00
)
```

## Issuing Embossing Request

The Issuing Embossing Request resource is used to initiate the personalization and delivery of a physical card.

Each request specifies the card, kit, display name, and shipping address for card delivery.

Track the embossing and shipping status through the log endpoints.

### The Issuing Embossing Request object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing embossing request. |
| `cardId` | STRING | Id of the IssuingCard to be embossed. |
| `kitId` | STRING | Id of the IssuingEmbossingKit to be used. |
| `displayName1` | STRING | First line of the name to be printed on the card face. Example: "TONY STARK". |
| `displayName2` | STRING | Second line of the name to be printed on the card face. |
| `displayName3` | STRING | Third line of the name to be printed on the card face. |
| `shippingCity` | STRING | City for card delivery. |
| `shippingCountryCode` | STRING | Country code for card delivery. Example: "BRA". |
| `shippingDistrict` | STRING | District for card delivery. |
| `shippingService` | STRING | Shipping service type. Options: "loggi", "conveyor". |
| `shippingStateCode` | STRING | State code for card delivery. Example: "SP". |
| `shippingStreetLine1` | STRING | Primary street line for card delivery. |
| `shippingStreetLine2` | STRING | Secondary street line for card delivery. |
| `shippingTrackingNumber` | STRING | Tracking number for the card shipment. |
| `shippingZipCode` | STRING | ZIP code for card delivery. Example: "01311-000". |
| `embosserId` | STRING | Id of the embosser responsible for this request. |
| `shippingPhone` | STRING | Phone number for delivery contact. Example: "+5511999999999". |
| `status` | STRING | Current status of the embossing request. Options: "created", "processing", "success", "failed". |
| `tags` | LIST OF STRINGS | Tags associated with the embossing request. |
| `fee` | INTEGER | Fee charged in cents for the embossing request. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Issuing Embossing Requests

`POST /v2/issuing-embossing-request`

Use this route to create up to 100 new issuing embossing requests at a time.

**Request**

```python
import starkinfra

requests = starkinfra.issuingembossingrequest.create([
    starkinfra.IssuingEmbossingRequest(
        card_id="5715709195239424",
        kit_id="6724771005489152",
        display_name_1="TONY STARK",
        shipping_city="Sao Paulo",
        shipping_country_code="BRA",
        shipping_district="Bela Vista",
        shipping_service="loggi",
        shipping_state_code="SP",
        shipping_street_line_1="Av. Paulista, 1000",
        shipping_street_line_2="Apto 101",
        shipping_tracking_number="BR1234567890",
        shipping_zip_code="01311-000",
        embosser_id="5656565656565656",
        tags=["department: tech"]
    )
])

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

**Response**

```python
IssuingEmbossingRequest(
    id=7834882116598271,
    card_id=5715709195239424,
    kit_id=6724771005489152,
    display_name_1=TONY STARK,
    display_name_2=None,
    display_name_3=None,
    shipping_city=Sao Paulo,
    shipping_country_code=BRA,
    shipping_district=Bela Vista,
    shipping_phone=+5511999999999,
    shipping_service=loggi,
    shipping_state_code=SP,
    shipping_street_line_1=Av. Paulista, 1000,
    shipping_street_line_2=Apto 101,
    shipping_tracking_number=BR1234567890,
    shipping_zip_code=01311-000,
    embosser_id=5656565656565656,
    fee=0,
    status=created,
    tags=['department: tech'],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Embossing Requests

`GET /v2/issuing-embossing-request`

Get a list of issuing embossing requests in chunks of at most 100.

**Request**

```python
import starkinfra

requests = starkinfra.issuingembossingrequest.query(
    limit=10,
    status="created"
)

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

**Response**

```python
IssuingEmbossingRequest(
    id=7834882116598271,
    card_id=5715709195239424,
    kit_id=6724771005489152,
    display_name_1=TONY STARK,
    display_name_2=None,
    display_name_3=None,
    shipping_city=Sao Paulo,
    shipping_country_code=BRA,
    shipping_district=Bela Vista,
    shipping_phone=+5511999999999,
    shipping_service=loggi,
    shipping_state_code=SP,
    shipping_street_line_1=Av. Paulista, 1000,
    shipping_street_line_2=Apto 101,
    shipping_tracking_number=BR1234567890,
    shipping_zip_code=01311-000,
    embosser_id=5656565656565656,
    fee=0,
    status=created,
    tags=['department: tech'],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Embossing Request

`GET /v2/issuing-embossing-request/:id`

Get a single issuing embossing request by its id.

**Request**

```python
import starkinfra

request = starkinfra.issuingembossingrequest.get("7834882116598271")

print(request)
```

**Response**

```python
IssuingEmbossingRequest(
    id=7834882116598271,
    card_id=5715709195239424,
    kit_id=6724771005489152,
    display_name_1=TONY STARK,
    display_name_2=None,
    display_name_3=None,
    shipping_city=Sao Paulo,
    shipping_country_code=BRA,
    shipping_district=Bela Vista,
    shipping_phone=+5511999999999,
    shipping_service=loggi,
    shipping_state_code=SP,
    shipping_street_line_1=Av. Paulista, 1000,
    shipping_street_line_2=Apto 101,
    shipping_tracking_number=BR1234567890,
    shipping_zip_code=01311-000,
    embosser_id=5656565656565656,
    fee=0,
    status=created,
    tags=['department: tech'],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Embossing Request Logs

`GET /v2/issuing-embossing-request/log`

Get a paged list of issuing embossing request logs.

**Request**

```python
import starkinfra

logs = starkinfra.issuingembossingrequest.log.query(
    limit=10,
    types=["sent"]
)

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

**Response**

```python
Log(
    id=8945993227707382,
    type=sent,
    request=IssuingEmbossingRequest(id=7834882116598271, status=processing),
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Embossing Request Log

`GET /v2/issuing-embossing-request/log/:id`

Get a single issuing embossing request log by its id.

**Request**

```python
import starkinfra

log = starkinfra.issuingembossingrequest.log.get("8945993227707382")

print(log)
```

**Response**

```python
Log(
    id=8945993227707382,
    type=sent,
    request=IssuingEmbossingRequest(id=7834882116598271, status=processing),
    created=2022-01-01 00:00:00
)
```

## Issuing Token

The Issuing Token resource represents a tokenized version of a card stored in a digital wallet.

Tokens allow cardholders to make purchases using digital wallets without exposing the actual card number.

You can manage token status and monitor token activity through the log endpoints.

### The Issuing Token object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing token. |
| `cardId` | STRING | Id of the IssuingCard this token is associated with. |
| `walletId` | STRING | Id of the digital wallet where the token is stored. |
| `walletName` | STRING | Name of the digital wallet. Example: "Apple Pay", "Google Pay". |
| `merchantId` | STRING | Id of the merchant if the token is merchant-specific. |
| `externalId` | STRING | Unique external identifier of the token. |
| `walletDeviceScore` | FLOAT | Device score informed by the digital wallet. |
| `walletAccountScore` | FLOAT | Account score informed by the digital wallet. |
| `status` | STRING | Current token status. Options: "active", "blocked", "canceled", "frozen", "pending", "denied". |
| `tags` | LIST OF STRINGS | Tags associated with the token. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Issuing Tokens

`GET /v2/issuing-token`

Get a list of issuing tokens in chunks of at most 100.

**Request**

```python
import starkinfra

tokens = starkinfra.issuingtoken.query(
    limit=10,
    status="active"
)

for token in tokens:
    print(token)
```

**Response**

```python
IssuingToken(
    id=5715709195239424,
    card_id=6724771005489152,
    wallet_id=apple,
    wallet_name=Apple Pay,
    merchant_id=5656565656565656,
    external_id=DNITHE301234567890123456789012345678,
    wallet_device_score=None,
    wallet_account_score=None,
    status=active,
    tags=['department: tech'],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Token

`GET /v2/issuing-token/:id`

Get a single issuing token by its id.

**Request**

```python
import starkinfra

token = starkinfra.issuingtoken.get("5715709195239424")

print(token)
```

**Response**

```python
IssuingToken(
    id=5715709195239424,
    card_id=6724771005489152,
    wallet_id=apple,
    wallet_name=Apple Pay,
    merchant_id=5656565656565656,
    external_id=DNITHE301234567890123456789012345678,
    wallet_device_score=None,
    wallet_account_score=None,
    status=active,
    tags=['department: tech'],
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Update an Issuing Token

`PATCH /v2/issuing-token/:id`

Update the status or tags of an existing issuing token.

**Request**

```python
import starkinfra

token = starkinfra.issuingtoken.update(
    "5715709195239424",
    status="blocked",
    tags=["blocked-reason: lost"]
)

print(token)
```

**Response**

```python
IssuingToken(
    id=5715709195239424,
    card_id=6724771005489152,
    wallet_id=apple,
    wallet_name=Apple Pay,
    merchant_id=5656565656565656,
    external_id=DNITHE301234567890123456789012345678,
    wallet_device_score=None,
    wallet_account_score=None,
    status=blocked,
    tags=['department: tech'],
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### Cancel an Issuing Token

`DELETE /v2/issuing-token/:id`

Cancel an issuing token. This action is irreversible.

**Request**

```python
import starkinfra

token = starkinfra.issuingtoken.cancel("5715709195239424")

print(token)
```

**Response**

```python
IssuingToken(
    id=5715709195239424,
    card_id=6724771005489152,
    wallet_id=apple,
    wallet_name=Apple Pay,
    merchant_id=5656565656565656,
    external_id=DNITHE301234567890123456789012345678,
    wallet_device_score=None,
    wallet_account_score=None,
    status=canceled,
    tags=['department: tech'],
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### List Issuing Token Logs

`GET /v2/issuing-token/log`

Get a paged list of issuing token logs.

**Request**

```python
import starkinfra

logs = starkinfra.issuingtoken.log.query(
    limit=10,
    types=["created"]
)

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

**Response**

```python
Log(
    id=6724771005489152,
    type=created,
    errors=[],
    token=IssuingToken(id=5715709195239424, status=active),
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Token Log

`GET /v2/issuing-token/log/:id`

Get a single issuing token log by its id.

**Request**

```python
import starkinfra

log = starkinfra.issuingtoken.log.get("6724771005489152")

print(log)
```

**Response**

```python
Log(
    id=6724771005489152,
    type=created,
    errors=[],
    token=IssuingToken(id=5715709195239424, status=active),
    created=2022-01-01 00:00:00
)
```

## Issuing Token Request

The Issuing Token Request resource is used to initiate the tokenization of a card for digital wallets.

When a cardholder attempts to add a card to a digital wallet (e.g., Apple Pay, Google Pay), a token request is generated.

Process the token request to approve or decline the card tokenization.

### The Issuing Token Request object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `cardId` | STRING | Id of the IssuingCard to be tokenized. |
| `walletId` | STRING | Id of the digital wallet requesting tokenization. Options: "apple", "google", "merchant". |
| `methodCode` | STRING | Provisioning method. Options: "app", "manual". |
| `content` | STRING | Processed content of the tokenization request. |
| `signature` | STRING | Digital signature of the content. |
| `metadata` | OBJECT | Additional data passed along with the tokenization request. |

### Create an Issuing Token Request

`POST /v2/issuing-token-request`

Use this route to process a tokenization request from a digital wallet provider.

**Request**

```python
import starkinfra

token_request = starkinfra.issuingtokenrequest.create(
    starkinfra.IssuingTokenRequest(
        card_id="5715709195239424",
        wallet_id="apple",
        method_code="app"
    )
)

print(token_request)
```

**Response**

```python
IssuingTokenRequest(
    card_id=5715709195239424,
    wallet_id=apple,
    method_code=app,
    content=eyJhcHBsaWNhdGlvbklkIjoiY29tLmFwcGxl...,
    signature=MEUCIQDp3GTGqsqDeKLN9aLhxAZ...,
    metadata={}
)
```

## Issuing Token Design

The Issuing Token Design resource represents the visual design used to display a tokenized card in a digital wallet.

Designs include the card artwork shown in the wallet app.

You can retrieve available token designs and download their PDF files.

### The Issuing Token Design object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing token design. |
| `name` | STRING | Name of the token design. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Issuing Token Designs

`GET /v2/issuing-token-design`

Get a list of available issuing token designs for your workspace.

**Request**

```python
import starkinfra

designs = starkinfra.issuingtokendesign.query(limit=10)

for design in designs:
    print(design)
```

**Response**

```python
IssuingTokenDesign(
    id=5715709195239424,
    name=Apple Pay Card Art,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Token Design

`GET /v2/issuing-token-design/:id`

Get a single issuing token design by its id.

**Request**

```python
import starkinfra

design = starkinfra.issuingtokendesign.get("5715709195239424")

print(design)
```

**Response**

```python
IssuingTokenDesign(
    id=5715709195239424,
    name=Apple Pay Card Art,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Token Design PDF

`GET /v2/issuing-token-design/:id/pdf`

Get the PDF file for a specific issuing token design. This file is used to represent the card in digital wallets.

**Request**

```python
import starkinfra

pdf = starkinfra.issuingtokendesign.pdf("5715709195239424")

with open("token-design.pdf", "wb") as f:
    f.write(pdf)
```

**Response**

```python
b'%PDF-1.4 ...' # Binary PDF content
```

## Issuing Invoice

The Issuing Invoice resource is used to add funds to your issuing balance.

Generate a Pix invoice (brcode) to receive deposits directly into your issuing wallet.

Once paid, the funds become available in your issuing balance for card spending.

### The Issuing Invoice object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing invoice. |
| `amount` | INTEGER | Invoice amount in cents. Example: 10000 (R$100.00). |
| `taxId` | STRING | Payer CPF (11 digits) or CNPJ (14 digits). |
| `name` | STRING | Payer full name. |
| `tags` | LIST OF STRINGS | Tags associated with the invoice. |
| `metadata` | OBJECT | Free-form map you can attach to the invoice. |
| `status` | STRING | Current invoice status. Options: "created", "expired", "paid". |
| `brcode` | STRING | Pix brcode string for payment. |
| `due` | STRING | Invoice due datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `link` | STRING | Public URL to the invoice payment page. |
| `issuingTransactionId` | STRING | Id of the IssuingTransaction created when the invoice is paid. Null until payment. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create an Issuing Invoice

`POST /v2/issuing-invoice`

Use this route to create a new issuing invoice to fund your issuing balance.

**Request**

```python
import starkinfra

invoice = starkinfra.issuinginvoice.create(
    starkinfra.IssuingInvoice(
        amount=10000,
        tax_id="012.345.678-90",
        name="Tony Stark",
        tags=["department: tech"]
    )
)

print(invoice)
```

**Response**

```python
IssuingInvoice(
    id=5715709195239424,
    amount=10000,
    tax_id=012.345.678-90,
    name=Tony Stark,
    tags=['department: tech'],
    metadata={},
    status=created,
    brcode=00020101021226870014br.gov.bcb.pix2565...,
    due=2022-02-10 00:00:00,
    link=https://sandbox.api.starkinfra.com/invoicelink/5715709195239424,
    issuing_transaction_id=None,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Invoices

`GET /v2/issuing-invoice`

Get a list of issuing invoices in chunks of at most 100.

**Request**

```python
import starkinfra

invoices = starkinfra.issuinginvoice.query(
    limit=10,
    status="created"
)

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

**Response**

```python
IssuingInvoice(
    id=5715709195239424,
    amount=10000,
    tax_id=012.345.678-90,
    name=Tony Stark,
    tags=['department: tech'],
    metadata={},
    status=created,
    brcode=00020101021226870014br.gov.bcb.pix2565...,
    due=2022-02-10 00:00:00,
    link=https://sandbox.api.starkinfra.com/invoicelink/5715709195239424,
    issuing_transaction_id=None,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Invoice

`GET /v2/issuing-invoice/:id`

Get a single issuing invoice by its id.

**Request**

```python
import starkinfra

invoice = starkinfra.issuinginvoice.get("5715709195239424")

print(invoice)
```

**Response**

```python
IssuingInvoice(
    id=5715709195239424,
    amount=10000,
    tax_id=012.345.678-90,
    name=Tony Stark,
    tags=['department: tech'],
    metadata={},
    status=created,
    brcode=00020101021226870014br.gov.bcb.pix2565...,
    due=2022-02-10 00:00:00,
    link=https://sandbox.api.starkinfra.com/invoicelink/5715709195239424,
    issuing_transaction_id=None,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Invoice Logs

`GET /v2/issuing-invoice/log`

Get a paged list of issuing invoice logs.

**Request**

```python
import starkinfra

logs = starkinfra.issuinginvoice.log.query(
    limit=10,
    types=["paid"]
)

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

**Response**

```python
Log(
    id=6724771005489152,
    type=paid,
    invoice=IssuingInvoice(id=5715709195239424, amount=10000, status=paid),
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Invoice Log

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

Get a single issuing invoice log by its id.

**Request**

```python
import starkinfra

log = starkinfra.issuinginvoice.log.get("6724771005489152")

print(log)
```

**Response**

```python
Log(
    id=6724771005489152,
    type=paid,
    invoice=IssuingInvoice(id=5715709195239424, amount=10000, status=paid),
    created=2022-01-01 00:00:00
)
```

## Issuing Billing Invoice

The Issuing Billing Invoice resource represents the invoice that settles the postpaid usage of your issuing operation in a billing period.

Each invoice consolidates the purchases and withdrawals settled in the billing period and can be paid via its brcode or link.

Fine and interest are applied when the invoice is paid after the due date.

### The Issuing Billing Invoice object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing billing invoice. |
| `taxId` | STRING | Tax id (CPF or CNPJ) of the invoice payer. Example: "012.345.678-90". |
| `name` | STRING | Name of the invoice payer. |
| `amount` | INTEGER | Current invoice amount in cents, including fine and interest when overdue. Example: 100000 (= R$ 1,000.00). |
| `nominalAmount` | INTEGER | Original invoice amount in cents, before fine and interest. Example: 100000 (= R$ 1,000.00). |
| `fine` | FLOAT | Fine percentage applied when paid after the due date. Example: 2.0. |
| `interest` | FLOAT | Monthly interest percentage applied when paid after the due date. Example: 1.0. |
| `status` | STRING | Current invoice status. Options: "created", "pending", "overdue", "expired", "paid". |
| `brcode` | STRING | Pix BR Code that can be used to pay the invoice. |
| `link` | STRING | Link to the invoice payment page. |
| `due` | STRING | Invoice due datetime. Example: "2022-02-10T00:00:00.000000+00:00". |
| `start` | STRING | Start datetime of the billing period. Example: "2022-01-01T00:00:00.000000+00:00". |
| `end` | STRING | End datetime of the billing period. Example: "2022-01-31T23:59:59.999999+00:00". |
| `created` | STRING | Creation datetime. Example: "2022-02-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-02-01T00:00:00.000000+00:00". |

### List Issuing Billing Invoices

`GET /v2/issuing-billing-invoice`

Get a list of issuing billing invoices in chunks of at most 100.

**Request**

```python
import starkinfra
from datetime import date

billing_invoices = starkinfra.issuingbillinginvoice.query(
    after=date(2023, 1, 1),
    before=date(2024, 3, 1),
    limit=10
)

for billing_invoice in billing_invoices:
    print(billing_invoice)
```

**Response**

```python
IssuingBillingInvoice(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    fine=2.0,
    interest=1.0,
    status=pending,
    amount=100000,
    nominal_amount=100000,
    brcode=00020101021226930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/d6a916beba1c41a5bbe31d63a93553c35204000053039865802BR5925Stark Bank S.A.6009Sao Paulo62070503***6304811B,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    due=2022-02-10 00:00:00,
    start=2022-01-01 00:00:00,
    end=2022-01-31 23:59:59,
    created=2022-02-01 00:00:00,
    updated=2022-02-01 00:00:00
)
```

### Get an Issuing Billing Invoice

`GET /v2/issuing-billing-invoice/:id`

Get a single issuing billing invoice by its id.

**Request**

```python
import starkinfra

billing_invoice = starkinfra.issuingbillinginvoice.get("5715709195239424")

print(billing_invoice)
```

**Response**

```python
IssuingBillingInvoice(
    id=5715709195239424,
    name=Tony Stark,
    tax_id=012.345.678-90,
    fine=2.0,
    interest=1.0,
    status=pending,
    amount=100000,
    nominal_amount=100000,
    brcode=00020101021226930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/d6a916beba1c41a5bbe31d63a93553c35204000053039865802BR5925Stark Bank S.A.6009Sao Paulo62070503***6304811B,
    link=https://invoice-h.sandbox.starkbank.com/invoicelink/851ff545535c40ba88e24a05accb9978,
    due=2022-02-10 00:00:00,
    start=2022-01-01 00:00:00,
    end=2022-01-31 23:59:59,
    created=2022-02-01 00:00:00,
    updated=2022-02-01 00:00:00
)
```

## Issuing Billing Transaction

The Issuing Billing Transaction resource represents an entry that composes an issuing billing invoice.

Each purchase or withdrawal settled in a billing period generates billing transactions, including the installments of installment purchases.

### The Issuing Billing Transaction object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing billing transaction. |
| `installment` | INTEGER | Number of this installment. Example: 1. |
| `installmentCount` | INTEGER | Total number of installments of the source purchase. Example: 3. |
| `amount` | INTEGER | Transaction amount in cents. Example: 30000 (= R$ 300.00). |
| `balance` | INTEGER | Invoice balance in cents after this transaction. |
| `source` | STRING | Entity that originated the transaction. Example: "issuing-purchase/5155165527080960". |
| `externalId` | STRING | Unique external identifier of the transaction. |
| `description` | STRING | Transaction description, usually the merchant name. |
| `cardEnding` | STRING | Last 4 digits of the card that originated the transaction. Example: "1234". |
| `holderName` | STRING | Name of the holder of the card that originated the transaction. |
| `tax` | INTEGER | IOF amount in cents applied to the transaction. |
| `rate` | FLOAT | Conversion rate applied to international transactions. |
| `merchantAmount` | INTEGER | Amount in cents in the merchant currency. Example: 30000. |
| `merchantCurrencyCode` | STRING | Currency code of the merchant amount. Example: "BRL". |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Issuing Billing Transactions

`GET /v2/issuing-billing-transaction`

Get a list of issuing billing transactions in chunks of at most 100.

**Request**

```python
import starkinfra

transactions = starkinfra.issuingbillingtransaction.query(
    limit=10,
    invoice_id="5715709195239424"
)

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

**Response**

```python
IssuingBillingTransaction(
    id=5715709195239424,
    installment=1,
    installment_count=3,
    amount=30000,
    balance=60000,
    source=issuing-purchase/5155165527080960,
    external_id=5155165527080960-1,
    description=Stark Coffee Shop,
    card_ending=1234,
    holder_name=Tony Stark,
    tax=0,
    rate=1.0,
    merchant_amount=30000,
    merchant_currency_code=BRL,
    created=2022-01-01 00:00:00
)
```

## Issuing Purchase

The Issuing Purchase resource represents a purchase transaction made with an issuing card.

Purchases are created when a cardholder makes a payment at a merchant using an issued card.

You can list, retrieve, and update purchases, as well as monitor purchase events through the log endpoints.

### The Issuing Purchase object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing purchase. |
| `productId` | STRING | Id of the IssuingProduct of the card used in the purchase. |
| `holderName` | STRING | Name of the cardholder. |
| `cardId` | STRING | Id of the IssuingCard used for the purchase. |
| `amount` | INTEGER | Purchase amount in cents in the issuer currency. |
| `tax` | INTEGER | Tax amount in cents charged on the purchase. |
| `issuerAmount` | INTEGER | Amount in cents in the issuer currency. |
| `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. |
| `merchantCurrencyCode` | STRING | ISO 4217 currency code of the merchant. Example: "USD". |
| `merchantCurrencySymbol` | STRING | Currency symbol of the merchant. Example: "$". |
| `merchantCategoryCode` | STRING | Merchant category code (MCC) for the purchase. |
| `merchantCategoryNumber` | INTEGER | MCC number of the merchant category. Example: 5814. |
| `merchantCategoryType` | STRING | Type of the merchant category. Example: "food". |
| `merchantCountryCode` | STRING | ISO 3166 country code of the merchant. Example: "BRA". |
| `acquirerId` | STRING | Id of the payment acquirer. |
| `merchantId` | STRING | Id of the merchant. |
| `merchantName` | STRING | Name of the merchant. |
| `merchantFee` | INTEGER | Merchant fee in cents. |
| `walletId` | STRING | Id of the digital wallet used if this was a token purchase. |
| `methodCode` | STRING | Payment method code. Options: "chip", "token", "server", "manual", "magstripe", "contactless". |
| `score` | FLOAT | Fraud risk score from 0 to 1. Higher values indicate higher risk. |
| `endToEndId` | STRING | End-to-end transaction identifier. |
| `tags` | LIST OF STRINGS | Tags associated with the purchase. |
| `zipCode` | STRING | ZIP code of the merchant location. |
| `issuingTransactionIds` | LIST OF STRINGS | Ids of the IssuingTransactions linked to this purchase. |
| `purpose` | STRING | Purchase purpose. Options: "purchase", "withdrawal", "verification", "purchaseRefund", "cashbackPurchase", "paymentTransaction". |
| `installmentCount` | INTEGER | Number of installments of the purchase. Example: 1. |
| `cardEnding` | STRING | Last 4 digits of the card number used. |
| `metadata` | OBJECT | Additional data related to the purchase, such as the authorizationId. |
| `description` | STRING | Purchase description provided by the merchant. |
| `confirmed` | STRING | Confirmation datetime. Null until the purchase is confirmed. |
| `status` | STRING | Current purchase status. Options: "approved", "canceled", "denied", "confirmed", "voided". |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Issuing Purchases

`GET /v2/issuing-purchase`

Get a list of issuing purchases in chunks of at most 100.

**Request**

```python
import starkinfra

purchases = starkinfra.issuingpurchase.query(
    limit=10,
    status="approved"
)

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

**Response**

```python
IssuingPurchase(
    id=5715709195239424,
    holder_name=Tony Stark,
    product_id=654321,
    card_id=7834882116598271,
    card_ending=1234,
    purpose=purchase,
    installment_count=1,
    amount=5000,
    tax=0,
    issuer_amount=5000,
    issuer_currency_code=BRL,
    issuer_currency_symbol=R$,
    merchant_amount=5000,
    merchant_currency_code=BRL,
    merchant_currency_symbol=R$,
    merchant_category_code=fastFoodRestaurants,
    merchant_category_number=5814,
    merchant_category_type=food,
    merchant_country_code=BRA,
    acquirer_id=5656565656565656,
    merchant_id=5656565656565656,
    merchant_name=Stark Store,
    merchant_fee=0,
    wallet_id=None,
    method_code=chip,
    score=0.9775689825217906,
    end_to_end_id=79fcf95d-1dfb-40db-9fa8-679e329c58f0,
    tags=[],
    issuing_transaction_ids=['5155165527080960'],
    status=approved,
    description=,
    metadata={},
    zip_code=01311-000,
    confirmed=2022-01-01 00:00:02,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Purchase

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

Get a single issuing purchase by its id.

**Request**

```python
import starkinfra

purchase = starkinfra.issuingpurchase.get("5715709195239424")

print(purchase)
```

**Response**

```python
IssuingPurchase(
    id=5715709195239424,
    holder_name=Tony Stark,
    product_id=654321,
    card_id=7834882116598271,
    card_ending=1234,
    purpose=purchase,
    installment_count=1,
    amount=5000,
    tax=0,
    issuer_amount=5000,
    issuer_currency_code=BRL,
    issuer_currency_symbol=R$,
    merchant_amount=5000,
    merchant_currency_code=BRL,
    merchant_currency_symbol=R$,
    merchant_category_code=fastFoodRestaurants,
    merchant_category_number=5814,
    merchant_category_type=food,
    merchant_country_code=BRA,
    acquirer_id=5656565656565656,
    merchant_id=5656565656565656,
    merchant_name=Stark Store,
    merchant_fee=0,
    wallet_id=None,
    method_code=chip,
    score=0.9775689825217906,
    end_to_end_id=79fcf95d-1dfb-40db-9fa8-679e329c58f0,
    tags=[],
    issuing_transaction_ids=['5155165527080960'],
    status=approved,
    description=,
    metadata={},
    zip_code=01311-000,
    confirmed=2022-01-01 00:00:02,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Update an Issuing Purchase

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

Update the tags of an existing issuing purchase.

**Request**

```python
import starkinfra

purchase = starkinfra.issuingpurchase.update(
    "5715709195239424",
    tags=["reconciled", "month: january"]
)

print(purchase)
```

**Response**

```python
IssuingPurchase(
    id=5715709195239424,
    holder_name=Tony Stark,
    product_id=654321,
    card_id=7834882116598271,
    card_ending=1234,
    purpose=purchase,
    installment_count=1,
    amount=5000,
    tax=0,
    issuer_amount=5000,
    issuer_currency_code=BRL,
    issuer_currency_symbol=R$,
    merchant_amount=5000,
    merchant_currency_code=BRL,
    merchant_currency_symbol=R$,
    merchant_category_code=fastFoodRestaurants,
    merchant_category_number=5814,
    merchant_category_type=food,
    merchant_country_code=BRA,
    acquirer_id=5656565656565656,
    merchant_id=5656565656565656,
    merchant_name=Stark Store,
    merchant_fee=0,
    wallet_id=None,
    method_code=chip,
    score=0.9775689825217906,
    end_to_end_id=79fcf95d-1dfb-40db-9fa8-679e329c58f0,
    tags=['reconciled', 'month: january'],
    issuing_transaction_ids=['5155165527080960'],
    status=approved,
    description=,
    metadata={},
    zip_code=01311-000,
    confirmed=2022-01-01 00:00:02,
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### List Issuing Purchase Logs

`GET /v2/issuing-purchase/log`

Get a paged list of issuing purchase logs.

**Request**

```python
import starkinfra

logs = starkinfra.issuingpurchase.log.query(
    limit=10,
    types=["approved"]
)

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

**Response**

```python
Log(
    id=6724771005489152,
    type=approved,
    purchase=IssuingPurchase(id=5715709195239424, amount=5000, status=approved),
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Purchase Log

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

Get a single issuing purchase log by its id.

**Request**

```python
import starkinfra

log = starkinfra.issuingpurchase.log.get("6724771005489152")

print(log)
```

**Response**

```python
Log(
    id=6724771005489152,
    type=approved,
    purchase=IssuingPurchase(id=5715709195239424, amount=5000, status=approved),
    created=2022-01-01 00:00:00
)
```

## Issuing Preview Installment

The Issuing Preview Installment resource represents an upcoming installment of an installment purchase that has not been billed yet.

Use it to preview the amounts that will compose your future issuing billing invoices.

### The Issuing Preview Installment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing preview installment. |
| `description` | STRING | Installment description, usually the merchant name. |
| `amount` | INTEGER | Installment amount in cents. Example: 30000 (= R$ 300.00). |
| `totalAmount` | INTEGER | Total amount in cents of the source purchase. Example: 90000 (= R$ 900.00). |
| `source` | STRING | Entity that originated the installment. Example: "issuing-purchase/5155165527080960". |
| `number` | INTEGER | Number of this installment. Example: 2. |
| `count` | INTEGER | Total number of installments of the source purchase. Example: 3. |
| `due` | STRING | Datetime when the installment will be billed. Example: "2022-02-01T00:00:00.000000+00:00". |
| `tags` | LIST OF STRINGS | Array of strings to tag the entity for future queries. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Issuing Preview Installments

`GET /v2/issuing-preview-installment`

Get a list of issuing preview installments in chunks of at most 100.

**Request**

```python
import starkinfra

installments = starkinfra.issuingpreviewinstallment.query(
    limit=10,
    sort="due"
)

for installment in installments:
    print(installment)
```

**Response**

```python
IssuingPreviewInstallment(
    id=6724771005489152,
    description=Stark Coffee Shop,
    amount=30000,
    total_amount=90000,
    source=issuing-purchase/5155165527080960,
    number=2,
    count=3,
    due=2022-02-01 00:00:00,
    tags=[],
    created=2022-01-01 00:00:00
)
```

## Issuing Transaction

The Issuing Transaction resource represents a change in your issuing balance.

Each purchase, invoice payment, withdrawal, or fee generates an issuing transaction.

Use transactions to reconcile your issuing balance and understand fund movements.

### The Issuing Transaction object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing transaction. |
| `amount` | INTEGER | Transaction amount in cents. Positive for credits, negative for debits. |
| `balance` | INTEGER | Issuing balance in cents after this transaction. |
| `description` | STRING | Description of the transaction. |
| `source` | STRING | Source entity that generated this transaction. |
| `tags` | LIST OF STRINGS | Tags associated with the transaction. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### List Issuing Transactions

`GET /v2/issuing-transaction`

Get a list of issuing transactions in chunks of at most 100.

**Request**

```python
import starkinfra

transactions = starkinfra.issuingtransaction.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    tags=["tony", "stark"]
)

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

**Response**

```python
IssuingTransaction(
    id=5715709195239424,
    amount=-1500,
    balance=5000000,
    description=Issuing purchase 6724771005489152,
    source=issuingPurchase/6724771005489152,
    tags=['tony', 'stark'],
    created=2022-01-01 00:00:00
)
```

### Get an Issuing Transaction

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

Get a single issuing transaction by its id.

**Request**

```python
import starkinfra

transaction = starkinfra.issuingtransaction.get("5715709195239424")

print(transaction)
```

**Response**

```python
IssuingTransaction(
    id=5715709195239424,
    amount=-1500,
    balance=5000000,
    description=Issuing purchase 6724771005489152,
    source=issuingPurchase/6724771005489152,
    tags=['tony', 'stark'],
    created=2022-01-01 00:00:00
)
```

## Issuing Withdrawal

The Issuing Withdrawal resource is used to transfer funds from your issuing balance back to your main balance.

Use withdrawals to move excess funds from your issuing wallet to your regular Stark Infra account.

### The Issuing Withdrawal object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the issuing withdrawal. |
| `amount` | INTEGER | Amount in cents to be withdrawn. Example: 10000 (R$100.00). |
| `externalId` | STRING | Your unique identifier for this withdrawal. Must be unique per workspace to prevent duplicates. |
| `description` | STRING | Description of the withdrawal. |
| `tags` | LIST OF STRINGS | Tags associated with the withdrawal. |
| `transactionId` | STRING | Id of the bank transaction linked to this withdrawal. |
| `issuingTransactionId` | STRING | Id of the issuing transaction linked to this withdrawal. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create an Issuing Withdrawal

`POST /v2/issuing-withdrawal`

Use this route to create a new issuing withdrawal and move funds from your issuing balance.

**Request**

```python
import starkinfra

withdrawal = starkinfra.issuingwithdrawal.create(
    starkinfra.IssuingWithdrawal(
        amount=10000,
        external_id="withdrawal-2022-001",
        description="Excess funds withdrawal",
        tags=["tony", "stark"]
    )
)

print(withdrawal)
```

**Response**

```python
IssuingWithdrawal(
    id=5715709195239424,
    amount=10000,
    external_id=withdrawal-2022-001,
    description=Excess funds withdrawal,
    tags=['tony', 'stark'],
    transaction_id=6724771005489152,
    issuing_transaction_id=7834882116598271,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### List Issuing Withdrawals

`GET /v2/issuing-withdrawal`

Get a list of issuing withdrawals in chunks of at most 100.

**Request**

```python
import starkinfra

withdrawals = starkinfra.issuingwithdrawal.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    tags=["tony", "stark"]
)

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

**Response**

```python
IssuingWithdrawal(
    id=5715709195239424,
    amount=10000,
    external_id=withdrawal-2022-001,
    description=Excess funds withdrawal,
    tags=['tony', 'stark'],
    transaction_id=6724771005489152,
    issuing_transaction_id=7834882116598271,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get an Issuing Withdrawal

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

Get a single issuing withdrawal by its id.

**Request**

```python
import starkinfra

withdrawal = starkinfra.issuingwithdrawal.get("5715709195239424")

print(withdrawal)
```

**Response**

```python
IssuingWithdrawal(
    id=5715709195239424,
    amount=10000,
    external_id=withdrawal-2022-001,
    description=Excess funds withdrawal,
    tags=['tony', 'stark'],
    transaction_id=6724771005489152,
    issuing_transaction_id=7834882116598271,
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

# Lending

## Credit Note

Credit Notes represent credit operations issued to individuals or businesses as Bank Credit Bills (Cédula de Crédito Bancário - CCB). They carry all the information needed to formalize a lending operation, including signers, installment invoices and the disbursement payment details.

Once created, the credit note generates a contract that must be digitally signed by all signers. After signing, the disbursement is transferred via Pix to the borrower's account and each installment is tracked through invoices.

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

### The CreditNote object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the credit note. |
| `templateId` | STRING | ID of the credit note template used. Templates are enabled for your workspace through your credit profile. |
| `name` | STRING | Borrower full name. |
| `taxId` | STRING | Borrower CPF or CNPJ. |
| `nominalAmount` | INTEGER | Nominal amount in cents of the credit note, before taxes. Example: 100000 (R$1,000.00). |
| `rebateAmount` | INTEGER | Amount in cents discounted from the disbursed amount. Example: 100 (R$1.00). |
| `taxAmount` | INTEGER | Tax amount in cents (IOF) embedded in the operation, computed from the borrower type (individual or business) and the operation duration. |
| `amount` | INTEGER | Net amount in cents disbursed to the borrower. |
| `interest` | FLOAT | Effective interest rate of the credit operation, in % per year, computed from the disbursed amount and the invoice schedule. Example: 27.5. |
| `nominalInterest` | FLOAT | Nominal interest rate of the credit operation, in % per year, computed from the nominal amount and the invoice schedule. Example: 25.2. |
| `rules` | LIST OF OBJECTS | List of rules modifying the credit note behavior, as {"key", "value"} objects. Currently available key: "invoiceCreationMode", with values "scheduled" (default - each installment invoice is issued a few days before its due date), "instant" (all invoices are issued as soon as the note is disbursed) or "never" (invoices are not issued automatically). |
| `scheduled` | STRING | Datetime when the credit note will be disbursed after signing. Example: "2022-06-28T00:00:00.000000+00:00". |
| `expiration` | INTEGER | Time span, in seconds, counted from the scheduled datetime, for the borrower and signers to sign the contract before the credit note expires. Default: 604800 (7 days). |
| `externalId` | STRING | Unique external ID that prevents the creation of duplicate credit notes on unintended retries. |
| `tags` | LIST OF STRINGS | Tags associated with the credit note. |
| `status` | STRING | Current status of the credit note. Options: "created" (awaiting signatures), "signed" (contract signed by all signers), "processing" (disbursement in progress), "success" (disbursement settled), "failed" (disbursement failed), "canceled" and "expired" (not signed before the expiration). |
| `signers` | LIST OF OBJECTS | List of CreditSigner objects representing every person or entity that must sign the contract, as {"id", "name", "contact", "method", "signed"} objects. Signers registered in your credit profile and the SCD signature are appended automatically. |
| `invoices` | LIST OF OBJECTS | List of Invoice objects representing the installments to be paid by the borrower, with their "id", "amount", "due", "fine", "interest", "expiration", "descriptions" and "tags". |
| `payment` | OBJECT | Transfer object used to disburse the credit amount to the borrower, including its "id" and "status" once the disbursement is initiated. |
| `paymentType` | STRING | Type of the payment object. Options: "transfer". |
| `streetLine1` | STRING | Borrower main address street line. |
| `streetLine2` | STRING | Borrower complement address street line. |
| `district` | STRING | Borrower address district. |
| `city` | STRING | Borrower address city. |
| `stateCode` | STRING | Borrower address state code. Example: "SP". |
| `zipCode` | STRING | Borrower address zip code. Example: "01310-100". |
| `documentId` | STRING | Unique id of the digital signing document attached to this credit note. |
| `workspaceId` | STRING | ID of the workspace that issued the credit note. |
| `debtorWorkspaceId` | STRING | ID of the borrower's workspace, when it differs from the issuing workspace. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction ids linked to the disbursement and its chargebacks. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Credit Notes

`POST /v2/credit-note`

Create credit notes in bulk. You can create up to 100 credit notes in a single request.

Provide either the nominalAmount (pre-tax) or the amount (net disbursed value) - the other one, along with the taxAmount (IOF) and the interest rates, is computed from the invoice schedule.

**Request**

```python
import starkinfra

notes = starkinfra.creditnote.create([
    starkinfra.CreditNote(
        template_id="5745297609744384",
        name="Jamie Lannister",
        tax_id="012.345.678-90",
        nominal_amount=100000,
        scheduled="2022-06-28",
        invoices=[
            starkinfra.creditnote.Invoice(
                amount=102612,
                due="2022-07-28"
            )
        ],
        payment=starkinfra.creditnote.Transfer(
            bank_code="20018183",
            branch_code="1234",
            account_number="129340-1",
            name="Jamie Lannister",
            tax_id="012.345.678-90"
        ),
        payment_type="transfer",
        signers=[
            starkinfra.creditsigner.CreditSigner(
                name="Jamie Lannister",
                contact="jamie.lannister@gmail.com",
                method="link"
            )
        ],
        external_id="my-internal-id-123456",
        street_line_1="Av. Paulista, 200",
        street_line_2="Apto. 51",
        district="Bela Vista",
        city="Sao Paulo",
        state_code="SP",
        zip_code="01310-100"
    )
])

for note in notes:
    print(note)
```

**Response**

```python
CreditNote(
    id=5745297609744385,
    template_id=5745297609744384,
    name=Jamie Lannister,
    tax_id=012.345.678-90,
    nominal_amount=100000,
    tax_amount=626,
    amount=99374,
    interest=38.61,
    nominal_interest=30.69,
    status=created,
    external_id=my-internal-id-123456,
    scheduled=2022-06-28T00:00:00.000000+00:00,
    expiration=604800,
    payment_type=transfer,
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-01T00:00:00.000000+00:00
)
```

### List Credit Notes

`GET /v2/credit-note`

List and filter all credit notes created in your workspace. Results are returned paged.

**Request**

```python
import starkinfra

notes = starkinfra.creditnote.query(
    limit=10,
    status="signed",
    after="2022-06-01",
    before="2022-06-30"
)

for note in notes:
    print(note)
```

**Response**

```python
CreditNote(
    id=5745297609744385,
    template_id=5745297609744384,
    name=Jamie Lannister,
    tax_id=012.345.678-90,
    nominal_amount=100000,
    tax_amount=626,
    amount=99374,
    interest=38.61,
    nominal_interest=30.69,
    status=signed,
    external_id=my-internal-id-123456,
    scheduled=2022-06-28T00:00:00.000000+00:00,
    expiration=604800,
    payment_type=transfer,
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-02T00:00:00.000000+00:00
)
```

### Get a Credit Note

`GET /v2/credit-note/:id`

Get a single credit note by its id.

**Request**

```python
import starkinfra

note = starkinfra.creditnote.get("5745297609744385")

print(note)
```

**Response**

```python
CreditNote(
    id=5745297609744385,
    template_id=5745297609744384,
    name=Jamie Lannister,
    tax_id=012.345.678-90,
    nominal_amount=100000,
    tax_amount=626,
    amount=99374,
    interest=38.61,
    nominal_interest=30.69,
    status=signed,
    signers=[{id: 6306107546853376, name: Jamie Lannister, method: link, contact: jamie.lannister@gmail.com, signed: 2022-06-02T00:00:00.000000+00:00}],
    document_id=07d05b14-9d83-4439-9622-d2b313b05a10,
    external_id=my-internal-id-123456,
    scheduled=2022-06-28T00:00:00.000000+00:00,
    expiration=604800,
    payment_type=transfer,
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-02T00:00:00.000000+00:00
)
```

### Cancel a Credit Note

`DELETE /v2/credit-note/:id`

Cancel a credit note that has not reached a final status yet. Credit notes with status "created", "signed" or "processing" can be canceled, which also cancels the signing document. Credit notes with status "success", "failed", "expired" or already "canceled" are returned unchanged.

**Request**

```python
import starkinfra

note = starkinfra.creditnote.cancel("5745297609744385")

print(note)
```

**Response**

```python
CreditNote(
    id=5745297609744385,
    template_id=5745297609744384,
    name=Jamie Lannister,
    tax_id=012.345.678-90,
    nominal_amount=100000,
    status=canceled,
    external_id=my-internal-id-123456,
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-03T00:00:00.000000+00:00
)
```

### Get a Credit Note PDF

`GET /v2/credit-note/:id/pdf`

Get the CCB contract PDF file of a credit note. After all signers have signed, the returned file carries the digital signatures.

**Request**

```python
import starkinfra

pdf = starkinfra.creditnote.pdf("5745297609744385")

with open("credit-note.pdf", "wb") as file:
    file.write(pdf)
```

**Response**

```python
(binary PDF file content)
```

### Get a Credit Note Payment PDF

`GET /v2/credit-note/:id/payment/pdf`

Get the disbursement transfer receipt PDF file of a credit note. Only available for credit notes with status "success".

**Request**

```python
import starkinfra

pdf = starkinfra.request.get(
    path="/credit-note/5745297609744385/payment/pdf"
).content

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

**Response**

```python
(binary PDF file content)
```

### List Credit Note Logs

`GET /v2/credit-note/log`

Get a paged list of all credit note logs. A log tracks a change in the credit note entity according to its life cycle, as {"id", "type", "errors", "note", "created"} objects.

**Request**

```python
import starkinfra

logs = starkinfra.creditnote.log.query(
    limit=10,
    note_ids=["5745297609744385"],
    types=["signed"]
)

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

**Response**

```python
Log(
    id=6532638269505536,
    type=signed,
    errors=[],
    note=CreditNote(
        id=5745297609744385,
        name=Jamie Lannister,
        status=signed
    ),
    created=2022-06-02T00:00:00.000000+00:00
)
```

### Get a Credit Note Log

`GET /v2/credit-note/log/:id`

Get a single credit note log by its id.

**Request**

```python
import starkinfra

log = starkinfra.creditnote.log.get("6532638269505536")

print(log)
```

**Response**

```python
Log(
    id=6532638269505536,
    type=signed,
    errors=[],
    note=CreditNote(
        id=5745297609744385,
        name=Jamie Lannister,
        status=signed
    ),
    created=2022-06-02T00:00:00.000000+00:00
)
```

## Credit Signer

Credit Signers represent every person or entity that must sign the CCB contract of a Credit Note.

Signers are created together with the Credit Note, through its "signers" parameter, and are returned embedded in the CreditNote object. Signers registered in your credit profile and the SCD signature are appended automatically.

When the method is "link" or "token", the signer receives the signing link or token on the registered contact (email or phone). If a signer misses it, you can trigger a new delivery.

### The CreditSigner object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the credit signer. |
| `name` | STRING | Signer full name. |
| `contact` | STRING | Signer contact that receives the signing link or token. Can be an email, a phone number or, for the "server" and "organization" methods, a URL. |
| `method` | STRING | Signing method. Options: "link" (signing link sent to the contact), "token" (signing token sent to the contact), "server" and "organization" (automatic signatures over URL contacts). |
| `signed` | STRING | Datetime when the signer signed the contract. Empty until the signature happens. Example: "2022-06-02T00:00:00.000000+00:00". |

### Update a Credit Signer

`PATCH /v2/credit-signer/:id`

Update the delivery state of a credit signer's signing token or link. Setting "isSent" to false marks it as not delivered, causing it to be sent again to the signer's contact. Use it when a signer misses the original email or SMS.

**Request**

```python
import starkinfra

signer = starkinfra.creditsigner.resend_token("6306107546853376")

print(signer)
```

**Response**

```python
CreditSigner(
    id=6306107546853376,
    name=Jamie Lannister,
    contact=jamie.lannister@gmail.com,
    method=link,
    signed=
)
```

## Credit Preview

CreditPreviews are used to preview a credit operation before creating it.

You can simulate the installment schedule, the IOF tax amount, the disbursed amount and the effective interest rates of a Credit Note without persisting anything. Previews are computed on the fly and are not saved.

### The CreditPreview object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `type` | STRING | Type of the credit preview. Options: "credit-note". |
| `credit` | OBJECT | CreditNotePreview object with the simulation parameters and, in the response, the computed results. Its "type" defines the amortization schedule: "sac" (constant amortization), "price" (fixed installments), "american" (periodic interest and principal at maturity), "bullet" (principal and interest at maturity) or "custom" (you provide the invoices and the rates are computed). Input fields: "taxId", "scheduled" (disbursement datetime), "nominalInterest" (% per year), "initialDue" (first installment due datetime), "count" (number of installments), "initialAmount" (installment amount in cents), "interval" ("day", "week", "month", "quarter", "semester" or "year" - default "month"), "nominalAmount" or "amount" (in cents), "rebateAmount" and, for the "custom" type, "invoices" as {"amount", "due"} objects. Computed fields returned: "amount" (net disbursed amount), "taxAmount" (IOF), "interest" (effective rate, % per year), "nominalInterest", "count", "initialDue", "initialAmount" and the full "invoices" schedule. |

### Create Credit Previews

`POST /v2/credit-preview`

Create credit previews to simulate credit notes before actually creating them. You can create up to 100 previews in a single request.

For the "sac" and "price" types, provide exactly one of "count" or "initialAmount" - the other one is computed. For all types except "custom", provide exactly one of "nominalAmount" or "amount".

**Request**

```python
import starkinfra

previews = starkinfra.creditpreview.create([
    starkinfra.CreditPreview(
        type="credit-note",
        credit=starkinfra.creditpreview.CreditNotePreview(
            type="sac",
            nominal_amount=100000,
            nominal_interest=15.0,
            scheduled="2022-06-28",
            initial_due="2022-07-28",
            count=12,
            tax_id="012.345.678-90"
        )
    )
])

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

**Response**

```python
CreditPreview(
    type=credit-note,
    credit=CreditNotePreview(
        type=sac,
        nominal_amount=100000,
        rebate_amount=0,
        tax_amount=1126,
        amount=98874,
        interest=17.34,
        nominal_interest=15.0,
        scheduled=2022-06-28T00:00:00.000000+00:00,
        initial_due=2022-07-28T00:00:00.000000+00:00,
        initial_amount=9583,
        count=12,
        invoices=[Invoice(amount=9583, due=2022-07-28), ..., Invoice(amount=8438, due=2023-06-28)]
    )
)
```

## Credit Holmes

CreditHolmes are used to request the credit analysis of a tax ID.

The analysis retrieves credit information from official sources for a given CPF or CNPJ, helping you evaluate the creditworthiness of a borrower.

### The CreditHolmes object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the credit holmes. |
| `taxId` | STRING | CPF or CNPJ of the entity to be analyzed. |
| `competence` | STRING | Month and year of the credit analysis in YYYY-MM format. Example: "2022-06". |
| `status` | STRING | Current status of the credit analysis. Options: "created", "solved", "failed". |
| `result` | OBJECT | Credit analysis result containing financial and credit data for the tax ID. |
| `tags` | LIST OF STRINGS | Tags associated with the credit holmes. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Credit Holmes

`POST /v2/credit-holmes`

Create credit holmes requests to analyze the credit profile of a tax ID.

You can create up to 100 requests in a single call.

**Request**

```python
import starkinfra

holmes = starkinfra.creditholmes.create([
    starkinfra.CreditHolmes(
        tax_id="012.345.678-90",
        competence="2022-06",
        tags=["credit-analysis"]
    )
])

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

**Response**

```python
CreditHolmes(
    id=5719405850615809,
    tax_id=012.345.678-90,
    competence=2022-06,
    status=created,
    result=None,
    tags=['credit-analysis'],
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-01T00:00:00.000000+00:00
)
```

### List Credit Holmes

`GET /v2/credit-holmes`

List and filter all credit holmes requests in your workspace. Results are returned paged.

**Request**

```python
import starkinfra

holmes = starkinfra.creditholmes.query(limit=10)

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

**Response**

```python
CreditHolmes(
    id=5719405850615809,
    tax_id=012.345.678-90,
    competence=2022-06,
    status=solved,
    result={...},
    tags=['credit-analysis'],
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-01T00:00:00.000000+00:00
)
```

### Get a Credit Holmes

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

Get a single credit holmes by its id.

**Request**

```python
import starkinfra

sherlock = starkinfra.creditholmes.get("5719405850615809")

print(sherlock)
```

**Response**

```python
CreditHolmes(
    id=5719405850615809,
    tax_id=012.345.678-90,
    competence=2022-06,
    status=solved,
    result={...},
    tags=['credit-analysis'],
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-01T00:00:00.000000+00:00
)
```

### List Credit Holmes Logs

`GET /v2/credit-holmes/log`

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

**Request**

```python
import starkinfra

logs = starkinfra.creditholmes.log.query(limit=10)

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

**Response**

```python
Log(
    id=5155165527080961,
    type=created,
    created=2022-06-01T00:00:00.000000+00:00,
    holmes=CreditHolmes(id=5719405850615809, status=created, ...)
)
```

### Get a Credit Holmes Log

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

Get a single credit holmes log by its id.

**Request**

```python
import starkinfra

log = starkinfra.creditholmes.log.get("5155165527080961")

print(log)
```

**Response**

```python
Log(
    id=5155165527080961,
    type=created,
    created=2022-06-01T00:00:00.000000+00:00,
    holmes=CreditHolmes(id=5719405850615809, status=created, ...)
)
```

# Ledger

## Ledger

The Ledger resource is used to track the balance of a given amount by inserting LedgerTransactions to it.

A Ledger can represent a bank account, a digital wallet, an inventory product, or any other entity whose balance you need to keep track of.

You can attach rules to a Ledger to limit its balance, such as a minimum or maximum balance, which are validated whenever a LedgerTransaction is created.

### The Ledger object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Ledger. |
| `externalId` | STRING | Unique external id to prevent duplicates. |
| `rules` | LIST OF OBJECTS | List of rule objects applied to the Ledger. |
| `tags` | LIST OF STRINGS | Tags associated with the Ledger. |
| `metadata` | OBJECT | Dictionary of additional information about the Ledger. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Ledgers

`POST /v2/ledger`

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

**Request**

```python
import starkinfra

ledgers = starkinfra.ledger.create([
    starkinfra.Ledger(
        external_id="my-internal-id-123456",
        rules=[
            starkinfra.ledger.Rule(
                key="minimumBalance",
                value=0
            )
        ],
        tags=["account/123", "savings"],
        metadata={"accountId": "123", "accountType": "savings"}
    )
])

for ledger in ledgers:
    print(ledger)
```

**Response**

```python
[
    Ledger(
        id=5656565656565656,
        external_id=my-internal-id-123456,
        rules=[
            Rule(
                key=minimumBalance,
                value=0
            )
        ],
        tags=['account/123', 'savings'],
        metadata={'accountId': '123', 'accountType': 'savings'},
        created=2022-01-01 00:00:00,
        updated=2022-01-01 00:00:00
    )
]
```

### List Ledgers

`GET /v2/ledger`

Get a list of ledgers in chunks of at most 100.

**Request**

```python
import starkinfra

ledgers = starkinfra.ledger.query(
    limit=10,
    tags=["savings"]
)

for ledger in ledgers:
    print(ledger)
```

**Response**

```python
Ledger(
    id=5656565656565656,
    external_id=my-internal-id-123456,
    rules=[
        Rule(
            key=minimumBalance,
            value=0
        )
    ],
    tags=['account/123', 'savings'],
    metadata={'accountId': '123', 'accountType': 'savings'},
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get a Ledger

`GET /v2/ledger/:id`

Get a single ledger by its id.

**Request**

```python
import starkinfra

ledger = starkinfra.ledger.get("5656565656565656")

print(ledger)
```

**Response**

```python
Ledger(
    id=5656565656565656,
    external_id=my-internal-id-123456,
    rules=[
        Rule(
            key=minimumBalance,
            value=0
        )
    ],
    tags=['account/123', 'savings'],
    metadata={'accountId': '123', 'accountType': 'savings'},
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Update a Ledger

`PATCH /v2/ledger/:id`

Update the rules, tags or metadata of an existing ledger.

**Request**

```python
import starkinfra

ledger = starkinfra.ledger.update(
    "5656565656565656",
    tags=["account/123", "closed"]
)

print(ledger)
```

**Response**

```python
Ledger(
    id=5656565656565656,
    external_id=my-internal-id-123456,
    rules=[
        Rule(
            key=minimumBalance,
            value=0
        )
    ],
    tags=['account/123', 'closed'],
    metadata={'accountId': '123', 'accountType': 'savings'},
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### List Ledger Logs

`GET /v2/ledger/log`

Get a paged list of ledger logs.

**Request**

```python
import starkinfra

logs = starkinfra.ledger.log.query(
    limit=10,
    ledger_id="5656565656565656"
)

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

**Response**

```python
Log(
    id=5656565656565656,
    type=created,
    ledger=Ledger(id=5656565656565656, external_id=my-internal-id-123456),
    created=2022-01-01 00:00:00
)
```

### Get a Ledger Log

`GET /v2/ledger/log/:id`

Get a single ledger log by its id.

**Request**

```python
import starkinfra

log = starkinfra.ledger.log.get("5656565656565656")

print(log)
```

**Response**

```python
Log(
    id=5656565656565656,
    type=created,
    ledger=Ledger(id=5656565656565656, external_id=my-internal-id-123456),
    created=2022-01-01 00:00:00
)
```

## Ledger Transaction

The LedgerTransaction resource is used to move balance in or out of a Ledger.

Each transaction carries an amount that is added to (or subtracted from) the Ledger balance, producing a new running balance that is returned in the response.

Transactions are validated against the rules of their Ledger, so a transaction that would push the balance beyond a configured minimum or maximum balance is rejected.

### The LedgerTransaction object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Ledger Transaction. |
| `ledgerId` | STRING | Id of the Ledger associated with this transaction. |
| `externalId` | STRING | Unique external id to prevent duplicates. |
| `source` | STRING | Source of the Ledger Transaction. Example: "bank-transfer/123". |
| `amount` | INTEGER | Amount in cents of the Ledger Transaction. Example: 100 (R$1.00). |
| `fee` | INTEGER | Fee charged in cents for this Ledger Transaction. |
| `balance` | INTEGER | Balance in cents of the Ledger after this transaction. Example: 100 (R$1.00). |
| `rules` | LIST OF OBJECTS | List of rule objects applied to the Ledger Transaction. |
| `tags` | LIST OF STRINGS | Tags associated with the Ledger Transaction. |
| `metadata` | OBJECT | Dictionary of additional information about the Ledger Transaction. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Ledger Transactions

`POST /v2/ledger-transaction`

Use this route to create up to 500 new ledger transactions at a time.

A single request may contain transactions targeting different ledgers. Each transaction is applied to its Ledger in the order it is sent and the resulting balance is returned for each one.

**Request**

```python
import starkinfra

transactions = starkinfra.ledgertransaction.create([
    starkinfra.LedgerTransaction(
        amount=11234,
        ledger_id="5656565656565656",
        external_id="my-internal-id-123456",
        source="bank-transfer/123",
        fee=100,
        created="2022-01-01T00:00:00.000000+00:00",
        tags=["transfer/123", "savings"],
        metadata={"orderId": "123", "orderType": "purchase"}
    )
])

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

**Response**

```python
[
    LedgerTransaction(
        id=5656565656565656,
        ledger_id=5656565656565656,
        external_id=my-internal-id-123456,
        source=bank-transfer/123,
        amount=11234,
        fee=100,
        balance=11134,
        tags=['transfer/123', 'savings'],
        metadata={'orderId': '123', 'orderType': 'purchase'},
        created=2022-01-01 00:00:00
    )
]
```

### List Ledger Transactions

`GET /v2/ledger-transaction`

Get a list of ledger transactions in chunks of at most 1000.

Either "ledgerId" or "ids" must be provided. If both are sent, results are filtered by both. When filtering by "ids", the informed ids may reference transactions across different ledgers.

**Request**

```python
import starkinfra

transactions = starkinfra.ledgertransaction.query(
    ledger_id="5656565656565656",
    limit=10
)

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

**Response**

```python
LedgerTransaction(
    id=5656565656565656,
    ledger_id=5656565656565656,
    external_id=my-internal-id-123456,
    source=bank-transfer/123,
    amount=11234,
    fee=100,
    balance=11134,
    tags=['transfer/123', 'savings'],
    metadata={'orderId': '123', 'orderType': 'purchase'},
    created=2022-01-01 00:00:00
)
```

### Get a Ledger Transaction

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

Get a single ledger transaction by its id.

**Request**

```python
import starkinfra

transaction = starkinfra.ledgertransaction.get("5656565656565656")

print(transaction)
```

**Response**

```python
LedgerTransaction(
    id=5656565656565656,
    ledger_id=5656565656565656,
    external_id=my-internal-id-123456,
    source=bank-transfer/123,
    amount=11234,
    fee=100,
    balance=11134,
    tags=['transfer/123', 'savings'],
    metadata={'orderId': '123', 'orderType': 'purchase'},
    created=2022-01-01 00:00:00
)
```

# Identity

## Business Identity

BusinessIdentities validate the identity of a legal entity (CNPJ) and feed its corporate documents into the Contract AI model.

After creating an identity, upload one or more Business Attachments referencing the returned id and PATCH the identity to processing. The structured signing rules extracted by the AI Model are delivered through the business-identity webhook when the identity reaches success.

### The BusinessIdentity object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the business identity. |
| `taxId` | STRING | CNPJ of the legal entity. Example: "20.018.183/0001-80". |
| `name` | STRING | Legal name of the company, fetched from the official bureau on creation. |
| `taxIdStatus` | STRING | Bureau status of the CNPJ, normalized from the Receita Federal value. Mapping: "active" = "ATIVA", "blocked" = "SUSPENSA", "pending" = "INAPTA", "canceled" = "BAIXADA", "voided" = "NULA". |
| `insightTaxId` | STRING | CNPJ extracted from the corporate documents by the AI Model. Empty until the analysis completes. |
| `insightDocumentType` | STRING | Document type detected by the AI Model. Empty until the analysis completes. |
| `representatives` | LIST OF OBJECTS | List of representative objects (sócios) fetched from the bureau. Each entry has name, qualification and taxId. |
| `attachments` | LIST OF STRINGS | List of attachment/<id> strings referencing the Business Attachments uploaded for this identity. |
| `rules` | LIST OF OBJECTS | List of signing rule objects extracted by the AI Model. Each entry carries reference, content, signaturesRequired and eligibles[] with name, taxId, role, isSignatureRequired and isRepresentative. Empty list until the analysis completes. |
| `tags` | LIST OF STRINGS | Tags associated with the business identity. |
| `status` | STRING | Current status of the business identity. Options: "created", "pending", "processing", "canceled", "success", "failed". |
| `created` | STRING | Creation datetime. Example: "2026-06-12T12:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2026-06-12T12:00:00.000000+00:00". |

### Create Business Identities

`POST /v2/business-identity`

Create one or more BusinessIdentities to start the Contract AI flow.

Each entry is created in pending status. Save the returned id — you'll use it as identityId when uploading the Business Attachments and as the path parameter on subsequent calls.

Validations: the CNPJ must be valid, must be active in the official bureau and must return non-empty representatives (sócios).

**Request**

```python
import starkinfra

identities = starkinfra.businessidentity.create([
    starkinfra.BusinessIdentity(
        tax_id="20.018.183/0001-80",
        tags=["onboarding-123"]
    )
])

for identity in identities:
    print(identity)
```

**Response**

```python
[
    BusinessIdentity(
        id="5740539971076096",
        tax_id="20.018.183/0001-80",
        name="STARK BANK S.A.",
        tax_id_status="active",
        insight_tax_id="",
        insight_document_type="",
        representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}],
        attachments=[],
        rules=[],
        tags=["onboarding-123"],
        status="pending",
        created="2026-06-12T12:00:00+00:00",
        updated="2026-06-12T12:00:00+00:00"
    )
]
```

### List Business Identities

`GET /v2/business-identity`

List and filter all business identities in your workspace. Results are returned paged via cursor.

**Request**

```python
import starkinfra

identities = starkinfra.businessidentity.query(
    after="2026-06-01",
    before="2026-06-30",
    status="success",
    tags=["onboarding-123"],
    limit=10
)

for identity in identities:
    print(identity)
```

**Response**

```python
[
    BusinessIdentity(
        id="5740539971076096",
        tax_id="20.018.183/0001-80",
        name="STARK BANK S.A.",
        tax_id_status="active",
        insight_tax_id="20.018.183/0001-80",
        insight_document_type="articles-of-incorporation",
        representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}],
        attachments=["attachment/5104320788332544"],
        rules=[{"reference": "Artigo 16, item (a)", "content": "pela assinatura isolada do Diretor Presidente", "signaturesRequired": 1, "eligibles": [{"name": "Daenerys Targaryen Stormborn", "taxId": "012.345.678-90", "role": "Diretor Presidente", "isSignatureRequired": True, "isRepresentative": True}]}],
        tags=["onboarding-123"],
        status="success",
        created="2026-06-12T12:00:00+00:00",
        updated="2026-06-12T12:10:00+00:00"
    )
]
```

### Get a Business Identity

`GET /v2/business-identity/:id`

Get a single business identity by its id. When status=success, the response includes the populated rules string with the signing combinations extracted by the AI Model.

**Request**

```python
import starkinfra

identity = starkinfra.businessidentity.get("5740539971076096")
print(identity)
```

**Response**

```python
BusinessIdentity(
    id="5740539971076096",
    tax_id="20.018.183/0001-80",
    name="STARK BANK S.A.",
    tax_id_status="active",
    insight_tax_id="20.018.183/0001-80",
    insight_document_type="articles-of-incorporation",
    representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}],
    attachments=["attachment/5104320788332544"],
    rules=[{"reference": "Artigo 16, item (a)", "content": "pela assinatura isolada do Diretor Presidente", "signaturesRequired": 1, "eligibles": [{"name": "Daenerys Targaryen Stormborn", "taxId": "012.345.678-90", "role": "Diretor Presidente", "isSignatureRequired": True, "isRepresentative": True}]}, {"reference": "Artigo 16, item (b)", "content": "pela assinatura de quaisquer 2 (dois) diretores em conjunto", "signaturesRequired": 2, "eligibles": [{"name": "Daenerys Targaryen Stormborn", "taxId": "012.345.678-90", "role": "Diretor Presidente", "isSignatureRequired": False, "isRepresentative": True}, {"name": "Jon Snow", "taxId": "098.765.432-10", "role": "Diretor de Riscos e Compliance", "isSignatureRequired": False, "isRepresentative": True}]}],
    tags=["onboarding-123"],
    status="success",
    created="2026-06-12T12:00:00+00:00",
    updated="2026-06-12T12:10:00+00:00"
)
```

### Update a Business Identity

`PATCH /v2/business-identity/:id`

Send a business identity to processing or replace its tags.

To trigger the AI Model analysis, set status=processing. The identity must be in created/pending status and must already have at least one Business Attachment associated with it.

**Request**

```python
import starkinfra

identity = starkinfra.businessidentity.update(
    id="5740539971076096",
    status="processing"
)

print(identity)
```

**Response**

```python
BusinessIdentity(
    id="5740539971076096",
    tax_id="20.018.183/0001-80",
    name="STARK BANK S.A.",
    tax_id_status="active",
    insight_tax_id="",
    insight_document_type="",
    representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}],
    attachments=["attachment/5104320788332544"],
    rules=[],
    tags=["onboarding-123"],
    status="processing",
    created="2026-06-12T12:00:00+00:00",
    updated="2026-06-12T12:05:00+00:00"
)
```

### Cancel a Business Identity

`DELETE /v2/business-identity/:id`

Cancel a business identity. Only identities in created or pending status can be canceled.

**Request**

```python
import starkinfra

identity = starkinfra.businessidentity.cancel("5740539971076096")
print(identity)
```

**Response**

```python
BusinessIdentity(
    id="5740539971076096",
    tax_id="20.018.183/0001-80",
    name="STARK BANK S.A.",
    tax_id_status="active",
    insight_tax_id="",
    insight_document_type="",
    representatives=[{"name": "Daenerys Targaryen Stormborn", "qualification": "Diretor", "taxId": "012.345.678-90"}],
    attachments=[],
    rules=[],
    tags=["onboarding-123"],
    status="canceled",
    created="2026-06-12T12:00:00+00:00",
    updated="2026-06-12T12:03:00+00:00"
)
```

### List Business Identity Logs

`GET /v2/business-identity/log`

Get a paged list of all business identity logs. A log tracks a change in the business identity entity according to its lifecycle.

**Request**

```python
import starkinfra

logs = starkinfra.businessidentity.log.query(
    types=["success", "failed"],
    identity_ids=["5740539971076096"],
    limit=10
)

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

**Response**

```python
[
    BusinessIdentityLog(
        id="6248173092645824",
        type="success",
        identity=BusinessIdentity(id="5740539971076096", status="success"),
        errors=[],
        created="2026-06-12T12:10:00+00:00"
    )
]
```

### Get a Business Identity Log

`GET /v2/business-identity/log/:id`

Get a single business identity log by its id.

**Request**

```python
import starkinfra

log = starkinfra.businessidentity.log.get("6248173092645824")
print(log)
```

**Response**

```python
BusinessIdentityLog(
    id="6248173092645824",
    type="success",
    identity=BusinessIdentity(id="5740539971076096", status="success"),
    errors=[],
    created="2026-06-12T12:10:00+00:00"
)
```

## Business Attachment

BusinessAttachments are corporate documents (articles of incorporation, amendments, board minutes) uploaded against a Business Identity.

Each Business Identity accepts up to two attachments. The attachment goes through OCR and document validation; once both attachments are approved, the parent identity can be sent to processing to run the AI Model analysis.

### The BusinessAttachment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the business attachment. |
| `name` | STRING | File name as provided on upload. Unique among the identity's other created attachments. |
| `businessIdentityId` | STRING | Id of the Business Identity that owns this attachment. |
| `attachmentId` | STRING | External attachment id in the document repository. Used internally to track approval. |
| `tags` | LIST OF STRINGS | Tags associated with the business attachment. |
| `status` | STRING | Current status of the attachment. Options: "created", "canceled", "approved", "denied". |
| `content` | STRING | Base64-encoded file content. Returned only when the GET request includes expand=content. |
| `created` | STRING | Creation datetime. Example: "2026-06-12T12:02:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2026-06-12T12:02:00.000000+00:00". |

### Upload a Business Attachment

`POST /v2/business-attachment`

Upload a single corporate document tied to a previously created Business Identity. Limit of 1 attachment per request and 2 attachments per identity.

Validations: only PDF, JPG and PNG are accepted, ≤ 8 MB per attachment; the name must be unique among the identity's other created attachments; the identity must be in created/pending status and have fewer than 2 attachments.

**Request**

```python
import starkinfra

attachments = starkinfra.businessattachment.create([
    starkinfra.BusinessAttachment(
        name="contrato-social.pdf",
        content="data:application/pdf;base64,JVBERi0xLjQK...",
        identity_id="5740539971076096",
        tags=["doc-principal"]
    )
])

for attachment in attachments:
    print(attachment)
```

**Response**

```python
[
    BusinessAttachment(
        id="6710539971076096",
        name="contrato-social.pdf",
        business_identity_id="5740539971076096",
        attachment_id="5104320788332544",
        tags=["doc-principal"],
        status="created",
        created="2026-06-12T12:02:00+00:00",
        updated="2026-06-12T12:02:00+00:00"
    )
]
```

### List Business Attachments

`GET /v2/business-attachment`

List and filter all business attachments in your workspace. Results are returned paged via cursor.

**Request**

```python
import starkinfra

attachments = starkinfra.businessattachment.query(
    after="2026-06-01",
    before="2026-06-30",
    status="approved",
    tags=["doc-principal"],
    limit=10
)

for attachment in attachments:
    print(attachment)
```

**Response**

```python
[
    BusinessAttachment(
        id="6710539971076096",
        name="contrato-social.pdf",
        business_identity_id="5740539971076096",
        attachment_id="5104320788332544",
        tags=["doc-principal"],
        status="approved",
        created="2026-06-12T12:02:00+00:00",
        updated="2026-06-12T12:08:00+00:00"
    )
]
```

### Get a Business Attachment

`GET /v2/business-attachment/:id`

Get a single business attachment by its id. Pass expand=content to include the base64 file payload in the response.

**Request**

```python
import starkinfra

attachment = starkinfra.businessattachment.get(
    "6710539971076096",
    expand=["content"]
)

print(attachment)
```

**Response**

```python
BusinessAttachment(
    id="6710539971076096",
    name="contrato-social.pdf",
    business_identity_id="5740539971076096",
    attachment_id="5104320788332544",
    tags=["doc-principal"],
    status="approved",
    content="data:application/pdf;base64,JVBERi0xLjQK...",
    created="2026-06-12T12:02:00+00:00",
    updated="2026-06-12T12:08:00+00:00"
)
```

### Cancel a Business Attachment

`DELETE /v2/business-attachment/:id`

Cancel a business attachment. Only attachments in created status can be canceled.

**Request**

```python
import starkinfra

attachment = starkinfra.businessattachment.cancel("6710539971076096")
print(attachment)
```

**Response**

```python
BusinessAttachment(
    id="6710539971076096",
    name="contrato-social.pdf",
    business_identity_id="5740539971076096",
    attachment_id="5104320788332544",
    tags=["doc-principal"],
    status="canceled",
    created="2026-06-12T12:02:00+00:00",
    updated="2026-06-12T12:03:30+00:00"
)
```

### List Business Attachment Logs

`GET /v2/business-attachment/log`

Get a paged list of all business attachment logs. A log tracks a change in the business attachment entity according to its lifecycle.

**Request**

```python
import starkinfra

logs = starkinfra.businessattachment.log.query(
    types=["approved", "denied"],
    attachment_ids=["6710539971076096"],
    limit=10
)

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

**Response**

```python
[
    BusinessAttachmentLog(
        id="5719045286731328",
        type="approved",
        attachment=BusinessAttachment(id="6710539971076096", status="approved"),
        errors=[],
        created="2026-06-12T12:08:00+00:00"
    )
]
```

### Get a Business Attachment Log

`GET /v2/business-attachment/log/:id`

Get a single business attachment log by its id.

**Request**

```python
import starkinfra

log = starkinfra.businessattachment.log.get("5719045286731328")
print(log)
```

**Response**

```python
BusinessAttachmentLog(
    id="5719045286731328",
    type="approved",
    attachment=BusinessAttachment(id="6710539971076096", status="approved"),
    errors=[],
    created="2026-06-12T12:08:00+00:00"
)
```

## Individual Identity

Individual Identities run an end-to-end identity verification on a Brazilian individual. Each entry wraps the proofs (document and/or facial biometrics) the holder must submit; Stark Infra orchestrates the collection, validates each proof and delivers the result through the individual-identity webhook subscription.

Identities are created in created status and are walked through processing, pending and finally success or failed by private workers. Every transition produces an Individual Identity Log.

### The IndividualIdentity object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the individual identity. |
| `name` | STRING | Full name of the holder being verified. |
| `taxId` | STRING | CPF of the holder. Optional at creation; can be patched later. Example: "012.345.678-90". |
| `email` | STRING | E-mail used to deliver the validatorLink when deliveryMethod = automatic. |
| `phone` | STRING | Holder's phone in international format. Optional. |
| `tags` | LIST OF STRINGS | Tags associated with the individual identity. |
| `proofs` | LIST OF STRINGS | List of proof types required by the identity. Options: identity, biometric. |
| `deliveryMethod` | STRING | How the validatorLink reaches the holder. Options: automatic, manual. |
| `validatorLink` | STRING | URL the holder opens to submit each proof. Carries the identityId encoded in the info query parameter. |
| `sourceId` | STRING | Id of the entity that triggered this verification. Filled automatically with the workspace id for external callers. |
| `sourceType` | STRING | Origin of the verification. Options: onboarding, reboarding, external. |
| `workspaceId` | STRING | Id of the workspace that owns this identity. |
| `status` | STRING | Current status of the individual identity. Options: "created", "processing", "pending", "success", "failed". |
| `created` | STRING | Creation datetime. Example: "2026-06-23T12:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2026-06-23T12:05:30.000000+00:00". |

### Create Individual Identities

`POST /v2/individual-identity`

Create one or more Individual Identities. Each entry is returned in created status and already carries the validatorLink the holder will use to submit each proof.

Validations: the workspace must have an Identity Profile; every value in proofs must be enabled on that profile.

**Request**

```python
import starkinfra

identities = starkinfra.individualidentity.create([
    starkinfra.IndividualIdentity(
        name="Daenerys Targaryen Stormborn",
        email="daenerys@example.com",
        delivery_method="automatic",
        proofs=["identity", "biometric"],
        tax_id="012.345.678-90",
        phone="+5511987654321",
        tags=["onboarding-123"]
    )
])

for identity in identities:
    print(identity)
```

**Response**

```python
[
    IndividualIdentity(
        id="5740977003561984",
        name="Daenerys Targaryen Stormborn",
        tax_id="012.345.678-90",
        email="daenerys@example.com",
        phone="+5511987654321",
        tags=["onboarding-123"],
        proofs=["identity", "biometric"],
        delivery_method="automatic",
        validator_link="https://starkbank.com/validator-link?info=eyJpZGVudGl0eUlkIjoiNTc0MDk3NzAwMzU2MTk4NCJ9",
        source_id="6480539068923904",
        source_type="external",
        workspace_id="6480539068923904",
        status="created",
        created="2026-06-23T12:00:00.000000+00:00",
        updated="2026-06-23T12:00:00.000000+00:00"
    )
]
```

### List Individual Identities

`GET /v2/individual-identity`

List and filter all individual identities in your workspace. Results are returned paged via cursor.

**Request**

```python
import starkinfra

identities = starkinfra.individualidentity.query(
    status=["pending", "success"],
    tags=["onboarding-123"],
    limit=10
)

for identity in identities:
    print(identity)
```

**Response**

```python
[
    IndividualIdentity(
        id="5740977003561984",
        name="Daenerys Targaryen Stormborn",
        tax_id="012.345.678-90",
        status="pending",
        proofs=["identity", "biometric"],
        delivery_method="automatic",
        created="2026-06-23T12:00:00.000000+00:00",
        updated="2026-06-23T12:00:10.000000+00:00"
    )
]
```

### Get an Individual Identity

`GET /v2/individual-identity/:id`

Get a single individual identity by its id.

**Request**

```python
import starkinfra

identity = starkinfra.individualidentity.get("5740977003561984")
print(identity)
```

**Response**

```python
IndividualIdentity(
    id="5740977003561984",
    name="Daenerys Targaryen Stormborn",
    tax_id="012.345.678-90",
    email="daenerys@example.com",
    phone="+5511987654321",
    tags=["onboarding-123"],
    proofs=["identity", "biometric"],
    delivery_method="automatic",
    validator_link="https://starkbank.com/validator-link?info=eyJpZGVudGl0eUlkIjoiNTc0MDk3NzAwMzU2MTk4NCJ9",
    source_id="6480539068923904",
    source_type="external",
    workspace_id="6480539068923904",
    status="success",
    created="2026-06-23T12:00:00.000000+00:00",
    updated="2026-06-23T12:05:30.000000+00:00"
)
```

### Update an Individual Identity

`PATCH /v2/individual-identity/:id`

Update the taxId of an individual identity after it has been created. Useful when the CPF is unknown at creation time and is only collected during the proof submission flow.

**Request**

```python
import starkinfra

identity = starkinfra.individualidentity.update(
    id="5740977003561984",
    tax_id="012.345.678-90"
)

print(identity)
```

**Response**

```python
IndividualIdentity(
    id="5740977003561984",
    name="Daenerys Targaryen Stormborn",
    tax_id="012.345.678-90",
    status="pending",
    proofs=["identity", "biometric"],
    delivery_method="automatic",
    created="2026-06-23T12:00:00.000000+00:00",
    updated="2026-06-23T12:02:00.000000+00:00"
)
```

### Cancel an Individual Identity

`DELETE /v2/individual-identity/:id`

Cancel an individual identity (soft delete). The identity transitions to failed, every pending proof is canceled and a canceled log is delivered through the webhook. Only identities in created or pending status can be canceled.

**Request**

```python
import starkinfra

identity = starkinfra.individualidentity.cancel("5740977003561984")
print(identity)
```

**Response**

```python
IndividualIdentity(
    id="5740977003561984",
    name="Daenerys Targaryen Stormborn",
    status="failed",
    proofs=["identity", "biometric"],
    delivery_method="automatic",
    created="2026-06-23T12:00:00.000000+00:00",
    updated="2026-06-23T12:03:00.000000+00:00"
)
```

### List Individual Identity Logs

`GET /v2/individual-identity/log`

Get a paged list of all individual identity logs. A log tracks a change in the individual identity entity according to its lifecycle.

**Request**

```python
import starkinfra

logs = starkinfra.individualidentity.log.query(
    types=["success", "failed"],
    identity_ids=["5740977003561984"],
    limit=10
)

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

**Response**

```python
[
    IndividualIdentityLog(
        id="6661702144623308",
        type="success",
        identity=IndividualIdentity(id="5740977003561984", status="success"),
        errors=[],
        created="2026-06-23T12:05:30.000000+00:00"
    )
]
```

### Get an Individual Identity Log

`GET /v2/individual-identity/log/:id`

Get a single individual identity log by its id.

**Request**

```python
import starkinfra

log = starkinfra.individualidentity.log.get("6661702144623308")
print(log)
```

**Response**

```python
IndividualIdentityLog(
    id="6661702144623308",
    type="success",
    identity=IndividualIdentity(id="5740977003561984", status="success"),
    errors=[],
    created="2026-06-23T12:05:30.000000+00:00"
)
```

## Individual Identity Proof

Each Individual Identity Proof represents one piece of evidence required by the parent Individual Identity. One proof is generated per proofType requested at creation; the holder submits the content via PATCH /v2/individual-identity-proof/:id.

Proofs go through their own lifecycle (pending → processing → success / failed / canceled / expired). The parent identity transitions to success only when every proof reaches success.

### The IndividualIdentityProof object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the individual identity proof. |
| `proofType` | STRING | Type of evidence required. Options: identity, biometric. |
| `metadata` | DICTIONARY | Raw payload returned by the provider after the proof is validated. Empty until the proof reaches processing. |
| `status` | STRING | Current status of the proof. Options: "pending", "processing", "success", "failed", "canceled", "expired". |
| `individualIdentityId` | STRING | Id of the parent individual identity. |
| `created` | STRING | Creation datetime. Example: "2026-06-23T12:00:10.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2026-06-23T12:03:00.000000+00:00". |

### List Individual Identity Proofs

`GET /v2/individual-identity-proof`

List the proofs tied to an Individual Identity. The identityId query parameter is required.

**Request**

```python
import starkinfra

proofs = starkinfra.individualidentityproof.query(
    identity_id="5740977003561984",
    status=["pending", "processing"],
    limit=10
)

for proof in proofs:
    print(proof)
```

**Response**

```python
[
    IndividualIdentityProof(
        id="4512334302912512",
        proof_type="biometric",
        metadata={},
        status="pending",
        individual_identity_id="5740977003561984",
        created="2026-06-23T12:00:10.000000+00:00",
        updated="2026-06-23T12:00:10.000000+00:00"
    )
]
```

### Get an Individual Identity Proof

`GET /v2/individual-identity-proof/:id`

Get a single individual identity proof by its id.

**Request**

```python
import starkinfra

proof = starkinfra.individualidentityproof.get("4512334302912512")
print(proof)
```

**Response**

```python
IndividualIdentityProof(
    id="4512334302912512",
    proof_type="identity",
    metadata={"documentId": "doc-abc-123", "documentType": "RG"},
    status="success",
    individual_identity_id="5740977003561984",
    created="2026-06-23T12:00:10.000000+00:00",
    updated="2026-06-23T12:03:00.000000+00:00"
)
```

### Submit an Individual Identity Proof

`PATCH /v2/individual-identity-proof/:id`

Submit the content of a proof. This is the step in which the holder's document or biometric is uploaded for validation.

biometric — content is a base64 image string with the facial selfie.

identity — content is a JSON-serialised string carrying the provider's documentId and/or the document file (base64 image).

After a successful PATCH the proof transitions from pending to processing and the provider validates it asynchronously.

**Request**

```python
import starkinfra

proof = starkinfra.individualidentityproof.update(
    id="4512334302912512",
    content="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
)

print(proof)
```

**Response**

```python
IndividualIdentityProof(
    id="4512334302912512",
    proof_type="biometric",
    metadata={},
    status="processing",
    individual_identity_id="5740977003561984",
    created="2026-06-23T12:00:10.000000+00:00",
    updated="2026-06-23T12:02:00.000000+00:00"
)
```

## Individual Holmes

Individual Holmes queries an external bureau or one of Stark Infra's internal datasets to investigate an individual (CPF). Each request targets a single bureau through the type path parameter and returns that bureau's payload under a key named after the type queried.

Use Individual Holmes to run KYC, anti-fraud, judicial, sanctions and federal-revenue checks on a person before onboarding, granting credit or releasing a high-risk operation. Every call is synchronous, scoped to your workspace and logged on Stark Infra's side — there is no resource lifecycle to track.

### Query an Individual Bureau

`GET /individual-holmes/:searchKey/:type`

Path params identify what to look up. The searchKey is a CPF (11 digits, masked or unmasked) for every bureau except internationalPep, where it is the person's full name. The type selects the bureau and the shape of the response.

Query params control paging. Only civil and criminal (JusBrasil) honour cursor — repeat the request with the returned cursor to fetch the next page.

**Request**

```python
import starkinfra

result = starkinfra.individualholmes.get(
    search_key="01234567890",
    type="kyc",
)

print(result)
```

**Response**

```python
The payload key and its inner shape depend on the bureau "type" queried. For each type (civil, criminal, frauds, data, dict, kyc, nationalPep, internationalPep, jointResolution6, csnu, federalRevenueRegistry, deceased, negativeMedia) the response is documented in the corresponding section of the <a href="/get-started/individual-holmes" class="link">get-started</a>.
```

## Business Holmes

Business Holmes queries an external bureau or one of Stark Infra's internal datasets to investigate a legal entity (CNPJ). Each request targets a single bureau through the type path parameter and returns that bureau's payload under a key named after the type queried.

Use Business Holmes to run KYB, judicial, anti-fraud, sanctions, QSA (corporate structure) and federal-revenue checks on a company before onboarding it, granting credit or releasing a high-risk operation. Every call is synchronous, scoped to your workspace and logged on Stark Infra's side — there is no resource lifecycle to track.

### Query a Business Bureau

`GET /business-holmes/:taxId/:type`

Path params identify what to look up. The taxId is the company's CNPJ (14 digits, masked or unmasked); the type selects the bureau and the shape of the response.

Query params control paging. Only civil and criminal (JusBrasil) honour cursor — repeat the request with the returned cursor to fetch the next page.

**Request**

```python
import starkinfra

result = starkinfra.businessholmes.get(
    tax_id="20018183000180",
    type="kyc",
)

print(result)
```

**Response**

```python
The payload key and its inner shape depend on the bureau "type" queried. For each type (civil, criminal, kyc, frauds, data, dict, jointResolution6, federalRevenueRegistry, negativeMedia, qsa) the response is documented in the corresponding section of the <a href="/get-started/business-holmes" class="link">get-started</a>.
```

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

NOTE 1: Registered webhooks will only work for services used in that same version.

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.

### The Webhook Object

**Attributes**

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

### Create a Webhook

`POST /v2/webhook`

Register a new webhook URL. The subscriptions refer to which kinds of logs will be sent to the webhook URL being registered.

Available subscriptions: pix-request, pix-reversal, pix-pull-subscription, pix-pull-request, pix-internal-transaction-report, pix-key, pix-key-holmes, pix-claim, pix-infraction, pix-chargeback, pix-dispute, issuing-card, issuing-holder, issuing-purchase, issuing-invoice, credit-note or credit-holmes

**Request**

```python
import starkinfra

webhook = starkinfra.webhook.create(
    url="https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec",
    subscriptions=[
        "pix-request",
        "pix-reversal",
        "pix-key",
        "credit-note",
        "credit-holmes"
    ]
)

print(webhook)
```

**Response**

```python
Webhook(
    id=5601079539523584,
    url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec,
    subscriptions=['pix-request', 'pix-reversal', 'pix-key', 'credit-note', 'credit-holmes']
)
```

### List Webhooks

`GET /v2/webhook`

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

**Request**

```python
import starkinfra

webhooks = starkinfra.webhook.query(limit=10)

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

**Response**

```python
Webhook(
    id=5601079539523584,
    url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec,
    subscriptions=['pix-request', 'credit-note']
)
```

### Get a Webhook

`GET /v2/webhook/:id`

Get a single Webhook by its id.

**Request**

```python
import starkinfra

webhook = starkinfra.webhook.get("5601079539523584")

print(webhook)
```

**Response**

```python
Webhook(
    id=5601079539523584,
    url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec,
    subscriptions=['pix-request', 'credit-note']
)
```

### Delete a Webhook

`DELETE /v2/webhook/:id`

Delete a single Webhook subscription.

NOTE: This action cannot be undone.

**Request**

```python
import starkinfra

webhook = starkinfra.webhook.delete("5601079539523584")

print(webhook)
```

**Response**

```python
Webhook(
    id=5601079539523584,
    url=https://webhook.site/dd784f26-1d6a-4ca6-81cb-fda0267761ec,
    subscriptions=['pix-request', 'credit-note']
)
```

## 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 credit-note, the log in the event will be a CreditNoteLog.

### The Event object

**Attributes**

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

### List Events

`GET /v2/event`

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

**Request**

```python
import starkinfra

events = starkinfra.event.query(limit=10, is_delivered=False)

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

**Response**

```python
Event(
    id=5719405850615809,
    log=CreditNote.Log(id=5155165527080961, type=created),
    created=2022-06-01T00:00:00.000000+00:00,
    is_delivered=False,
    subscription=credit-note,
    workspace_id=4019167990849536
)
```

### Get an Event

`GET /v2/event/:id`

Get a single Event by its id.

**Request**

```python
import starkinfra

event = starkinfra.event.get("5719405850615809")

print(event)
```

**Response**

```python
Event(
    id=5719405850615809,
    log=CreditNote.Log(id=5155165527080961, type=created),
    created=2022-06-01T00:00:00.000000+00:00,
    is_delivered=False,
    subscription=credit-note,
    workspace_id=4019167990849536
)
```

### Delete an Event

`DELETE /v2/event/:id`

Delete a single Event from the event list.

Note: This action cannot be undone.

**Request**

```python
import starkinfra

event = starkinfra.event.delete("5719405850615809")

print(event)
```

**Response**

```python
Event(
    id=5719405850615809,
    log=CreditNote.Log(id=5155165527080961, type=created),
    created=2022-06-01T00:00:00.000000+00:00,
    is_delivered=False,
    subscription=credit-note,
    workspace_id=4019167990849536
)
```

### Update an Event

`PATCH /v2/event/:id`

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

**Request**

```python
import starkinfra

event = starkinfra.event.update(
    "5719405850615809",
    is_delivered=True
)

print(event)
```

**Response**

```python
Event(
    id=5719405850615809,
    log=CreditNote.Log(id=5155165527080961, type=created),
    created=2022-06-01T00:00:00.000000+00:00,
    is_delivered=True,
    subscription=credit-note,
    workspace_id=4019167990849536
)
```

## Event Attempt

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

### The Event Attempt object

**Attributes**

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

### List failed Webhook Event delivery attempts

`GET /v2/event/attempt`

Get information on failed webhook event delivery attempts.

**Request**

```python
import starkinfra

attempts = starkinfra.event.attempt.query(limit=10)

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

**Response**

```python
Attempt(
    id=6891221774008321,
    code=CONNECTION_ERROR,
    message=Connection refused,
    event_id=5719405850615809,
    webhook_id=5601079539523584,
    created=2022-06-01T00:00:00.000000+00:00
)
```

### Get an Event Attempt

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

Get a single event attempt by its id.

**Request**

```python
import starkinfra

attempt = starkinfra.event.attempt.get("6891221774008321")

print(attempt)
```

**Response**

```python
Attempt(
    id=6891221774008321,
    code=CONNECTION_ERROR,
    message=Connection refused,
    event_id=5719405850615809,
    webhook_id=5601079539523584,
    created=2022-06-01T00:00:00.000000+00:00
)
```

---

## Other Languages

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