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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `accountCreated` | REQUIRED | Creation date of the linked bank account. |
| `accountNumber` | REQUIRED | Account number of the linked bank account. |
| `accountType` | REQUIRED | Type of the linked bank account. Options: "checking", "savings", "salary", "payment", "other". |
| `branchCode` | REQUIRED | Branch code of the linked bank account. |
| `name` | REQUIRED | Name of the account holder. |
| `taxId` | REQUIRED | CPF or CNPJ of the account holder. |
| `id` | OPTIONAL | Key value (CPF, CNPJ, email, phone). Leave empty to generate an EVP key. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of key values to get specific entities. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter by status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `taxId` | OPTIONAL | Filter Pix keys by the holder's CPF or CNPJ. |
| `type` | OPTIONAL | Filter by key type. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id (key value) of the Pix key entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `payerTaxId` | OPTIONAL | Not a parameter you provide: the API automatically uses your Workspace's own registered tax ID (CPF/CNPJ) as the payer for DICT query rate-limiting purposes, so this field should be omitted. Any value sent has no effect. |
| `endToEndId` | OPTIONAL | Unique end-to-end ID of the Pix transaction associated with this DICT query. |
| `expand` | OPTIONAL | Entity fields to expand in the response. Options: "statistics", "ownerStatistics". |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id (key value) of the Pix key entity. |
| `reason` | REQUIRED | Reason for the update. Options: "branchTransfer", "reconciliation", "userRequested", "entryInvalid". |
| `accountCreated` | OPTIONAL | New creation date of the linked bank account. |
| `accountNumber` | OPTIONAL | New account number. |
| `accountType` | OPTIONAL | New account type. |
| `branchCode` | OPTIONAL | New branch code. |
| `name` | OPTIONAL | New holder name. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id (key value) of the Pix key entity. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. |
| `ids` | OPTIONAL | Filter by Pix key ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filter logs by log types. |

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

**Parameters**

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

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

## Available Languages

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

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