Residual Reporting

Residual reporting gives partners visibility into the fee revenue Bead collected across their merchant portfolio during a settlement period.

Bead operates on a net daily settlement model: fees are withheld from each merchant's gross payment volume before funds are settled into the merchant's account. Those fees accumulate through the settlement period and are reconciled at month end.

This page explains where revenue and fee data lives in the Bead API and how to assemble it for a monthly residual report.

How Bead retains fees

When a payment settles:

1. Bead groups completed payments into daily batches.

2. Each batch carries a grossFundableAmount (total payment volume) and a totalFees amount (transaction-based fees withheld).

3. At the end of the settlement period, Bead closes the batches into a Settlement record.

4. The Settlement record captures totalTransactionFees (sum of all batch fees for the period), depositFees (the ACH or wire fee for funding), and any adjustments (chargebacks, refunds, platform fees, etc.).

5. Bead funds the merchant the netFundableAmount — gross minus all fees and adjustments.

6. The retained fees are reconciled at month end and made available to the partner for reporting and payout purposes.

Fee and revenue fields by entity

Field	Entity	API field	Notes
Gross payment volume	SettlementResponse	grossFundableAmount	Total payment volume before any deductions
Transaction fees (period total)	SettlementResponse	totalTransactionFees	Sum of all per-transaction fees across batches in the period
Transaction fees (per batch)	PaymentBatchResponse	totalFees	Per-batch subtotal; rolls up to totalTransactionFees
Deposit / funding fee	SettlementResponse	depositFees	ACH or wire fee for the funding transfer
Deposit / funding fee	DepositResponse	feeAmount	Same fee, visible at the deposit record level
Adjustments	SettlementResponse	adjustments[]	Chargebacks, refunds, platform fees, holdbacks, and others
Net payout to merchant	SettlementResponse	netFundableAmount	What the merchant received after all deductions

Transaction fees are not tracked at the individual payment level. They are aggregated at the batch level (totalFees) and at the settlement level (totalTransactionFees). If you need per-payment fee detail, contact Bead — this is not currently available in the standard API responses.

Recommended API pattern for monthly residual reporting

Step 1: Identify the settlement period

Determine the date range for the reporting month. Use From and To date filters on the /Settlements endpoint.

Step 2: Retrieve settlements for the period

GET /Settlements?MerchantIds[]=<merchantId>&From=<startDate>&To=<endDate>

Retrieve one page at a time. Use Page and PageSize (up to 100 per page). Repeat until you have all records for the period.

For partners with many merchants, pass an array of MerchantIds to filter to the merchants in your portfolio.

Step 3: For each settlement, capture the revenue and fee fields

From each SettlementResponse, collect:

• merchantId

• id (settlement ID)

• grossFundableAmount

• totalTransactionFees

• depositFees

• adjustments — iterate the array and note type and amount for each

• netFundableAmount

• targetPayoutDate or settlementDate

• status — filter to dispatched or paid to include only funded settlements

Step 4: Optionally validate against batch-level fees

To cross-check settlement-level totals against batch-level detail:

GET /Settlements/{id}/batches

Sum totalFees across all batches for the settlement. This should equal totalTransactionFees on the settlement record. If there is a discrepancy, contact Bead support.

Step 5: Optionally validate deposit fees

GET /Settlements/{id}/deposits

The feeAmount on the deposit record should match depositFees on the settlement. Use this when auditing funding fees.

Adjustments

Adjustments represent non-transaction items that modify the net settlement amount. They are included in the adjustments array on the SettlementResponse and should be reviewed when assembling a complete revenue picture for the period.

Adjustment type	Description
chargeback	Chargeback amount recovered from the merchant
chargebackFee	Fee assessed for a chargeback
refund	Refund amount recovered from the merchant
achReject	ACH reject recovery
holdback	Reserve holdback
reversal	Reversal amount
complianceFine	Compliance fine assessed against the settlement
platformFee	Platform fee assessed against the settlement
equipmentFee	Equipment fee assessed against the settlement
adjustmentCredit	Credit applied to the settlement
currencyConversionFee	Currency conversion fee
networkAssessmentFee	Network assessment fee
depositCorrection	Correction to a prior deposit
taxWithholding	Tax withholding amount

Review the note field on each adjustment when present — it provides additional context for the specific item.

Example: fee data for a single merchant over one month

Assume Bead closed three settlements for a merchant during the month.

Settlement	Gross	Transaction Fees	Deposit Fee	Adjustments	Net to Merchant
S-001	$20,000	$480	$0.25	-$150 (chargeback)	$19,669.75
S-002	$18,000	$432	$0.25	none	$17,567.75
S-003	$12,000	$288	$0.25	+$50 (credit)	$11,761.75

For the period, the data available to the partner is:

• Total gross volume: $50,000

• Total transaction fees: $1,200

• Total deposit fees: $0.75

• Net adjustments: -$100 (chargeback net of credit)

• Total net to merchant: $49,000

This is the revenue and fee data Bead surfaces per merchant per settlement period. How partners apply this data to their internal payout schedules is handled outside the Bead API.

Pagination and data completeness

The /Settlements endpoint returns up to 100 records per page. For partners with large merchant portfolios or long reporting windows, paginate fully before computing totals.

Check that all settlements in the period have a status of dispatched or paid before including them in a final report. Settlements in hold or cleared state have not yet been funded and may change before month end.

Multi-merchant portfolios

Use the MerchantIds array filter to limit results to the merchants in your portfolio. Retrieve and aggregate per merchant to build a complete revenue picture across your book for the period.

Next steps

• Use Settlements to retrieve settlement records and fee fields.

• Use Batches to validate batch-level fee totals.

• Use Deposits to validate deposit fees.

• Use Merchant Settlements for the merchant-level settlement event view.

• Use Reporting APIs when you need the underlying payment activity for a period.

• Contact Bead if you need per-payment fee detail or a custom settlement export.