# Direct Pix Participant

A Direct Participant connects to the Brazilian Central Bank (Bacen) Pix system with its own ISPB and operates under its own license.

Stark Infra abstracts the complexity of SPI and DICT, so integrating with Bacen can be simple. Forget complex messaging and low-level message handling. We provide the integration layer so you can route inbound and outbound Pix payments, manage your DICT keys, raise disputes, claim portability, and operate within the Pix rulebook without building the low-level Bacen integration yourself.

This guide walks you through every Pix resource a Direct Participant uses, from sending and receiving payments to managing keys, claims, infractions, frauds, chargebacks and the Brcodes that initiate payments.

Dispute handling — infractions, chargebacks, fraud markers and disputes — lives in the MED guide, and recurring Pix in the Pix Automático guide.

NOTE: Direct participation requires authorization with Bacen. If you don't yet hold a Pix license, see the Indirect Participant guide first.

**RESOURCE SUMMARY**

Pix RequestSend and receive Pix payments through SPI.Pix ReversalRefund a received Pix back to its sender.Pix Internal Transaction ReportReport transactions that were settled internally on the participant.Static BrcodeGenerate reusable QR codes that initiate Pix payments.Dynamic BrcodeGenerate single-use QR codes with custom amounts and metadata.Brcode PreviewGet information from a QR code to initiate a Pix payment or accept a Pix Subscription.Pix KeyRegister CPF, CNPJ, phone, e-mail or random keys in DICT.Pix ClaimClaim a Pix key from another participant via portability or ownership.Pix UserConsult end-user statistics about Pix keys, Pix requests, frauds and infractions registered in Bacen's systems.Pix BalanceConsult the Bacen settlement account balance.Pix DomainList Pix participant domains registered with Bacen to provide Brcodes, along with their respective certificates.Pix StatementGenerate end-of-day statements as required by Bacen.Pix DirectorRegister the responsible director (DPO) for your participant.

## Pix Operations

Stark Infra brings together everything a direct participant needs, from the connection with the Central Bank to the full automation of your Pix operations. The main operations available:

Balance managementView and control your settlement account balance directly through the Stark Infra API.Pix key managementCreate, edit and synchronize Pix keys with DICT with full control.Transaction inquiryAccess the full history of Pix transactions, filtered by date, amount and status.MED managementOpen and track refund requests through the Special Return Mechanism (MED).Key synchronizationKeep your keys always up to date with the Central Bank's directory.Reversal managementManage refunds and reversals with full visibility over the process.

## Our Infrastructure

The Stark Infra system is the same one Stark SCD uses as a direct participant of Pix. We face the same challenges, evolve continuously and deliver a reliable experience for your institution.

High availabilityExtremely high availability and scalability for millions of Pix transactions, 24/7. You focus on your business; we take care of the infrastructure.Pix Automático, QR Code and moreNew Bacen products don't have to be complicated. Our interfaces let your institution offer every Pix feature without extra work.100% in the cloudYour connection to Bacen runs fully in the cloud — no worries about updates, security, versioning or infrastructure.

## Integration via SDKs and APIs

Our SDKs handle the ECDSA cryptography for you, ensuring a simple and secure integration without the headache. See How to create your ECDSA keys to generate your keys.

Stark Infra offers a high-performance, direct connection to the Central Bank, ready to scale at the speed of your business — without intermediaries.

## Setup

Before you start, confirm the following with your workspace administrator:

1. Your workspace is enabled as a Direct Participant in the desired environment (Sandbox or Production).

2. Your ISPB has been registered with Bacen and tested in DICT.

3. A webhook has been created subscribing to the Pix events you want to consume (pix-request, pix-reversal, pix-internal-transaction-report, pix-key, pix-claim, pix-infraction, pix-chargeback, pix-dispute, pix-pull-subscription, pix-pull-request).

4. A Pix Director has been registered. This is mandatory before any Pix operations can be performed in production.

## Pix Request Overview

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

**Parameters**

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

### Receiving a Pix Request

Every time a Pix participant sends you a Pix, an inbound Pix Request is created and we send you a synchronous POST authorization request to your registered pixRequestUrl, which you must analyze and answer with approval or denial. You must respond to this synchronous authorization webhook within 1 second; if you do not respond in time, Stark Infra resolves the authorization using the default behavior. If no pixRequestUrl is registered, the inbound Pix Request is denied by default.

### The Pix Request Status

After creation, you can use asynchronous Webhooks to monitor status changes of a Pix Request.

Outbound Pix Requests (the ones you send) follow this life cycle:

Inbound Pix Requests (the ones you receive and authorize) follow this life cycle:

| Status | Description |
| --- | --- |
| Created | The Pix Request was registered at Stark Infra. |
| Processing | The Pix Request is being processed. |
| Success | The Pix Request was completed and settled. |
| Failed | The Pix Request failed or was denied. |

### The Pix Request Logs

Every time we change a Pix Request, we create a Log. Logs are useful for understanding the life cycle of each Pix Request, and we fire a Webhook to your registered URL whenever a new Log is created. The possible Pix Request Logs:

For inbound Pix Requests:

| Log type | Status | Description |
| --- | --- | --- |
| Success | Success | The Pix Request was completed successfully. |
| Failed | Failed | The Pix Request failed. |
| Denied | Failed | The inbound Pix Request authorization was denied. |

### 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"
    )
]
```

### Create Pix Requests from a Pix Key

Resolve the receiver's Pix Key with Get a Pix Key to fetch their account data from DICT, then create the Pix Request with those fields and the resolved receiverKeyId. The method is inferred as "dict".

**Request**

```python
import starkinfra

my_bank_code = "34052649"
end_to_end_id = starkinfra.endtoendid.create(my_bank_code)

key = starkinfra.pixkey.get(
    "+5511285025604",
    payer_id="594.739.480-42",
    end_to_end_id=end_to_end_id
)

requests = starkinfra.pixrequest.create([
    starkinfra.PixRequest(
        amount=10000,
        description="A Lannister always pays his debts",
        end_to_end_id=end_to_end_id,
        external_id="my_unique_id_170",
        receiver_account_number=key.account_number,
        receiver_account_type=key.account_type,
        receiver_bank_code=key.bank_code,
        receiver_branch_code=key.branch_code,
        receiver_key_id=key.id,
        receiver_name=key.name,
        receiver_tax_id=key.tax_id,
        sender_account_number="00000",
        sender_account_type="checking",
        sender_branch_code="0000",
        sender_name="jaime Lannister",
        sender_tax_id="594.739.480-42",
        tags=['lannister', 'war/123']
    )
])

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

**Response**

```python
PixRequest(
    amount=10000,
    cash_amount=0,
    cashier_bank_code=,
    cashier_type=,
    created=2022-08-05 19:19:47.256075,
    description=A Lannister always pays his debts,
    end_to_end_id=E34052649202245501450u34sDGd19lz,
    external_id=my_unique_id_170,
    fee=0,
    flow=out,
    id=6123232910376960,
    initiator_tax_id=,
    method=dict,
    receiver_account_number=0000,
    receiver_account_type=savings,
    receiver_bank_code=35547753,
    receiver_branch_code=0000,
    receiver_key_id=+5511285025604,
    receiver_name=Jaime Lannister,
    receiver_tax_id=012.345.678-90,
    reconciliation_id=,
    sender_account_number=00000,
    sender_account_type=checking,
    sender_bank_code=34052649,
    sender_branch_code=0000,
    sender_name=jaime Lannister,
    sender_tax_id=594.739.480-42,
    status=created,
    tags=['lannister', 'war/123'],
    updated=2022-08-05 19:19:47.256092
)
```

### Create Pix Requests from a Brcode

Preview a Brcode with Brcode Preview to obtain the payment and receiver data, then create the Pix Request from it. The method is "staticQrcode" or "dynamicQrcode".

**Request**

```python
import starkinfra

my_bank_code = "35547753"

previews = starkinfra.brcodepreview.create([
    starkinfra.BrcodePreview(
        id="00020126360014br.gov.bcb.pix0114+5541999999999520400005303986540510.005802BR5910Tony Stark6014Rio de Janeiro62070503***630466B7"
    )
])
preview = previews[0]

requests = starkinfra.pixrequest.create([
    starkinfra.PixRequest(
        amount=preview.amount,
        description="A Lannister always pays his debts",
        end_to_end_id=starkinfra.endtoendid.create(my_bank_code),
        external_id="my_unique_id_170",
        receiver_account_number=preview.account_number,
        receiver_account_type=preview.account_type,
        receiver_bank_code=preview.bank_code,
        receiver_branch_code=preview.branch_code,
        receiver_name=preview.name,
        receiver_tax_id=preview.tax_id,
        receiver_key_id=preview.key_id,
        reconciliation_id=preview.reconciliation_id,
        sender_account_number="00000",
        sender_account_type="checking",
        sender_branch_code="0000",
        sender_name="jaime Lannister",
        sender_tax_id="594.739.480-42",
        tags=['lannister', 'war/123']
    )
])

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

**Response**

```python
PixRequest(
    amount=1000,
    cash_amount=0,
    cashier_bank_code=,
    cashier_type=,
    created=2022-08-22 21:01:48.917564,
    description=A Lannister always pays his debts,
    end_to_end_id=E35547753202208222101Ll2MpIBYy08,
    external_id=my_unique_id_170,
    fee=0,
    flow=out,
    id=6298665144549376,
    initiator_tax_id=,
    method=staticQrcode,
    receiver_account_number=2446567693893903,
    receiver_account_type=checking,
    receiver_bank_code=03412878,
    receiver_branch_code=5742,
    receiver_key_id=+5511285025604,
    receiver_name=Jaime Lannister,
    receiver_tax_id=012.345.678-90,
    reconciliation_id=12345678910,
    sender_account_number=00000,
    sender_account_type=checking,
    sender_bank_code=35547753,
    sender_branch_code=0000,
    sender_name=jaime Lannister,
    sender_tax_id=594.739.480-42,
    status=created,
    tags=['lannister', 'war/123'],
    updated=2022-08-22 21:01:48.917580
)
```

### Create Pix Requests for a Pix Pull Request

Settle a scheduled Pix Pull Request (Pix Automático) by creating a Pix Request with method="subscription", passing the pull request's endToEndId and a matching reconciliationId.

The amount, tax IDs and receiver account fields must match the pull request.

**Request**

```python
import starkinfra

requests = starkinfra.pixrequest.create([
    starkinfra.PixRequest(
        amount=1000,
        external_id="my-external-id-1",
        end_to_end_id="E20018183202201011000r01",
        method="subscription",
        reconciliation_id="my-pull-request-reconciliation-id",
        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)
```

### Create Pix Requests for a Pix Chargeback

A Pix Chargeback you receive may carry reversal account data. Close it by creating a Pix Request that returns the funds to that account, mapping the chargeback's reversal fields onto the receiver fields: receiverBankCode from reversalBankCode, receiverBranchCode from reversalBranchCode, receiverAccountNumber from reversalAccountNumber, receiverAccountType from reversalAccountType and receiverTaxId from reversalTaxId.

Set reason="fraud" and senderTaxId to your institution's organization taxId (CNPJ), which is required for this reason.

**Request**

```python
import starkinfra

# map the received chargeback's reversal_* fields onto the receiver_* fields
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="20.018.183/0001-80",
        receiver_bank_code=chargeback.reversal_bank_code,
        receiver_branch_code=chargeback.reversal_branch_code,
        receiver_account_number=chargeback.reversal_account_number,
        receiver_account_type=chargeback.reversal_account_type,
        receiver_tax_id=chargeback.reversal_tax_id,
        reason="fraud",
        tags=["chargeback", "pix"]
    )
])

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

### Create Pix Requests with cashAmount, cashierType and cashierBankCode parameters

For Pix Saque and Pix Troco, set cashAmount (less than or equal to amount) to withdraw cash on payment.

This requires cashierType (one of "participant", "merchant", "other") and cashierBankCode (the cashier's 8-digit ISPB).

**Request**

```python
import starkinfra

requests = starkinfra.pixrequest.create([
    starkinfra.PixRequest(
        amount=10000,
        external_id="my-external-id-1",
        end_to_end_id="E20018183202201011000r01",
        cash_amount=1000,
        cashier_type="merchant",
        cashier_bank_code="20018183",
        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)
```

### Create Pix Requests with initiatorTaxId parameter

Pass initiatorTaxId (the payment initiator's CPF/CNPJ) to register the initiator of the payment.

The endToEndId must be issued under the initiator's ISPB.

**Request**

```python
import starkinfra

requests = starkinfra.pixrequest.create([
    starkinfra.PixRequest(
        amount=1000,
        external_id="my-external-id-1",
        end_to_end_id="E20018183202201011000r01",
        initiator_tax_id="20.018.183/0001-80",
        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)
```

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

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

**Parameters**

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

### Receiving a Pix Reversal

Every time a Pix participant reverses a Pix you have successfully sent, a Pix Reversal is created and an authorization request is sent to your pixReversalUrl, which you must analyze and answer with approval or denial. You must respond to this synchronous authorization webhook within 1 second; if you do not respond in time, Stark Infra resolves the authorization using the default behavior. If no pixReversalUrl is registered, the inbound Pix Reversal is accepted by default.

### The Pix Reversal Status

After creation, you can use asynchronous Webhooks to monitor status changes of a Pix Reversal.

Outbound Pix Reversals (the ones you send) follow this life cycle:

Inbound Pix Reversals (the ones you receive and authorize) follow this life cycle:

| Status | Description |
| --- | --- |
| Created | The Pix Reversal creation request was registered at Stark Infra. |
| Processing | The Pix Reversal is being processed. |
| Success | The Pix Reversal was completed. |
| Failed | The Pix Reversal failed or was denied. |

### The Pix Reversal Logs

Every time we change a Pix Reversal, we create a Log. Logs are useful for understanding the life cycle of each Pix Reversal, and we fire a Webhook whenever a new Log is created. The possible Pix Reversal Logs:

For inbound Pix Reversals:

| Log type | Status | Description |
| --- | --- | --- |
| Success | Success | The Pix Reversal was completed. |
| Failed | Failed | The Pix Reversal failed. |

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

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

**Parameters**

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

### The Pix Internal Transaction Report Status

After creation, you can use asynchronous Webhooks to monitor status changes. A Pix Internal Transaction Report follows the life cycle below:

| Status | Description |
| --- | --- |
| Created | The Pix internal transaction report was registered at Stark Infra. |
| Processing | The Pix internal transaction report was sent to Bacen and is awaiting a response. |
| Success | The Pix internal transaction report was accepted by Bacen. |
| Failed | The Pix internal transaction report was rejected by Bacen. |

### The Pix Internal Transaction Report Logs

Every time we change a Pix Internal Transaction Report, we create a Log. Logs are useful for understanding the life cycle of each report. Whenever a new Log is created, we fire a Webhook to your registered URL. Check the diagram below to understand the possible Pix Internal Transaction Report Logs:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Pix internal transaction report was registered and queued to be sent. |
| Sent | Processing | The Pix internal transaction report was sent to Bacen. |
| Success | Success | The Pix internal transaction report was accepted by Bacen. |
| Failed | Failed | The Pix internal transaction report was rejected by Bacen. |

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

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

**Parameters**

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

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

**Parameters**

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

### Reconcile a Dynamic Brcode

When the Dynamic Brcode gets paid, you receive a Pix Request carrying the reconciliationId you answered in the read request.

Use that reconciliationId to find your corresponding invoice and verify that all data is correct before accepting it.

Once the Pix Request payment is completed and its status turns to success, update your invoice status to paid.

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

### Receiving a Dynamic Brcode Read Request

When a Dynamic Brcode is read, Stark Infra sends you a synchronous GET HTTP request to your registered dynamicBrcodeUrl in order to retrieve the remaining information required to complete the transaction, such as amount, discounts and fines.

The request includes the UUID of the Brcode as a path variable and the Dynamic Brcode type as a query parameter: instant, due or subscription. Subscription reads are covered in the Pix Pull Subscription guide.

For security reasons, we sign the UUID and send you the Digital Signature. You can use our SDK to validate it before returning your response.

Answer with HTTP 200 and a JSON body whose format depends on the type query parameter.

## Brcode Preview Overview

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

**Parameters**

| 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 Key Overview

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

**Parameters**

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

### The Pix Key Status

After creation, you can use asynchronous Webhooks to monitor status changes. A Pix Key follows the life cycle below:

| Status | Description |
| --- | --- |
| Created | The Pix Key creation request was registered at Stark Infra. |
| Registered | The Pix Key was successfully registered in DICT and is ready to use. |
| Canceled | The Pix Key was removed from DICT. |
| Failed | The Pix Key registration failed. |

### The Pix Key Logs

Every time we change a Pix Key, we create a Log. Logs are useful for understanding the life cycle of each Pix Key. Whenever a new Log is created, we fire a Webhook to your registered URL. Check the diagram below to understand the possible Pix Key Logs:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Pix Key creation request was registered at Stark Infra. |
| Registered | Registered | The Pix Key was successfully registered in DICT. |
| Canceled | Canceled | The Pix Key was removed from DICT. |
| Failed | Failed | The Pix Key registration failed. |

### 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 Claim Overview

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

**Parameters**

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

### Receiving a Pix Claim

When another participant claims a Pix Key registered under your bank code, an inbound Pix Claim is created for you to analyze and answer within the resolution period.

### The Pix Claim Status

After creation, you can use asynchronous Webhooks to monitor status changes of a Pix Claim. A confirmed status indicates the donor participant confirmed the claim and the Pix Key was deleted; when the status changes to success, the exchange is complete and a new Pix Key is linked to your user's account.

Pix Claims you open (outbound) follow this life cycle:

To monitor received Pix Claims, register a webhook with a pix-claim subscription and filter by the flow attribute. Inbound Pix Claims follow this life cycle:

| Status | Description |
| --- | --- |
| Created | The Pix Claim was successfully created at Stark Infra. |
| Failed | The Pix Claim could not be completed. |
| Delivered | The Pix Claim was delivered to the donor participant and is awaiting an answer. |
| Confirmed | The donor participant confirmed the claim and the Pix Key was deleted. |
| Success | The exchange is complete and the Pix Key is now linked to your user's account. |
| Canceled | The Pix Claim was canceled or rejected. |

### The Pix Claim Logs

Every time we change a Pix Claim, we create a Log. Logs are useful for understanding the life cycle of each Pix Claim, and we fire a Webhook whenever a new Log is created. The possible Pix Claim Logs:

For inbound Pix Claims:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Pix Claim was successfully created at Stark Infra. |
| Delivered | Delivered | The Pix Claim was delivered to the donor participant and is awaiting an answer. |
| Confirmed | Confirmed | The donor participant confirmed the claim and the Pix Key was deleted. |
| Success | Success | The exchange is complete and the Pix Key is now linked to your user's account. |
| Canceled | Canceled | The Pix Claim was canceled or rejected. |
| Failed | Failed | The Pix Claim could not be completed. |

### 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 User Overview

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

**Parameters**

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

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

**Parameters**

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

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

**Parameters**

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

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

**Parameters**

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

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

**Parameters**

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

---

## Other Languages

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