Deposits

Deposit records help integrators reconcile settlement activity to funded bank movement.

Use Deposits when you need to confirm whether a settlement has been funded, review the funded amount, identify the settlement associated with a deposit, or match a deposit back to merchant settlement activity.

Deposits are returned through Bead APIs. They are not a settlement file, statement, or custom export.

When to use Deposits

Use Deposits when you need to:

• Confirm whether settlement funds have been dispatched or paid.

• Review the amount associated with a funded deposit.

• Match a deposit to a settlement record.

• Filter deposit activity by merchant, settlement, date range, status, or method.

• Support merchant or partner questions about funded settlement activity.

• Reconcile deposited funds to your internal ledger or accounting system.

For payment history and transaction-level search, use Reporting APIs first. For settlement grouping and payment-level settlement detail, use Merchant Settlements and Payment Settlements. For funded movement tied to settlement, use Deposits.

How it works

A deposit represents funding activity associated with a settlement.

A typical deposit reconciliation flow is:

1. Start with a merchant, settlement, or date range.

2. Retrieve deposit records using the relevant filters.

3. Review the deposit status, amount, method, and settlement identifier.

4. Use the settlement identifier to connect the deposit back to settlement and batch activity.

5. Use payment settlement details when you need to reconcile the deposit back to individual payments.

Available endpoints

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

Shared query parameters

The deposit list and settlement deposit endpoints support filters that help narrow results for reconciliation and support workflows.

Common filters include:

• From

• To

• Status

• Method

• MerchantIds

• SettlementIds

• Page

• PageSize

• SortBy

• SortDirection

From and To use date values. MerchantIds and SettlementIds accept arrays of IDs. Page defaults to 0, and PageSize defaults to 50 with a maximum of 100.

Use date, merchant, and settlement filters together when reconciling a known merchant or settlement period. Use status and method filters when reviewing funding state or deposit method.

Deposit fields

A deposit record can include:

Field	Type	Description
id	string	Unique deposit identifier.
merchantId	string	Merchant associated with the deposit record.
destinationMerchantId	string	Destination merchant for the funded movement.
settlementId	string	Settlement associated with the deposit.
status	string	Current deposit status. Expected values include dispatched, paid, and error.
amount	number	Deposit amount. Returned as a numeric value.
feeAmount	number	Fee amount associated with the deposit, when applicable. Returned as a numeric value.
method	string	Deposit method. Expected values include ach and wire.
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	Transfer type associated with the deposit. Values include sale, refund, and chargeback.

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

Deposit status

Deposit status indicates the current funding state of the deposit.

Supported status values include:

• dispatched

• paid

• error

Use the status field to determine whether a deposit has been sent, completed, or requires review.

Deposit method

Deposit method identifies the funding rail used for the deposit.

Supported method values include:

• ach

• wire

Transfer type

Transfer type identifies the kind of funding movement associated with the deposit.

Supported transfer type values include:

• sale

• refund

• chargeback

Relationship to Settlement

Deposits are part of the broader Settlement model.

Use Settlement records and Merchant Settlements to understand how payments were grouped and calculated. Use Payment Settlements when you need payment-level settlement detail. Use Deposits when you need to confirm funded movement tied to a settlement.

A common pattern is:

1. Use Reporting APIs to find completed payments.

2. Use Settlement APIs to understand how those payments were grouped.

3. Use Payment Settlements for payment-level settlement detail.

4. Use Deposits to confirm funded movement and deposit status.

Files, exports, and API reporting

Deposit data is available through Bead APIs.

Most integrations should use the documented API responses for deposit reconciliation. If a partner needs a custom export or file delivery process, that should be handled as a separate implementation requirement with Bead.

Typical integration flows

Reconcile deposits for a merchant

Goal: show deposit activity for one merchant.

High level steps:

1. Identify the merchant ID.

2. Retrieve deposits filtered by merchant ID and date range.

3. Display deposit amount, status, method, settlement ID, and dispatched date.

4. Link each deposit to the related settlement detail where available.

Reconcile a settlement to a deposit

Goal: confirm whether a settlement has been funded.

High level steps:

1. Start with a settlement ID.

2. Retrieve deposits filtered by settlement ID or use the settlement deposits endpoint.

3. Review deposit status, amount, method, transfer type, and dispatched date.

4. Compare the deposit amount and fee amount to the settlement record.

Investigate a funding question

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

High level steps:

1. Search deposits by merchant, settlement, or date range.

2. Review the deposit status and dispatched date.

3. Confirm the deposit method, transfer type, and masked bank reference.

4. Use the settlement ID to review the related settlement and payment-level detail.

Next steps

• Use Merchant Settlements for merchant-level settlement batches.

• Use Payment Settlements for payment-level settlement detail.

• Use Reporting APIs when you need payment history before reviewing settlement.

• Use Settlement status codes in the Reference Guide when interpreting settlement states.