# Deposit

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

### The Deposit object

**Attributes**

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

### List Deposits

`GET /v2/deposit`

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

**Parameters**

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

**Request**

```python
import starkbank

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

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

**Response**

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

### Get a Deposit

`GET /v2/deposit/:id`

Get a single Deposit by its id.

**Parameters**

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

**Request**

```python
import starkbank

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

print(deposit)
```

**Response**

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

### Update a Deposit

`PATCH /v2/deposit/:id`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the deposit. Example: '5155165527080960'. |
| `amount` | REQUIRED | The new amount of the Deposit. If the amount = 0 the Deposit will be fully reversed |

**Request**

```python
import starkbank

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

print(deposit)
```

**Response**

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

### List Deposit Logs

`GET /v2/deposit/log`

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

**Parameters**

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

**Request**

```python
import starkbank

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

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

**Response**

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

### Get a Deposit Log

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

Get a single deposit log by its id.

**Parameters**

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

**Request**

```python
import starkbank

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

print(log)
```

**Response**

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

### Get a reversed Deposit Log PDF

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

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

**Parameters**

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

**Request**

```python
import starkbank

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

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

## Available Languages

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

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