> 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](https://developers.bead.xyz/reporting) first. For the settlement-level fee and net amount, use Settlements. For payment-level settlement detail, use Payment Settlement Detail.

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

#### When a deposit appears

A deposit record does not exist until the payout for the settlement is dispatched. A settlement is created earlier in the day than its payout is sent, so there is a window, usually the morning and early afternoon Eastern Time, in which a new settlement has no deposit yet.

During that window, `GET /Settlements/{id}/deposits` returns a successful response with an empty list. The empty list does not mean the settlement was skipped, failed, or left unfunded. It means the payout has not been dispatched yet. The endpoint does not return a separate "not yet dispatched" status.

The same is true of `GET /Deposits` with the `SettlementIds` filter.

A typical day on a given settlement looks like this:

1. The settlement record is created.
2. The payout is dispatched later in the day, and the deposit record is created with status `dispatched`.
3. The deposit moves to `paid` and the settlement moves to `paid` once the bank movement is confirmed, usually the same afternoon or evening.

Exact times can change, so do not hardcode a schedule.

When you design a sync job:

* Do not treat an empty deposit list as a final answer. Treat it as "not yet available" and read again later.
* Prefer to read deposits only after the settlement `status` is `paid`, instead of reading at a fixed time of day.
* If you read on a schedule, run the job late in the day Eastern Time or the following morning, and re-check any settlement that has no deposit yet.
* Do not mark a settlement as missing a deposit until the settlement is `paid` and a later read still returns no deposit. If that happens, contact Bead support with the `settlementId`.

#### More than one deposit per settlement

A settlement can have more than one deposit record. If a deposit ends in `error`, a later deposit for the same settlement can follow it. The earlier record keeps its `error` status, and the later record has its own `id`, `status`, and `dispatchedDate`. For example, a single settlement can show one deposit with status `error` and a second deposit with status `paid`.

When you reconcile:

* Retrieve all deposits for the settlement with `GET /Settlements/{id}/deposits`, not only the first record.
* Treat the settlement as funded when it has a deposit with status `paid`. An earlier `error` record does not by itself mean the settlement was left unfunded.
* Expect more than one record per `settlementId` when you list deposits with `GET /Deposits` using the `SettlementIds` filter.

The API does not currently return a failure reason for a deposit with status `error`. If you need the cause, contact Bead support with the deposit `id` and `settlementId`.

#### 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. Returns an empty list until the payout is dispatched.         |

#### 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. A later deposit for the same settlement can follow it. See the section above. |

#### 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. Wait until the settlement `status` is `paid`, or until the payout has been dispatched. An empty deposit list before then is expected.
2. Use `GET /Settlements/{id}/deposits` to retrieve deposits for the settlement.
3. Review deposit status, amount, `feeAmount`, method, and `dispatchedDate` on every record returned.
4. Confirm the settlement has a deposit with status `paid`.
5. 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 for the period-level fee rollup, adjustments, and net fundable amount.
* Use Residual Reporting for guidance on how deposit fees factor into monthly residual calculations.
* Use Batches to review grouped payment activity behind a settlement.
* Use Payment Settlement Detail for payment-level settlement context and to trace payments through the settlement lifecycle.
* Use [Reporting](https://developers.bead.xyz/reporting) 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
