> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/settlement/deposits.md).

# Deposits

Deposits represent the funded bank movement associated with a settlement.

Use Deposits when you need to confirm whether a settlement has been funded, review the deposited amount and fee, match a deposit to a settlement record, or answer merchant questions about when funds arrived.

For payment history and transaction-level search, use [Reporting](/reporting.md) first. For the settlement-level fee and net amount, use [Settlements](/settlement/settlements.md). For payment-level settlement detail, use [Payment Settlement Detail](/settlement/payment-settlement-detail.md).

#### When to use Deposits

Use Deposits when you need to:

* Confirm whether settlement funds have been dispatched or paid.
* Review the funded amount and deposit fee for a settlement.
* Validate that `feeAmount` on the deposit matches `depositFees` on the parent Settlement.
* Match a deposit to a settlement record.
* Filter deposit activity by merchant, settlement, date range, status, or method.
* Investigate a merchant or partner question about funded settlement activity.
* Reconcile deposited funds to your internal ledger or accounting system.

#### How it works

When Bead funds a settlement, it creates a Deposit record representing the bank transfer to the merchant's account. The deposit carries the funded amount, the `feeAmount` for the ACH or wire transfer, and a reference back to the parent `settlementId`.

The `feeAmount` on the deposit record is the same fee captured as `depositFees` on the Settlement. Use this to cross-validate the two records during reconciliation.

A typical deposit reconciliation flow:

1. Start with a merchant, settlement ID, or date range.
2. Retrieve deposit records using the relevant filters.
3. Review deposit status, amount, fee amount, method, and dispatched date.
4. Use `settlementId` to connect the deposit back to the parent settlement record.
5. Compare `feeAmount` to `depositFees` on the settlement to confirm they match.

#### Available endpoints

| Scope               | Path                           | Description                                                                                                         |
| ------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Deposit list        | GET /Deposits                  | Returns deposit records with filters for date range, status, method, merchant, settlement, pagination, and sorting. |
| Single deposit      | GET /Deposits/{id}             | Returns one deposit record by deposit ID.                                                                           |
| Settlement deposits | GET /Settlements/{id}/deposits | Returns deposit records associated with a settlement.                                                               |

#### Query parameters

| Parameter     | Type             | Description                                    |
| ------------- | ---------------- | ---------------------------------------------- |
| From          | date             | Start of the date range filter.                |
| To            | date             | End of the date range filter.                  |
| Status        | string           | Filter by deposit status. See Deposit status.  |
| Method        | string           | Filter by deposit method: ach or wire.         |
| MerchantIds   | array of strings | Filter by one or more merchant IDs.            |
| SettlementIds | array of strings | Filter by one or more settlement IDs.          |
| Page          | integer          | Page number. Defaults to 0.                    |
| PageSize      | integer          | Results per page. Defaults to 50, maximum 100. |
| SortBy        | string           | Field to sort by.                              |
| SortDirection | string           | Sort direction: asc or desc.                   |

#### Deposit fields

| Field                 | Type             | Description                                                                       |
| --------------------- | ---------------- | --------------------------------------------------------------------------------- |
| id                    | string           | Unique deposit identifier.                                                        |
| merchantId            | string           | Merchant associated with the deposit.                                             |
| destinationMerchantId | string           | Destination merchant for the funded movement.                                     |
| settlementId          | string           | Settlement associated with this deposit.                                          |
| status                | string           | Current deposit status. See Deposit status.                                       |
| amount                | number or string | Funded amount transferred to the merchant.                                        |
| feeAmount             | number or string | Fee for the ACH or wire transfer. Matches `depositFees` on the parent Settlement. |
| method                | string           | Funding rail used. See Deposit method.                                            |
| maskedRoutingNumber   | string           | Masked routing number for reconciliation and support reference.                   |
| maskedAccountNumber   | string           | Masked account number for reconciliation and support reference.                   |
| created               | date-time        | Date and time the deposit record was created.                                     |
| updated               | date-time        | Date and time the deposit record was last updated.                                |
| dispatchedDate        | date-time        | Date and time the deposit was dispatched.                                         |
| transferType          | string           | Type of funding movement. See Transfer type.                                      |

Masked bank fields are provided for reconciliation and support reference. Full bank account details are not returned in deposit responses.

#### Deposit status

| Value      | Description                                       |
| ---------- | ------------------------------------------------- |
| dispatched | Deposit has been sent to the merchant's bank.     |
| paid       | Deposit has been confirmed as received.           |
| error      | Deposit encountered an error and requires review. |

#### Deposit method

| Value | Description                          |
| ----- | ------------------------------------ |
| ach   | Funds transferred via ACH.           |
| wire  | Funds transferred via wire transfer. |

#### Transfer type

| Value      | Description                                         |
| ---------- | --------------------------------------------------- |
| sale       | Standard settlement funding for completed payments. |
| refund     | Funding movement associated with a refund.          |
| chargeback | Funding movement associated with a chargeback.      |

#### Fee validation

The `feeAmount` on a deposit record should always match the `depositFees` field on the parent Settlement. Use this check when auditing deposit fees during reconciliation.

If there is a discrepancy, contact Bead support.

#### Typical integration flows

**Reconcile deposits for a merchant**

Goal: show deposit activity for a merchant.

1. Retrieve deposits filtered by `MerchantIds` and date range.
2. Display deposit amount, fee amount, status, method, settlement ID, and dispatched date.
3. Link each deposit to the related settlement for further detail.

**Confirm a settlement was funded**

Goal: verify that a settlement has been paid out.

1. Use `GET /Settlements/{id}/deposits` to retrieve deposits for the settlement.
2. Review deposit status, amount, `feeAmount`, method, and `dispatchedDate`.
3. Confirm `feeAmount` matches `depositFees` on the settlement record.

**Investigate a funding question**

Goal: answer a merchant or partner question about a deposit.

1. Search deposits by merchant, settlement ID, or date range.
2. Review deposit status and dispatched date.
3. Confirm the deposit method, transfer type, and masked bank reference.
4. Use `settlementId` to pull the related settlement and batch detail if needed.

#### Next steps

* Use [Settlements](/settlement/settlements.md) for the period-level fee rollup, adjustments, and net fundable amount.
* Use [Residual Reporting](/settlement/residual-reporting.md) for guidance on how deposit fees factor into monthly residual calculations.
* Use [Batches](/settlement/batches.md) to review grouped payment activity behind a settlement.
* Use [Payment Settlement Detail](/settlement/payment-settlement-detail.md) for payment-level settlement context and to trace payments through the settlement lifecycle.
* Use [Reporting](/reporting.md) when you need payment history before reviewing deposits.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/settlement/deposits.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.