# Deposit

Learn how to query and manage Deposits on the Stark Bank platform.

Deposits represent passive cash-ins: money that has already been received in your Stark Bank account from external transfers or payments. A Deposit is created automatically when the funds arrive — for example, when someone pays one of your Dynamic BR Codes — so this guide is about tracking and managing amounts you have already received, not about issuing charges.

If you want to charge your customers instead, check the Invoice Get Started or the Pix QR Code Get Started.

For the complete list of endpoints and parameters, check the Deposit API Reference.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

DepositMoney already received in your account — query it, track its life cycle and reverse it partially or fully when needed.

## Setup

For each environment (Sandbox or Production):

1. Create an account at Stark Bank.

2. Create a webhook with the following subscription to receive events at your desired URL:

deposit

2.1. Via Internet Banking:

Integrations > Webhook > New Webhook

2.2. Via API:

Use the POST /webhook route to create the webhook

## Deposit Overview

Deposits represent passive cash-ins received by your account from external transfers or payments. They are created automatically when the money arrives in your account — you never create a Deposit directly.

Use the tags field to match deposits to your own entities. For example, deposits created by Dynamic BR Code payments carry a tag in the format "dynamic-brcode/{uuid}", where {uuid} is the UUID of the code that was paid.

### The Deposit object

**Parameters**

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

### Deposit Status

Each deposit has a status that can change over time according to its life cycle:

| Status | Description |
| --- | --- |
| Created | You received a deposit in your account. |
| Voided | You fully returned the deposit. |

### The Deposit Logs

Every time either you or Stark Bank makes a change to a Deposit, we create a Log. Logs are pretty useful for understanding the life cycle of each Deposit and the changes that happened to it. Here you can see the flow of possible logs:

A Deposit can be either partially or fully reversed back to its payer. Multiple reversals can be made for the same deposit and each time, the following flow of logs will occur:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Deposit was successfully received in your Stark Bank account. |
| Credited | Created | The Deposit payment was credited to your account. |
| Voided | Voided | The Deposit was fully returned. |
| Reversing | Created | A reversal for the Deposit is being processed. |
| Sending | Created | The reversal is being sent to the banking network. |
| Sent | Created | The reversal was sent to the banking network. |
| Failed | Created | The reversal failed. |
| Reversed | Created | The Deposit was partially or fully reversed to the payer. |
| Refunded | Created | The reversal was refunded back to you after failing. |

### Listing Deposits

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

Use the optional parameters to narrow the search: after and before for the creation date, status, tags and ids.

**Response**

```python
Deposit(
    account_number=1010101010101010,
    account_type= "payment",
    amount=4000,
    bank_code=20018183,
    branch_code=0001,
    created=2023-02-06 22:14:58.555321,
    fee=0,
    id=4638572095847362,
    name=Jon Snow,
    status=created,
    tags=['dynamic-brcode/80b0688d05934971a6b8ecd86cde69f2'],
    tax_id=012.345.678-90,
    transaction_ids=['6532871094857362'],
    type=pix,
    updated=2023-02-06 22:14:58.555321
)
```

### Getting a Deposit

You can retrieve a single Deposit by its ID to check its amount, status, payer information, and tags.

### Reversing Partially a Deposit

To partially reverse a Deposit, you need to PATCH the deposit amount to a lower value. The difference between the original amount and the new amount will be reversed to the payer.

For example, if a Deposit was credited with an amount of 10000 (R$ 100.00) and you patch the amount to 3000 (R$ 30.00), it means you reversed 7000 (R$ 70.00) back to the payer.

While the reversal is being processed, the deposit status remains created.

### Reversing Fully a Deposit

To fully reverse a Deposit, you need to PATCH the deposit amount to 0. This will reverse the entire amount back to the payer.

For example, if a Deposit was credited with an amount of 10000 (R$ 100.00) and you patch the amount to 0, the full 10000 (R$ 100.00) will be reversed to the payer.

After the full reversal is completed, the deposit status changes to voided.

### Receiving Deposit Webhooks

After setting up a webhook subscription for deposit, Stark Bank will send a POST request to your registered URL every time a Deposit is created or updated.

Use the tags field in the webhook payload to match the deposit to your own entities — for example, a deposit created by a Dynamic BR Code payment carries the "dynamic-brcode/{uuid}" tag.

---

## Other Languages

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