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

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 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 when you need payment history before reviewing deposits.