Settlement data and deposit reconciliation
This FAQ explains what settlement and deposit data Bead provides for reconciliation.
Use this page when you need to understand whether settlement data is available as an API response, a file, or a bank deposit reference, and how to connect a funded deposit back to settlement records, batches, and payments.
Does Bead provide a settlement file?
Bead exposes settlement, batch, deposit, and payment-level settlement data through APIs.
The standard integration path is API-based reconciliation. Bead does not require integrators to consume provider-level settlement files or use a bank deposit reference as the only reconciliation source.
If a partner needs a custom settlement export or file delivery process, that should be handled as a separate implementation requirement with Bead.
Is the bank deposit enough for reconciliation?
A bank deposit confirms that funds moved to the destination account, but it should not be treated as the only source of reconciliation detail.
For reconciliation, use the Bead deposit record, settlement record, batch records, and payment-level settlement records. These API records provide the identifiers and amounts needed to connect a funded movement back to the underlying settlement and payment activity.
What data is included with a deposit?
A deposit record represents funded movement associated with settlement.
A deposit record can include:
id
Unique deposit identifier.
merchantId
Merchant associated with the deposit record.
destinationMerchantId
Destination merchant for the funded movement.
settlementId
Settlement associated with the deposit.
status
Current deposit status.
amount
Deposit amount.
feeAmount
Fee amount associated with the deposit, when applicable.
method
Deposit method. Exactly two values: ach or wire, lowercase.
maskedRoutingNumber
Masked routing number for reconciliation and support reference.
maskedAccountNumber
Masked account number for reconciliation and support reference.
created
Date and time the deposit record was created.
updated
Date and time the deposit record was last updated.
dispatchedDate
Date and time the deposit was dispatched.
transferType
Type of transfer associated with the deposit.
Deposit status values can include:
dispatchedpaiderror
Deposit method values are:
achwire
Match on the lowercase values exactly. The same values are accepted by the Method filter on GET /Deposits and GET /Settlements/{id}/deposits.
Transfer type values can include:
salerefundchargeback
Full bank account and routing details are not returned in deposit responses. Deposit responses use masked bank fields for support and reconciliation reference.
What fields are in a settlement record?
A settlement record provides the top-level settlement view.
A settlement record can include:
id
Unique settlement identifier.
merchantId
Merchant associated with the settlement.
type
Settlement category.
networkTypes
Network types included in the settlement.
status
Current settlement status.
holdReason
Reason the settlement is held. Null unless status is hold.
batchIds
Batch IDs included in the settlement.
batchCount
Number of batches included in the settlement, as an integer.
payoutId
Payout identifier for the settlement, when one has been assigned. Nullable.
grossFundableAmount
Gross fundable amount before fees and adjustments.
totalTransactionFees
Total transaction fees included in the settlement.
depositFees
Deposit fees included in the settlement.
totalFees
Total fees for the settlement, the rolled-up fee figure used in the gross-to-net math.
adjustments
Adjustments applied to the settlement. Each adjustment carries type, note, and netAdjustment.
netAdjustmentTotal
Net total of all adjustments applied to the settlement.
netFundableAmount
Net fundable amount after fees and adjustments.
outgoingAchIds
Outgoing ACH identifiers associated with the settlement, as an array of strings.
settlementDate
Date and time the settlement was completed, when available. Nullable.
created
Date and time the settlement record was created.
updated
Date and time the settlement record was last updated.
Settlement status values can include:
clearedholddispatchedpaid
The gross-to-net arithmetic can be followed entirely from this record: start at grossFundableAmount, apply totalFees (of which totalTransactionFees and depositFees are the components), apply netAdjustmentTotal (the net of the entries in adjustments), and arrive at netFundableAmount.
There is no target or projected payout date on the settlement record. Use settlementDate for settlement timing, and payoutId plus outgoingAchIds to tie the settlement to the outbound movement.
How do I reconcile a deposit back to payments?
A typical reconciliation flow is:
Start with the deposit record.
Use the deposit's
settlementIdto retrieve the related settlement record.Review the settlement record's
batchIds,batchCount,grossFundableAmount,totalTransactionFees,depositFees,totalFees,adjustments,netAdjustmentTotal, andnetFundableAmount.Retrieve the related batch records to identify grouped payment activity.
Use payment-level settlement records when you need to connect the settlement back to individual payments.
Use Reporting APIs when you need payment history, tender type, status, reference, terminal, or date-range filters.
If the settlement status is hold, read holdReason for the explanation before escalating.
Which APIs should I use?
Use Deposits when you need the funded movement record.
Use Settlement Records when you need the top-level settlement event.
Use Batches when you need to understand which payments were grouped together.
Use Payment Settlement Detail when you need payment-level settlement detail.
Use GET /Merchants/{merchantId}/settlements when you need the settlement history for a single merchant.
Use Reporting when you need payment history before reviewing settlement.
Related pages
Last updated